Table of contents
For other information, see the Ghostscript overview.
From what I understand and how I did it previously you need to install 'homebrew', this is essentially a package manager for Mac. It is very similar in functionality to Linux package managers. A package manager should look for all other libraries and support files that are required to make the application (package) run correctly on your. Analytics cookies. We use analytics cookies to understand how you use our websites so we can make them better, e.g. They're used to gather information about the pages you visit and how many clicks you need to accomplish a task.
WARNING: The API described in this document is subject to changes infuture releases, possibly ones that are not backward compatible with whatis described here.
What is the Ghostscript Interpreter API?
The Ghostscript interpreter can be built as a dynamic link library(DLL) on Microsoft Windows, as a shared object on theLinux, Unix and MacOS X platforms. With some changes, it could be builtas a static library. This document describes the Application ProgrammingInterface (API) for the Ghostscript interpreter library.This should not be confused with theGhostscript library which provides a graphicslibrary but not the interpreter.
This supercedes the old DLL interface.
To provide the interface described in theusage documentation, a smaller independentexecutable loads the DLL/shared object.This executable must provide all the interaction with the windowing system,including image windows and, if necessary, a text window.
The Ghostscript interpreter library's name and characteristics differfor each platform:
- The Win32 DLL
gsdll32.dll
can be used by multiple programs simultaneously, but only oncewithin each process. - The OS/2 DLL
gsdll2.dll
hasMULTIPLE NONSHARED data segments and can be called by multiple programssimultaneously. - The Linux shared object
libgs.so
can be used by multiple programs simultaneously.
The source for the executable is in dw
*.* (Windows),dp
*.* (OS/2) and dx
*.* (Linux/Unix).See these source files for examples of how to use the DLL.
The source file dxmainc.c can also serve as an example of how to use theshared library component on MacOS X, providing the same command-line tool it doeson any linux, bsd or similar operating system.
At this stage, Ghostscript does not support multiple instancesof the interpreter within a single process.
Exported functions
The functions exported by the DLL/shared object are describedin the header file iapi.h
and are summarised below. Omitted from the summary arethe calling convention (e.g. __stdcall), details of returnvalues and error handling.
intgsapi_revision(gsapi_revision_t *pr, int len);
intgsapi_new_instance(void **pinstance, void *caller_handle);
voidgsapi_delete_instance(void *instance);
intgsapi_set_stdio_with_handle(void *instance, int(*stdin_fn)(void *caller_handle, char *buf, int len), int(*stdout_fn)(void *caller_handle, const char *str, int len), int(*stderr_fn)(void *caller_handle, const char *str, int len), void *caller_handle);
intgsapi_set_stdio(void *instance, int(*stdin_fn)(void *caller_handle, char *buf, int len), int(*stdout_fn)(void *caller_handle, const char *str, int len), int(*stderr_fn)(void *caller_handle, const char *str, int len));
intgsapi_set_poll_with_handle(void *instance, int(*poll_fn)(void *caller_handle), void *caller_handle);
intgsapi_set_poll(void *instance, int(*poll_fn)(void *caller_handle));
intgsapi_set_display_callback(void *instance, display_callback *callback);
intgsapi_register_callout(void *instance, gs_callout callout, void *callout_handle);
voidgsapi_deregister_callout(void *instance, gs_callout callout, void *callout_handle);
intgsapi_set_arg_encoding(void *instance, int encoding);
intgsapi_get_default_device_list(void *instance, char **list, int *listlen);
intgsapi_set_default_device_list(void *instance, const char *list, int listlen);
intgsapi_run_string_begin(void *instance, int user_errors, int *pexit_code);
intgsapi_run_string_continue(void *instance, const char *str, unsigned int length, int user_errors, int *pexit_code);
intgsapi_run_string_end(void *instance, int user_errors, int *pexit_code);
intgsapi_run_string_with_length(void *instance, const char *str, unsigned int length, int user_errors, int *pexit_code);
intgsapi_run_string(void *instance, const char *str, int user_errors, int *pexit_code);
intgsapi_run_file(void *instance, const char *file_name, int user_errors, int *pexit_code);
intgsapi_init_with_args(void *instance, int argc, char **argv);
intgsapi_exit(void *instance);
intgsapi_set_param(void *instance, const char *param, const void *value, gs_set_param_type type);
int gsapi_get_param(void *instance, const char *param, void *value, gs_set_param_type type);
intgsapi_enumerate_params(void *instance, void **iter, const char **key, gs_set_param_type *type);
intgsapi_add_control_path(void *instance, int type, const char *path);
intgsapi_remove_control_path(void *instance, int type, const char *path);
voidgsapi_purge_control_paths(void *instance, int type);
voidgsapi_activate_path_control(void *instance, int enable);
intgsapi_is_path_control_active(void *instance);
intgsapi_add_fs(void *instance, gsapi_fs_t *fs, void *secret);
voidgsapi_remove_fs(void *instance, gsapi_fs_t *fs, void *secret);
gsapi_revision()
This function returns the revision numbers and strings of the Ghostscriptinterpreter library; you should call it before any other interpreterlibrary functions to make sure that the correct version of theGhostscript interpreter has been loaded.
gsapi_new_instance()
Create a new instance of Ghostscript.This instance is passed to most other gsapi functions.The caller_handle is the default value that will be provided to callback functions.Unless Ghostscript has been compiled with the GS_THREADSAFEdefine, only one instance at a time is supported.Historically, Ghostscript has only supported a single instance; anyattempt to create more than one at a time would result in gsapi_new_instancereturning an error. Experimental work has been done to lift thisrestriction; if Ghostscript is compiled with the GS_THREADSAFE definethen multiple concurrent instances are permitted.
While the core Ghostscript devices are believed to be thread safenow, certain devices are known not to be (particularly the contribdevices). The makefiles currently make no attempt to exclude thesefrom builds. If you enable GS_THREADSAFE then you should check to ensurethat you do not rely on such devices (check for global variable use).
The first parameter, is a pointer to an opaque pointer ('void **
').The opaque pointer ('void *
') must be initialised to NULL
beforethe call to gsapi_new_instance()
. See Example 1.
gsapi_delete_instance()
Destroy an instance of Ghostscript.Before you call this, Ghostscript must have finished.If Ghostscript has been initialised, you must callgsapi_exit
beforegsapi_delete_instance
.
gsapi_set_stdio_with_handle()
Set the callback functions for stdio, together with thehandle to use in the callback functions.The stdin callback function should return the number ofcharacters read, 0 for EOF, or -1 for error.The stdout and stderr callback functions should returnthe number of characters written.
NOTE: These callbacks do not affect output device I/O whenusing '%stdout
' as the output file. In thatcase, device output will still be directed to the process 'stdout'file descriptor, not to the stdio callback.
gsapi_set_stdio()
Set the callback functions for stdio. The handle usedin the callbacks will be taken from the value passedto gsapi_new_instance
. Otherwise the behaviour of thisfunction matches gsapi_set_stdio_with_handle
.
gsapi_set_poll_with_handle()
Set the callback function for polling, together with the handle to passto the callback function. This function will only be called ifthe Ghostscript interpreter was compiled with CHECK_INTERRUPTS
as described in gpcheck.h
.The polling function should return zero if all is well, and returnnegative if it wants ghostscript to abort. This is oftenused for checking for a user cancel. This can also be used forhandling window events or cooperative multitasking.
The polling function is called very frequently during interpretation andrendering so it must be fast. If the function is slow, then using a counterto return 0 immediately some number of times can be used to reduce theperformance impact.
gsapi_set_poll()
Set the callback function for polling. The handle passed to thecallback function will be taken from the handle passed togsapi_new_instance
.Otherwise the behaviour of this function matchesgsapi_set_poll_with_handle
.
gsapi_set_display_callback()
This call is deprecated; please usegsapi_register_callout
to register a callout handler for thedisplay device in preference.Set the callback structure for the displaydevice. The handle passed in the callback functions is taken fromtheDisplayHandle
parameter (or NULL if there is nosuch parameter). If the display device is used,this must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.Seegdevdsp.h
for more details.
gsapi_register_callout()
This call registers a callout
handler.
gsapi_deregister_callout()
This call deregisters a callout
handlerpreviously registered with gsapi_register_callout
.All three arguments must match exactly for the callout handler tobe deregistered.
gsapi_set_arg_encoding()
Set the encoding used for the interpretation of all subsequent argssupplied via the gsapi interface on this instance. By default weexpect args to be in encoding 0 (the 'local' encoding for this OS).On Windows this means 'the currently selected codepage'. On Linux thistypically means utf8. This means that omitting to call this functionwill leave Ghostscript running exactly as it always has. Please notethat use of the 'local' encoding is now deprecated and should beavoided in new code.This must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.
set_default_device_list()
Set the string containing the list of default device names,for example 'display x11alpha x11 bbox'. Allows the callingapplication to influence which device(s) gs will try, in order,in it's selection of the default device.This must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.
get_default_device_list()
Returns a pointer to the current default device string.This must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.
gsapi_init_with_args()
Initialise the interpreter.This callsgs_main_init_with_args()
inimainarg.c
.See below for return codes.The arguments are the same as the 'C' main function:argv[0] is ignored and the user supplied argumentsare argv[1] to argv[argc-1].
gsapi_run_*()
The gsapi_run_*
functions are likegs_main_run_*
except that the error_object is omitted.If these functions return <= -100, either quit or a fatalerror has occured. You must call gsapi_exit()
next.The only exception is gsapi_run_string_continue()
which will return gs_error_NeedInput
if all is well.See below for return codes.The address passed in pexit_code
will be used to return theexit code for the interpreter in case of a quit or fatal error. Theuser_errors
argument is normally set to zero to indicate thaterrors should be handled through the normal mechanisms within theinterpreted code. If set to a negative value, the functions will returnan error code directly to the caller, bypassing the interpretedlanguage. The interpreted language's error handler is bypassed, regardless ofuser_errors
parameter, for the gs_error_interrupt
generated when the polling callback returns a negativevalue. A positive user_errors
is treated the same as zero.
There is a 64 KB length limit on any buffer submitted to agsapi_run_*
function for processing. If you have morethan 65535 bytes of input then you must split it into smallerpieces and submit each in a separategsapi_run_string_continue()
call.
gsapi_exit()
Exit the interpreter.This must be called on shutdown ifgsapi_init_with_args()
has been called, and just beforegsapi_delete_instance()
.
gsapi_set_param()
Set a parameter.Broadly, this is equivalent to setting a parameter using -d
, -s
or -p
on the command line. This call cannot be made during a run_string
operation.Parameters in this context are not the same as 'arguments' as processed by gsapi_init_with_args
, but often the same thing can be achieved. For example, with gsapi_init_with_args
, we can pass '-r200
' to change the resolution. Broadly the same thing can be achieved by using gsapi_set_param
to set a parsed value of '<>
'.
Note, that internally, when we set a parameter, we perform an initgraphics
operation. This means that using set_param
other than at the start of a page is likely to give unexpected results.
Further, note that attempting to set a parameter that the device does not recognise will be silently ignored, and that parameter will not be found in subsequent gsapi_get_param
calls.
The type
argument dictates the kind of object that value
points to:
Combining a type value by ORRing it with the gs_spt_more_to_come
flag will cause the set_param
operation to be queued internally, but not actually be sent to the device. Thus a series of set_param
operations can be queued, for example as below:
This enables a series of set operations to be performed 'atomically'. This can be useful for performance, in that any reconfigurations to the device (such as page size changes or memory reallocations) will only happen when all the parameters are sent, rather than potentially each time each one is sent.
gsapi_get_param()
Get a parameter.Retrieve the current value of a parameter.If an error occurs, the return value is negative. Otherwise the return value is the number of bytes required for storage of the value. Call once with value = NULL
to get the number of bytes required, then call again with value
pointing to at least the required number of bytes where the value will be copied out. Note that the caller is required to know the type of value in order to get it. For all types other than string
, name
, and parsed
knowing the type means you already know the size required.
This call retrieves parameters/values that have made it to the device. Thus, any values set using the gs_spt_more_to_come
without a following call without that flag will not be retrieved. Similarly, attempting to get a parameter before gsapi_init_with_args
has been called will not list any, even if gsapi_set_param
has been used.
Attempting to read a parameter that is not set will return gs_error_undefined (-21)
. Note that calling gsapi_set_param
followed by gsapi_get_param
may not find the value, if the device did not recognise the key as being one of its configuration keys.
gsapi_enumerate_params()
Enumerate the current parameters.Call repeatedly to list out the current parameters. The first call should have *iter = NULL
. Subsequent calls should pass the same pointer in so the iterator can be updated. Negative return codes indicate error, 0 success, and 1 indicates that there are no more keys to read. On success, key
will be updated to point to a null terminated string with the key name that is guaranteed to be valid until the next call to gsapi_enumerate_params
. If type
is non NULL
then *type
will be updated to have the type of the parameter.
Note that only one enumeration can happen at a time. Starting a second enumeration will reset the first.
The enumeration only returns parameters/values that have made it to the device. Thus, any values set using the gs_spt_more_to_come
without a following call without that flag will not be retrieved. Similarly, attempting to enumerate parameters before gsapi_init_with_args
has been called will not list any, even if gsapi_set_param
has been used.
gsapi_add_control_path()
Add a (case sensitive) path to one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_remove_control_path()
Remove a (case sensitive) path from one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_purge_control_paths()
Clear all the paths from one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_activate_path_control()
Enable/Disable path control (i.e. whether paths are checked against permitted pathsbefore access is granted).See here for more information about permitted paths.
gsapi_is_path_control_active()
Query whether path control is activated or not.See here for more information about permitted paths.
gsapi_add_fs()
Adds a new 'Filing System' to the interpreter.This enables callers to implement their own filing systems. The systemstarts with just the conventional 'file' handlers installed, to allowaccess to the local filing system. Whenever files are to be openedfrom the interpreter, the file paths are offered around each registeredfiling system in turn (from most recently registered to oldest), untileither an error is given, or the file is opened successfully.Details of the gsapi_fs_t
are givenbelow.
gsapi_remove_fs()
Remove a previously registered 'Filing System' from the interpreter.Both the function pointers within the gs_fs_t
and thesecret value must match exactly.
Return codes
The gsapi_init_with_args
, gsapi_run_*
andgsapi_exit
functions return an integer code.
Return Codes from gsapi_*() | |
---|---|
CODE | STATUS |
0 | No errors |
gs_error_Quit | 'quit ' has been executed. This is not an error. gsapi_exit() must be called next. |
gs_error_interrupt | The polling callback function returned a negative value, requesting Ghostscript to abort. |
gs_error_NeedInput | More input is needed by gsapi_run_string_continue() . This is not an error. |
gs_error_Info | 'gs -h ' has been executed. This is not an error. gsapi_exit() must be called next. |
< 0 | Error |
<= gs_error_Fatal | Fatal error. gsapi_exit() must be called next. |
The gsapi_run_*()
functions do not flush stdio.If you want to see output from Ghostscript youmust do this explicitly as shown in the example below.
When executing a string with gsapi_run_string_*()
,currentfile
is the input from the string.Reading from %stdin
uses the stdin callback.
gsapi_fs_t
Each 'filing system' within gs is a structure of functionpointers; each function pointer gives a handler from taking adifferent named resource (a file, a pipe, a printer, a scratchfile etc) and attempts to open it.
If the filename (always given in utf-8 format) is recognised asbeing one that the filing system handles (perhaps by the prefix used),then it should open the file, fill in the gp_file
pointer and return 0.
If the filename is not-recognised as being one that the filingsystem handles, then returning 0 will cause the filename to beoffered to other registered filing systems.
If an error is returned (perhaps gs_error_invalidfileaccess),then no other filing system will be allowed to try to open thefile. This provides a mechanism whereby a caller to gsapi cancompletely control access to all files accessed via gp_fopen
at runtime.
Note, that while most file access within ghostscript will beredirected via these functions, stdio will not; see the existingmechanisms within Ghostscript for intercepting/replacing this.
- The
open_file
function pointer will be called whensomething (most often a call togp_fopen
) attempts toopen a file. - The
open_pipe
function pointer will be called whensomething (most often a call togp_popen
) attempts toopen a pipe.rfname
points to a 4K buffer in which theactual name of the opened pipe should be returned. - The
open_scratch
function pointer will be called whensomething (most often a call togp_open_scratch_file
orgp_open_scratch_file_rm
) attempts to open a temporary file.rfname
points to a 4K buffer in which the actual name ofthe opened pipe should be returned. Ifrm
is true, thenthe file should be set to delete itself when all handles to it are closed. - The
open_printer
function pointer will be called whensomething (most often a call togp_open_printer
) attemptsto open a stream to a printer. Ifbinary
is true, thenthe stream should be opened as binary; most streams will be binary bydefault - this has historical meaning on OS/2. - The
open_handle
function pointer will be called whensomething (most often a call via the postscript%handle%
IO device) attempts to open a Windows handle. This entry point willnever be called on non-Windows builds.
Any of these which are left as NULL will never be called; a filingsystem with all of the entries left as NULL is therefore pointless.
The most complex part of the implementation of these functionsis the creation of a gp_file
instance to return. There aresome helper functions for this, best explained by example.
Let us consider a hypothetical filing system that encrypts data asit is written, and decrypts it as it is read back. As each file isread and written the encryption/decryption routines will need to usesome state, carried between calls to the filing system. We thereforemight define a new type 'derived' from gp_file
as follows:
An implementation of gs_fs_t
for our 'crypt' filing systemmight then look like this:
In the above definition, we define a single handler, to cope with theopening of our input/output files. If we wanted to encrypt/decryptother files too (perhaps the temporary files we produce) we'd need todefine additional handlers (such as open_scratch
).
Our handler might look as follows:
The crucial part of this function is the definition of crypt_ops
,an instance of the gp_file_ops_t
type; a table of function pointersthat implement the actual operations required.
I would like to seed to at least 1.0+ ratio but I don't want to just leave seeding open like that. Www bittorret com.
These functions generally follow the same patterns as the posix functions that match them,and so in many cases we will describe these with references to such.Whenever these routines are called, they will be passed a gp_file
pointer.This pointer will have originated from the crypt_open_file
call, and so cansafely be cast back to a gp_file_crypt
pointer to allow private data to be accessed.
close(gp_file *)
- close the given file; free any storage in the crypt specific parts of
gp_file_crypt
,but not the gp_file_crypt structure itself. int getc(gp_file *)
- Get a single character from the file, returning it as an int (or -1 for EOF).Behaves like
fgetc(FILE *)
. int putc(gp_file *, int)
- Put a single character to the file, returning the character on success, orEOF (and setting the error indicator) on error.Behaves like
fgetc(FILE *)
. int read(gp_file *, size_t size, unsigned int count, void *buf)
- Reads count entries of size bytes the file into buf, returning the numberof entries read. Behaves like
fread(FILE *, size, count, buf)
. int write(gp_file *, size_t size, unsigned int count, const void *buf)
- Writes count entries of size bytes from buf into the file, returning thenumber of entries written. Behaves like
fwrite(FILE *, size, count, buf)
. int seek(gp_file *, gs_offset_t offset, int whence)
- Seeks within the file. Behaves like
fseek(FILE *, offset, whence)
. gs_offset_t tell(gp_file *)
- Returns the current offset within the file. Behaves like
ftell(FILE *)
. int eof(gp_file *)
- Returns 1 if we are at the end of the file, 0 otherwise. Behaves like
feof(FILE *)
. gp_file * dup(gp_file *, const char *mode)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like
fdup(FILE *)
. Leave NULL if not implemented. int seekable(gp_file *)
- Returns 1 if the file is seekable, 0 otherwise. Certain output devices willonly work with seekable files.
int pread(gp_file *, size_t count, gs_offset_t offset, void *buf)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like an atomic
fseek(FILE *, offset, 0)
andfread(FILE *, 1, count, buf)
.Akin topread
. int pwrite(gp_file *, size_t count, gs_offset_t offset, const void *buf)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like an atomic
fseek(FILE *, offset, 0)
andfwrite(FILE *, 1, count, buf)
.Akin topwrite
. int is_char_buffered(gp_file *file)
- Returns 1 if the file is character buffered, 0 otherwise. Used for handlingreading from terminals. Very unlikely to be used, so returning 0 all the timeshould be safe. Leave NULL to indicate 'always 0'.
void fflush(gp_file *file)
- Ensures that any buffered data is written to the file. Behaves like
fflush(FILE *)
.Leave NULL to indicate that no flushing is ever required. int ferror(gp_file *file)
- Returns non-zero if there has been an error, or 0 otherwise. Behaves like
ferror(FILE *)
. FILE * get_file(gp_file *file)
- Optional: Gets the FILE * pointer that backs this file. Required for a few devicesthat insist on working with FILE *'s direct. Generally safe to leave this set to NULL, and thosedevices will fail gracefully.
void clearerr(gp_file *file)
- Clear the error and EOF values for a file. Behaves like
clearerror(FILE *)
. gp_file * reopen(gp_file *f, const char *fname, const char *mode)
- Optional function, only used if the
gp_file
came from anopen_scratch
call; can be left as NULL if theopen_scratch
pointer is set to NULL.Reopen a stream with a different mode. Behaves likefreopen(fname, mode, FILE *)
.
Avghostscript For Macbook Pro
Callouts
Callouts are a mechanismfor the core code (specifically devices) to communicate with theuser of gsapi. This communication can take the form of passinginformation out vis-a-vis what devices are doing, or requestingconfiguration from the caller to affect exactly how the deviceitself works.
This is deliberately an extensible system, so exact details ofcallouts should be documented with the device in question. In generalhowever a callout handler will be of the form:
The callout_handle
value passed to the callout willbe the value passed in at registration. The device_name
should be a null-terminated string giving the name of the device(though care should be taken to cope with the case wheredevice_name
is NULL for potential future uses).The id
value will have a (device-specific) meaning; seethe documentation for the device in question for more details. Thesame id
value may be used to mean different things indifferent devices.Finally, size
and data
have calloutspecific meanings, but typically, data
will be a pointerto data block (which may either be uninitialised or wholly/partiallyinitialised on entry, and may be updated on exit), and size
will be the size (in bytes) of the block pointed to by data
.
A return value of -1 (gs_error_unknownerror
) meansthe callout was not recognised by the handler, and should be passedto more handlers. Other negative values are interpreted as standardGhostscript error values, and stop the propagation of the callout.Non-negative return codes mean the callout was handled and shouldnot be passed to any more registered callout handlers.
Example Usage
To try out the following examples in a development environment like Microsoft'sdeveloper tools or Metrowerks Codewarrior, create a new project, save the examplesource code as a .c file and add it, along with the Ghostscript dll or sharedlibrary. You will also need to make sure the Ghostscript headers are available, eitherby adding their location (the src directory in the Ghostscript sourcedistribution) to the project's search path, or by copying ierrors.h and iapi.h into thesame directory as the example source.
Example 1
Example 2
Example 3
Replace main() in either of the above with the following code,showing how you can feed Ghostscript piecemeal:
Example 4
When feeding Ghostscript piecemeal buffers, one can use the normaloperators to configure things and invoke library routines. For example,to parse a PDF file one could say:
and Ghostscript would open and process the file named 'example.pdf' asif it had been passed as an argument togsapi_init_with_args()
.
Multiple threads
The Ghostscript library should have been compiled with athread safe run time library.Synchronisation of threads is entirely up to the caller.The exported gsapi_*()
functions must be called from one thread only.
Standard input and output
When using the Ghostscript interpreter library interface, you have achoice of two standard input/output methods.
- If you do nothing, the 'C' stdio will be used.
- If you use
gsapi_set_stdio()
, all stdio will be redirected to the callback functions you provide. This would be used in a graphical user interface environment where stdio is not available, or where you wish to process Ghostscript input or output.
The callback functions are described iniapi.h
.
Display device
The display
device is available for use withthe Ghostscript interpreter library. While originally designedfor allowing screen display of rendered output from Ghostscript,this is now powerful enough to provide a simple mechanism forgetting rendered output suitable for use in all manner ofoutput scenarios, including printing.
Details of the API and options are given in the filegdevdsp.h
.This device provides you with access to the raster output ofGhostscript. It is the callers responsibility to copy this rasterto a display window or printer.
In order for this device to operate, it needs access to a structurecontaining a set of callback functions, and a callback handle (anopaque void *
that can be used by caller to locate itsown state). There are 2 ways that the device can get thisinformation, a legacy method, and a modern method.
The address of the callback structure, is providedusing gsapi_set_display_callback()
.This must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.
With this call, the callback handle is passed as NULL by default, but canbe overridden by using a parameter. We actively dislikethis way of working, as we consider passing addressesvia the command line distasteful. The handle can beset using
-sDisplayHandle=1234
Where '1234' is a string. The API was changed to use a stringrather than an integer/long value when support for 64 bit systemsarrived. A display 'handle' is often a pointer, and since thesecommand line options have to survive being processed by Postscriptmachinery, and Postscript only permits 32 bit number values, adifferent representation was required. Hence changing the valueto a string, so that 64 bit values can be supported. The stringformats allowed are:
1234
- implicit base 10
10#1234
- explicit base 10
16#04d2
- explicit base 16
The 'number string' is parsed by the display device to retrievethe number value, and is then assigned to the void pointerparameter 'pHandle' in the display device structure. Thus, fora trivial example, passing -sDisplayHandle=0
will resultin the first parameter passed to your display device callbacks being:(void *)0
.
The previous API, using a number value:
-dDisplayHandle=1234
is still supported on 32 bit systems, but will cause a 'typecheck'error on 64 bit systems, and is considered deprecated. It shouldnot be used in new code.
The preferred method is to register a callout handler usinggsapi_register_callout
.When this handler is called for the 'display'
device, with id = 0
(= DISPLAY_CALLOUT_GET_CALLBACK
),then data
should point to an empty gs_display_get_callback_t
block, with size = sizeof(gs_display_get_callback_t)
.
The handler should fill in the structure before returning,with a return code of 0.
Note, that the DisplayHandle
value is only consulted fordisplay device callbacks registered using the (legacy, now deprecated)gsapi_set_display_callback
API, not the preferredgsapi_register_callout
based mechanism.
Parameters in this context are not the same as 'arguments' as processed by gsapi_init_with_args
, but often the same thing can be achieved. For example, with gsapi_init_with_args
, we can pass '-r200
' to change the resolution. Broadly the same thing can be achieved by using gsapi_set_param
to set a parsed value of '<>
'.
Note, that internally, when we set a parameter, we perform an initgraphics
operation. This means that using set_param
other than at the start of a page is likely to give unexpected results.
Further, note that attempting to set a parameter that the device does not recognise will be silently ignored, and that parameter will not be found in subsequent gsapi_get_param
calls.
The type
argument dictates the kind of object that value
points to:
Combining a type value by ORRing it with the gs_spt_more_to_come
flag will cause the set_param
operation to be queued internally, but not actually be sent to the device. Thus a series of set_param
operations can be queued, for example as below:
This enables a series of set operations to be performed 'atomically'. This can be useful for performance, in that any reconfigurations to the device (such as page size changes or memory reallocations) will only happen when all the parameters are sent, rather than potentially each time each one is sent.
gsapi_get_param()
Get a parameter.Retrieve the current value of a parameter.If an error occurs, the return value is negative. Otherwise the return value is the number of bytes required for storage of the value. Call once with value = NULL
to get the number of bytes required, then call again with value
pointing to at least the required number of bytes where the value will be copied out. Note that the caller is required to know the type of value in order to get it. For all types other than string
, name
, and parsed
knowing the type means you already know the size required.
This call retrieves parameters/values that have made it to the device. Thus, any values set using the gs_spt_more_to_come
without a following call without that flag will not be retrieved. Similarly, attempting to get a parameter before gsapi_init_with_args
has been called will not list any, even if gsapi_set_param
has been used.
Attempting to read a parameter that is not set will return gs_error_undefined (-21)
. Note that calling gsapi_set_param
followed by gsapi_get_param
may not find the value, if the device did not recognise the key as being one of its configuration keys.
gsapi_enumerate_params()
Enumerate the current parameters.Call repeatedly to list out the current parameters. The first call should have *iter = NULL
. Subsequent calls should pass the same pointer in so the iterator can be updated. Negative return codes indicate error, 0 success, and 1 indicates that there are no more keys to read. On success, key
will be updated to point to a null terminated string with the key name that is guaranteed to be valid until the next call to gsapi_enumerate_params
. If type
is non NULL
then *type
will be updated to have the type of the parameter.
Note that only one enumeration can happen at a time. Starting a second enumeration will reset the first.
The enumeration only returns parameters/values that have made it to the device. Thus, any values set using the gs_spt_more_to_come
without a following call without that flag will not be retrieved. Similarly, attempting to enumerate parameters before gsapi_init_with_args
has been called will not list any, even if gsapi_set_param
has been used.
gsapi_add_control_path()
Add a (case sensitive) path to one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_remove_control_path()
Remove a (case sensitive) path from one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_purge_control_paths()
Clear all the paths from one of the lists of permitted paths for file access.See here for more information about permitted paths.
gsapi_activate_path_control()
Enable/Disable path control (i.e. whether paths are checked against permitted pathsbefore access is granted).See here for more information about permitted paths.
gsapi_is_path_control_active()
Query whether path control is activated or not.See here for more information about permitted paths.
gsapi_add_fs()
Adds a new 'Filing System' to the interpreter.This enables callers to implement their own filing systems. The systemstarts with just the conventional 'file' handlers installed, to allowaccess to the local filing system. Whenever files are to be openedfrom the interpreter, the file paths are offered around each registeredfiling system in turn (from most recently registered to oldest), untileither an error is given, or the file is opened successfully.Details of the gsapi_fs_t
are givenbelow.
gsapi_remove_fs()
Remove a previously registered 'Filing System' from the interpreter.Both the function pointers within the gs_fs_t
and thesecret value must match exactly.
Return codes
The gsapi_init_with_args
, gsapi_run_*
andgsapi_exit
functions return an integer code.
Return Codes from gsapi_*() | |
---|---|
CODE | STATUS |
0 | No errors |
gs_error_Quit | 'quit ' has been executed. This is not an error. gsapi_exit() must be called next. |
gs_error_interrupt | The polling callback function returned a negative value, requesting Ghostscript to abort. |
gs_error_NeedInput | More input is needed by gsapi_run_string_continue() . This is not an error. |
gs_error_Info | 'gs -h ' has been executed. This is not an error. gsapi_exit() must be called next. |
< 0 | Error |
<= gs_error_Fatal | Fatal error. gsapi_exit() must be called next. |
The gsapi_run_*()
functions do not flush stdio.If you want to see output from Ghostscript youmust do this explicitly as shown in the example below.
When executing a string with gsapi_run_string_*()
,currentfile
is the input from the string.Reading from %stdin
uses the stdin callback.
gsapi_fs_t
Each 'filing system' within gs is a structure of functionpointers; each function pointer gives a handler from taking adifferent named resource (a file, a pipe, a printer, a scratchfile etc) and attempts to open it.
If the filename (always given in utf-8 format) is recognised asbeing one that the filing system handles (perhaps by the prefix used),then it should open the file, fill in the gp_file
pointer and return 0.
If the filename is not-recognised as being one that the filingsystem handles, then returning 0 will cause the filename to beoffered to other registered filing systems.
If an error is returned (perhaps gs_error_invalidfileaccess),then no other filing system will be allowed to try to open thefile. This provides a mechanism whereby a caller to gsapi cancompletely control access to all files accessed via gp_fopen
at runtime.
Note, that while most file access within ghostscript will beredirected via these functions, stdio will not; see the existingmechanisms within Ghostscript for intercepting/replacing this.
- The
open_file
function pointer will be called whensomething (most often a call togp_fopen
) attempts toopen a file. - The
open_pipe
function pointer will be called whensomething (most often a call togp_popen
) attempts toopen a pipe.rfname
points to a 4K buffer in which theactual name of the opened pipe should be returned. - The
open_scratch
function pointer will be called whensomething (most often a call togp_open_scratch_file
orgp_open_scratch_file_rm
) attempts to open a temporary file.rfname
points to a 4K buffer in which the actual name ofthe opened pipe should be returned. Ifrm
is true, thenthe file should be set to delete itself when all handles to it are closed. - The
open_printer
function pointer will be called whensomething (most often a call togp_open_printer
) attemptsto open a stream to a printer. Ifbinary
is true, thenthe stream should be opened as binary; most streams will be binary bydefault - this has historical meaning on OS/2. - The
open_handle
function pointer will be called whensomething (most often a call via the postscript%handle%
IO device) attempts to open a Windows handle. This entry point willnever be called on non-Windows builds.
Any of these which are left as NULL will never be called; a filingsystem with all of the entries left as NULL is therefore pointless.
The most complex part of the implementation of these functionsis the creation of a gp_file
instance to return. There aresome helper functions for this, best explained by example.
Let us consider a hypothetical filing system that encrypts data asit is written, and decrypts it as it is read back. As each file isread and written the encryption/decryption routines will need to usesome state, carried between calls to the filing system. We thereforemight define a new type 'derived' from gp_file
as follows:
An implementation of gs_fs_t
for our 'crypt' filing systemmight then look like this:
In the above definition, we define a single handler, to cope with theopening of our input/output files. If we wanted to encrypt/decryptother files too (perhaps the temporary files we produce) we'd need todefine additional handlers (such as open_scratch
).
Our handler might look as follows:
The crucial part of this function is the definition of crypt_ops
,an instance of the gp_file_ops_t
type; a table of function pointersthat implement the actual operations required.
I would like to seed to at least 1.0+ ratio but I don't want to just leave seeding open like that. Www bittorret com.
These functions generally follow the same patterns as the posix functions that match them,and so in many cases we will describe these with references to such.Whenever these routines are called, they will be passed a gp_file
pointer.This pointer will have originated from the crypt_open_file
call, and so cansafely be cast back to a gp_file_crypt
pointer to allow private data to be accessed.
close(gp_file *)
- close the given file; free any storage in the crypt specific parts of
gp_file_crypt
,but not the gp_file_crypt structure itself. int getc(gp_file *)
- Get a single character from the file, returning it as an int (or -1 for EOF).Behaves like
fgetc(FILE *)
. int putc(gp_file *, int)
- Put a single character to the file, returning the character on success, orEOF (and setting the error indicator) on error.Behaves like
fgetc(FILE *)
. int read(gp_file *, size_t size, unsigned int count, void *buf)
- Reads count entries of size bytes the file into buf, returning the numberof entries read. Behaves like
fread(FILE *, size, count, buf)
. int write(gp_file *, size_t size, unsigned int count, const void *buf)
- Writes count entries of size bytes from buf into the file, returning thenumber of entries written. Behaves like
fwrite(FILE *, size, count, buf)
. int seek(gp_file *, gs_offset_t offset, int whence)
- Seeks within the file. Behaves like
fseek(FILE *, offset, whence)
. gs_offset_t tell(gp_file *)
- Returns the current offset within the file. Behaves like
ftell(FILE *)
. int eof(gp_file *)
- Returns 1 if we are at the end of the file, 0 otherwise. Behaves like
feof(FILE *)
. gp_file * dup(gp_file *, const char *mode)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like
fdup(FILE *)
. Leave NULL if not implemented. int seekable(gp_file *)
- Returns 1 if the file is seekable, 0 otherwise. Certain output devices willonly work with seekable files.
int pread(gp_file *, size_t count, gs_offset_t offset, void *buf)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like an atomic
fseek(FILE *, offset, 0)
andfread(FILE *, 1, count, buf)
.Akin topread
. int pwrite(gp_file *, size_t count, gs_offset_t offset, const void *buf)
- Optional function, only used if clist files are to be stored in this filing system.Behaves like an atomic
fseek(FILE *, offset, 0)
andfwrite(FILE *, 1, count, buf)
.Akin topwrite
. int is_char_buffered(gp_file *file)
- Returns 1 if the file is character buffered, 0 otherwise. Used for handlingreading from terminals. Very unlikely to be used, so returning 0 all the timeshould be safe. Leave NULL to indicate 'always 0'.
void fflush(gp_file *file)
- Ensures that any buffered data is written to the file. Behaves like
fflush(FILE *)
.Leave NULL to indicate that no flushing is ever required. int ferror(gp_file *file)
- Returns non-zero if there has been an error, or 0 otherwise. Behaves like
ferror(FILE *)
. FILE * get_file(gp_file *file)
- Optional: Gets the FILE * pointer that backs this file. Required for a few devicesthat insist on working with FILE *'s direct. Generally safe to leave this set to NULL, and thosedevices will fail gracefully.
void clearerr(gp_file *file)
- Clear the error and EOF values for a file. Behaves like
clearerror(FILE *)
. gp_file * reopen(gp_file *f, const char *fname, const char *mode)
- Optional function, only used if the
gp_file
came from anopen_scratch
call; can be left as NULL if theopen_scratch
pointer is set to NULL.Reopen a stream with a different mode. Behaves likefreopen(fname, mode, FILE *)
.
Avghostscript For Macbook Pro
Callouts
Callouts are a mechanismfor the core code (specifically devices) to communicate with theuser of gsapi. This communication can take the form of passinginformation out vis-a-vis what devices are doing, or requestingconfiguration from the caller to affect exactly how the deviceitself works.
This is deliberately an extensible system, so exact details ofcallouts should be documented with the device in question. In generalhowever a callout handler will be of the form:
The callout_handle
value passed to the callout willbe the value passed in at registration. The device_name
should be a null-terminated string giving the name of the device(though care should be taken to cope with the case wheredevice_name
is NULL for potential future uses).The id
value will have a (device-specific) meaning; seethe documentation for the device in question for more details. Thesame id
value may be used to mean different things indifferent devices.Finally, size
and data
have calloutspecific meanings, but typically, data
will be a pointerto data block (which may either be uninitialised or wholly/partiallyinitialised on entry, and may be updated on exit), and size
will be the size (in bytes) of the block pointed to by data
.
A return value of -1 (gs_error_unknownerror
) meansthe callout was not recognised by the handler, and should be passedto more handlers. Other negative values are interpreted as standardGhostscript error values, and stop the propagation of the callout.Non-negative return codes mean the callout was handled and shouldnot be passed to any more registered callout handlers.
Example Usage
To try out the following examples in a development environment like Microsoft'sdeveloper tools or Metrowerks Codewarrior, create a new project, save the examplesource code as a .c file and add it, along with the Ghostscript dll or sharedlibrary. You will also need to make sure the Ghostscript headers are available, eitherby adding their location (the src directory in the Ghostscript sourcedistribution) to the project's search path, or by copying ierrors.h and iapi.h into thesame directory as the example source.
Example 1
Example 2
Example 3
Replace main() in either of the above with the following code,showing how you can feed Ghostscript piecemeal:
Example 4
When feeding Ghostscript piecemeal buffers, one can use the normaloperators to configure things and invoke library routines. For example,to parse a PDF file one could say:
and Ghostscript would open and process the file named 'example.pdf' asif it had been passed as an argument togsapi_init_with_args()
.
Multiple threads
The Ghostscript library should have been compiled with athread safe run time library.Synchronisation of threads is entirely up to the caller.The exported gsapi_*()
functions must be called from one thread only.
Standard input and output
When using the Ghostscript interpreter library interface, you have achoice of two standard input/output methods.
- If you do nothing, the 'C' stdio will be used.
- If you use
gsapi_set_stdio()
, all stdio will be redirected to the callback functions you provide. This would be used in a graphical user interface environment where stdio is not available, or where you wish to process Ghostscript input or output.
The callback functions are described iniapi.h
.
Display device
The display
device is available for use withthe Ghostscript interpreter library. While originally designedfor allowing screen display of rendered output from Ghostscript,this is now powerful enough to provide a simple mechanism forgetting rendered output suitable for use in all manner ofoutput scenarios, including printing.
Details of the API and options are given in the filegdevdsp.h
.This device provides you with access to the raster output ofGhostscript. It is the callers responsibility to copy this rasterto a display window or printer.
In order for this device to operate, it needs access to a structurecontaining a set of callback functions, and a callback handle (anopaque void *
that can be used by caller to locate itsown state). There are 2 ways that the device can get thisinformation, a legacy method, and a modern method.
The address of the callback structure, is providedusing gsapi_set_display_callback()
.This must be called aftergsapi_new_instance()
and beforegsapi_init_with_args()
.
With this call, the callback handle is passed as NULL by default, but canbe overridden by using a parameter. We actively dislikethis way of working, as we consider passing addressesvia the command line distasteful. The handle can beset using
-sDisplayHandle=1234
Where '1234' is a string. The API was changed to use a stringrather than an integer/long value when support for 64 bit systemsarrived. A display 'handle' is often a pointer, and since thesecommand line options have to survive being processed by Postscriptmachinery, and Postscript only permits 32 bit number values, adifferent representation was required. Hence changing the valueto a string, so that 64 bit values can be supported. The stringformats allowed are:
1234
- implicit base 10
10#1234
- explicit base 10
16#04d2
- explicit base 16
The 'number string' is parsed by the display device to retrievethe number value, and is then assigned to the void pointerparameter 'pHandle' in the display device structure. Thus, fora trivial example, passing -sDisplayHandle=0
will resultin the first parameter passed to your display device callbacks being:(void *)0
.
The previous API, using a number value:
-dDisplayHandle=1234
is still supported on 32 bit systems, but will cause a 'typecheck'error on 64 bit systems, and is considered deprecated. It shouldnot be used in new code.
The preferred method is to register a callout handler usinggsapi_register_callout
.When this handler is called for the 'display'
device, with id = 0
(= DISPLAY_CALLOUT_GET_CALLBACK
),then data
should point to an empty gs_display_get_callback_t
block, with size = sizeof(gs_display_get_callback_t)
.
The handler should fill in the structure before returning,with a return code of 0.
Note, that the DisplayHandle
value is only consulted fordisplay device callbacks registered using the (legacy, now deprecated)gsapi_set_display_callback
API, not the preferredgsapi_register_callout
based mechanism.
The device raster format can be configured using
-dDisplayFormat=NNNN
Options include
- native, gray, RGB, CMYK or separation color spaces.
- alpha byte (ignored).
- 1 to 16 bits/component.
- bigendian (RGB) or littleendian (BGR) order.
- top first or bottom first raster.
- 16 bits/pixel with 555 or 565 bitfields.
- Chunky, Planar and Planar interleaved formats.
- 'Full screen' or 'Rectangle Request' modes of operation.
The operation of the device is best described with a walkthroughof some example code that uses it. For simplicity and clarity, wehave omitted the error handling code in this example; in productioncode, every place where we get a code
value returnedwe should check it for failure (a negative value) and clean upaccordingly. First, we create an instance of Ghostscript:
Next, we have to give the display device the address of ourcallback structure. In old code, we would do so using somethinglike this:
We strongly recommend that you don't do that, but instead use themore modern callout mechanism:
where state
is any void *
value you like,usually a pointer to help you reach any internal state you may need.Earlier in your code you would have the definition ofmy_callout_handler
that might look like this:
As you can see, this callout handler only responds to calloutsfor the display device, and then only for one particular function(id
). It returns the same display_callback
structure as the deprecated, legacy mechanism passed in usinggsapi_set_display_callback
, with the added benefit thatthe caller_handle
value can be passed in too. In thisexample we pass in the same value as was used for callout_handle
,but implementations are free to use any value they want.
Returning to our example, we now set up a set of arguments tosetup Ghostscript:
The zeroth arg is a dummy argument to match the standard C mechanismfor passing arguments to a program. Traditionally this is the name ofthe program being invoked. Next, we tell Ghostscript to use the displaydevice.
Next we tell the display device what output format to use. Theformat is flexible enough to support common Windows, OS/2, Linuxand Mac raster formats.The format values are described ingdevdsp.h
.To select the display device with a Windows 24-bit RGB raster:
If (and only if) you used the legacy mechanism described above, youwill need another argument to pass in the caller_handle
value to be parroted back to the functions listed withindisplay_callback
:
Any other arguments that you want can be added to the end ofthe command line, typically including a file to run. Then we passthat all to Ghostscript:
At this point you should start tosee your display callback functions being called. Exactly which callbackfunctions are provided, and how they respond will determine exactlyhow the display device operates. The primary choice will be whether thedevice runs in 'full page' or 'rectangle request' mode. Details of these are given below.
Once we have finished processing the file, we can processother files using gsapi_run_file
, or feed in datausing gsapi_run_string
. Once you have finished, youcan shut the interpreter down and exit, using:
A full list of the display callback functions can be found ingdevdsp.h
. Thereare several different versions of the callback, corresponding todifferent 'generations' of the device. In generalyou should use the latest one. The size
field ofthe structure should be initialised to the size of the structurein bytes.
display_open
This function will be called when the display device isopened. The device may be opened and closed many times,sometimes without any output being produced.
Download PC Demo. Free Saints Row IV - Thank You Pack. 'Saints Row 4 is a modern classic befitting the insane legacy of the 3rd Street Saints. Saints row 4 setup download. Saints Row The Third Remastered Free Download PC Game 2020 Multiplayer DMG Repacks For MAC OS X With Latest Updates And All The DLCs Worldofpcgames. Overview Saints Row The Third Remastered: Saints Row The Third Remastered is an action and adventure game and is the third main entry in the Saints row series.
display_preclose
This function will be called when the display device isabout to be closed. The device will not actually be closeduntil this function returns.
display_close
This function will be called once the display device hasbeen closed. There will be no more events from the deviceunless/until it is reopened.
display_presize
This function will be called when the display device isabout to be resized. The device will only be resized if thisfunction returns 0.
display_size
This function will be called when the display device ishas been resized. The pointer to the raster image is pimage.
display_sync
This function may be called periodically during displayto flush the page to the display.
display_page
This function is called on a 'showpage' operation(i.e. at the end of every page). Operation will continue as soon asthis function returns.
display_update
This function may get called repeatedlyduring rendering to indicate that an area of the output hasbeen updated. Certain types of rendering will not see thisfunction called back at all (in particular files usingtransparency).
display_memalloc
Note: In older versions of this API,size is an unsigned long
rather than asize_t
.
If this function pointer is sent as NULL, then thedisplay device will handle all the memory allocationsinternally, and will always work in full page renderingmode.
Otherwise, this function will be called to allocatethe storage for the page to be rendered into. If a non-NULLvalue is returned, then the device will proceed to renderthe full page into it. Mass effect 2 money glitch hack. If NULL is returned, then the devicewill check a) whether we are using a V2 or greater displaycallback structure and b) whether that structure specifiesa rectangle_request
function pointer.
If both of those conditions are true, then the devicewill continue in rectangle request mode. Otherwise it willfail with an out of memory error.
display_memfree
This function should be NULL if and only ifdisplay_memalloc
isNULL. Any memory allocated using display_memalloc
will befreed via this function.
display_separation
When using DISPLAY_COLORS_SEPARATION
, this function will be called once for every separation component - first 'Cyan', 'Magenta', 'Yellow' and 'Black', then any spot colors used. The supplied c
, m
, y
and k
values give the equivalent color for each spot. Each colorant value ranges from 0 (for none) to 65535 (full).
In separation color mode you are expected to count the numberof calls you get to this function after eachdisplay_size
to know how manycolors you are dealing with.
display_adjust_band_height
When running in 'rectangle request mode' the devicefirst renders the page to a display list internally. It can thenbe played back repeatedly so that different regions (rectangles)of the page can be extracted in sequence. A common use of this isto support 'banded' operation, where the page is dividedinto multiple non-overlapping bands of a fixed height.
Ghostscript Mactex
The display device itself will pick an appropriate band heightfor it to use. If this function pointer is left as NULL then thisvalue will be used unchanged. Otherwise, the proposed value willbe offered to this function. This function can override the choiceof bandheight, by returning the value that it would like to beused in preference.
In general, this figure should (as much as possible) only beadjusted downwards. For example, a device targeting an inkjet printerwith 200 nozzles in the print head might like to extract bandsthat are a multiple of 200 lines high. So the function mightreturn max(200, 200*(bandheight/200))
. If the functionreturns 0, then the existing value will be used unchanged.
Any size rectangle can be chosen with any size bandheight,so ultimately the value chosen here will not matter much. Itmay make some small difference in speed in some cases.
display_rectangle_request
If the display device chooses to use rectangle request mode,this function will be called repeatedly to request a rectangleto render. Ghostscript will render the rectangle, and call thisfunction again. The implementer is expected to handle the rectanglethat has just been rendered, and to return the details of anotherrectangle to render. This will continue until a rectangle withzero height or width is returned, whereupon Ghostscript willcontinue operation.
On entry, *raster
and *plane_raster
are set to the values expected by the format in use. All theother pointers point to uninitialised values.
On exit, the values should be updated appropriately. Theimplementor is expected to store the values returned so thatthe rendered output given can be correctly interpreted when control returns to this function.
memory
should be updated to point to a block ofmemory to use for the rendered output. Pixel (*ox
,*oy
) is the first pixel represented in that block.*raster
is the number of bytes difference betweenthe address of component 0 of Pixel(*ox
, *oy
)and the address of component 0 of Pixel(*ox
,1+*oy
). *plane_raster
is the number ofbytes difference between the address of component 0 ofPixel(*ox
, *oy
) and the address ofcomponent 1 of Pixel(*ox
, *oy
), if inplanar mode, 0 otherwise. *x
, *y
,*w
and *h
give the rectangle requestedwithin that memory block.
Any set of rectangles can be rendered with this method, so thiscan be used to drive Ghostscript in various ways. Firstly, it issimple to request a set of non-overlapping 'bands' thatcover the page, to drive a printer. Alternatively, rectangles canbe chosen to fill a given block of memory to implement a windowpanning around a larger page. Either the whole image could beredrawn each time, or smaller rectangles around the edge of thepanned area could be requested. The choice is down to the caller.
How To Use Ghostscript
Some examples of driving this code in full page mode are indwmain.c
(Windows),dpmain.c
(OS/2) anddxmain.c
(X11/Linux), anddmmain.c
(MacOS Classic or Carbon).
Alternatively an example that drives this code in both full pageand rectangle request mode can be found indisplaydevice_test.c
.
On some platforms, the calling convention for the display device callbacks ingdevdsp.h
is not the same as the exportedgsapi_*()
functions in iapi.h
.
Copyright © 2000-2020 Artifex Software, Inc. All rights reserved.
This software is provided AS-IS with no warranty, either express orimplied.
This software is distributed under license and may not be copied, modifiedor distributed except as expressly authorized under the terms of thatlicense. Refer to licensing information at https://www.artifex.comor contact Artifex Software, Inc., 1305 Grant Avenue - Suite 200,Novato, CA 94945, U.S.A., +1(415)492-9861, for further information.Ghostscript version 9.53.3, 1 October 2020