Avghostscript For Mac

Ghostscript is a set of software for PostScript language and for Portable Document Format files (PDF) interpreting. Ghostscript features high conversion capabilities and provides the complete set of Page Description Language interpreters in today’s market. ☎ +1-866-263-9903. FREE software for commercial and non-commercial use!No Adware, No Malware! Installation Requirements. Supports Microsoft Windows Vista/7/8/8.1/10 (32-bit/64-bit). Supports Microsoft Windows Server 2008/2012/2016/2019.

For other information, see the Ghostscript overview.

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.

Find the best free programs like Ghostscript for Mac. More than 13 alternatives to choose: Scribus, iPhone Explorer, iMyfone D-Back for Mac and more. Is cross-platform script writing software with story planning and screenplay formatting features ideal for the novice writer who is learning the. Ghostscript, Ghostview and GSview. This was the home page for Ghostscript, an interpreter for the PostScript language and for PDF, and related software and documentation.

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.dllcan 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.socan 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.hand 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 before gsapi_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_INTERRUPTSas 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_calloutto 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 fromthe DisplayHandle parameter (or NULL if there is nosuch parameter). If the display device is used,this must be called aftergsapi_new_instance()and before gsapi_init_with_args().See gdevdsp.hfor more details.

`gsapi_register_callout()`

This call registers a callouthandler.

`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 after gsapi_new_instance()and before gsapi_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 after gsapi_new_instance()and before gsapi_init_with_args().

`get_default_device_list()`

Returns a pointer to the current default device string.This must be called after gsapi_new_instance()and before gsapi_init_with_args().

`gsapi_init_with_args()`

Initialise the interpreter.This calls gs_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_interruptgenerated 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 if gsapi_init_with_args()has been called, and just before gsapi_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 '<</HWResolution [ 200.0 200.0 ]>>'.

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.

Ghostscript Download Windows

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_filepointer 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_fopenat 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 to gp_fopen) attempts toopen a file.
The open_pipe function pointer will be called whensomething (most often a call to gp_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 to gp_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. If rm 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 to gp_open_printer) attemptsto open a stream to a printer. If binary 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.

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 likefeof(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) and fread(FILE *, 1, count, buf).Akin to pread.
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) and fwrite(FILE *, 1, count, buf).Akin to pwrite.
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 an open_scratchcall; can be left as NULL if the open_scratch pointer is set to NULL.Reopen a stream with a different mode. Behaves likefreopen(fname, mode, FILE *).

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_nameshould 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 sizewill 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.

Legacy 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.

Modern method

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_tblock, 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_callbackstructure 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.

Ghostscript For Mac

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.

Avghostscript For Macbook Pro

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_handlevalue 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

Ghostscript For Macintosh

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.

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. 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.

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_rasterare 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.

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.his not the same as the exportedgsapi_*()functions in iapi.h.

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

Table of contents

What is the Ghostscript Interpreter API?

Exported functions

gsapi_revision()

gsapi_new_instance()

gsapi_delete_instance()

gsapi_set_stdio_with_handle()

gsapi_set_stdio()

gsapi_set_poll_with_handle()

gsapi_set_poll()

gsapi_set_display_callback()

gsapi_register_callout()

gsapi_deregister_callout()

gsapi_set_arg_encoding()

set_default_device_list()

get_default_device_list()

gsapi_init_with_args()

gsapi_run_*()

gsapi_exit()

gsapi_set_param()

gsapi_get_param()

gsapi_enumerate_params()

gsapi_add_control_path()

gsapi_remove_control_path()

gsapi_purge_control_paths()

gsapi_activate_path_control()

gsapi_is_path_control_active()

gsapi_add_fs()

gsapi_remove_fs()