include/ghostscript/gdevdsp.h

0001 /* Copyright (C) 2001-2023 Artifex Software, Inc.
0002    All Rights Reserved.
0003
0004    This software is provided AS-IS with no warranty, either express or
0005    implied.
0006
0007    This software is distributed under license and may not be copied,
0008    modified or distributed except as expressly authorized under the terms
0009    of the license contained in the file LICENSE in this distribution.
0010
0011    Refer to licensing information at http://www.artifex.com or contact
0012    Artifex Software, Inc.,  39 Mesa Street, Suite 108A, San Francisco,
0013    CA 94129, USA, for further information.
0014 */
0015
0016 /* gdevdsp.h - callback structure for DLL based display device */
0017
0018 #ifndef gdevdsp_INCLUDED
0019 #  define gdevdsp_INCLUDED
0020
0021 /*
0022  * There are 2 mechanisms to provide the callback structure to
0023  * Ghostscript. A legacy one, and a modern one. The legacy one is
0024  * deprecated and should not be used in new code - at some point it may
0025  * be removed.
0026  *
0027  * Modern method: Call the Ghostscript APIs in the following order:
0028  *  gsapi_new_instance(&minst);
0029  *  gsapi_register_callout(minst, callout, callout_handle);
0030  *  gsapi_init_with_args(minst, argc, argv);
0031  *
0032  * The callout handler should look for a callout from the 'display'
0033  * device, with id=DISPLAY_CALLOUT_GET_CALLBACK and respond by filling
0034  * in the supplied gs_display_get_callback_t structure.
0035  *
0036  * Supported parameters and default values are:
0037  * -dDisplayFormat=0                      long
0038  *    Color format specified using bitfields below.
0039  *    Included as argument of display_size() and display_presize()
0040  * These can only be changed when the device is closed.
0041  *
0042  * Legacy method: Call the Ghostscript APIs in the following order:
0043  *  gsapi_new_instance(&minst);
0044  *  gsapi_set_display_callback(minst, callback);
0045  *  gsapi_init_with_args(minst, argc, argv);
0046  *
0047  * An additional parameter is supported, with default value NULL:
0048  * -sDisplayHandle=16#04d2 or 1234        string
0049  *    Caller supplied handle as a decimal or hexadecimal number
0050  *    in a string.  On 32-bit platforms, it may be set
0051  *    using -dDisplayHandle=1234 for backward compatibility.
0052  *    Included as first parameter of all callback functions.
0053  *
0054  * The second parameter of all callback functions "void *device"
0055  * is the address of the Ghostscript display device instance.
0056  * The arguments "void *handle" and "void *device" together
0057  * uniquely identify an instance of the display device.
0058  *
0059  * A typical sequence of callbacks (when running without a
0060  * display_choose_mode) would be:
0061  *  open, presize, memalloc, size, sync, page
0062  *  presize, memfree, memalloc, size, sync, page
0063  *  preclose, memfree, close
0064  * The caller should not access the image buffer:
0065  *  - before the first sync
0066  *  - between presize and size
0067  *  - after preclose
0068  * If opening the device fails, you might see the following:
0069  *  open, presize, memalloc, memfree, close
0070  *
0071  * A typical sequence of callbacks (when running with a
0072  * display_choose_mode) will depend upon whether display_choose_mode
0073  * selects pagemode or request-rectangle mode:
0074  *
0075  * In the pagemode case:
0076  *  open, presize, display_choose_mode, memalloc, size, sync, page
0077  *  presize, display_choose_mode, memfree, memalloc, size, sync, page
0078  *  preclose, memfree, close
0079  * The caller should not access the image buffer:
0080  *  - before the first sync
0081  *  - between presize and size
0082  *  - after preclose
0083  * If opening the device fails, you might see the following:
0084  *  open, presize, memalloc, memfree, close
0085  *
0086  * In the request-rectangle mode:
0087  *  open, presize, display_choose_mode, {rectangle_request}*
0088  *  presize, display_choose_mode, {rectangle_request}*
0089  *  preclose, close
0090  *
0091  * In a run that mixed request-rectangle and pagemode:
0092  *  open, presize, display_choose_mode, memalloc, size, sync, page
0093  *  presize, display_choose_mode, memfree, {rectangle_request}*
0094  *  presize, display_choose_mode, {rectangle_request}*
0095  *  presize, display_choose_mode, memalloc, size, sync, page
0096  *  preclose, memfree, close
0097  */
0098
0099 #define DISPLAY_VERSION_MAJOR 3
0100 #define DISPLAY_VERSION_MINOR 0
0101
0102 #define DISPLAY_VERSION_MAJOR_V1 1 /* before separation format was added */
0103 #define DISPLAY_VERSION_MINOR_V1 0
0104
0105 #define DISPLAY_VERSION_MAJOR_V2 2 /* before planar and banding were added */
0106 #define DISPLAY_VERSION_MINOR_V2 0
0107
0108 /* The display format is set by a combination of the following bitfields */
0109
0110 /* Define the color space alternatives */
0111 typedef enum {
0112     DISPLAY_COLORS_NATIVE    = (1<<0),
0113     DISPLAY_COLORS_GRAY      = (1<<1),
0114     DISPLAY_COLORS_RGB       = (1<<2),
0115     DISPLAY_COLORS_CMYK      = (1<<3),
0116     DISPLAY_COLORS_SEPARATION    = (1<<19)
0117 } DISPLAY_FORMAT_COLOR;
0118 #define DISPLAY_COLORS_MASK 0x8000fL
0119
0120 /* Define whether alpha information, or an extra unused bytes is included */
0121 /* DISPLAY_ALPHA_FIRST and DISPLAY_ALPHA_LAST are not implemented */
0122 typedef enum {
0123     DISPLAY_ALPHA_NONE   = (0<<4),
0124     DISPLAY_ALPHA_FIRST  = (1<<4),
0125     DISPLAY_ALPHA_LAST   = (1<<5),
0126     DISPLAY_UNUSED_FIRST = (1<<6),  /* e.g. Mac xRGB */
0127     DISPLAY_UNUSED_LAST  = (1<<7)   /* e.g. Windows BGRx */
0128 } DISPLAY_FORMAT_ALPHA;
0129 #define DISPLAY_ALPHA_MASK 0x00f0L
0130
0131 /* Define the depth per component for DISPLAY_COLORS_GRAY,
0132  * DISPLAY_COLORS_RGB and DISPLAY_COLORS_CMYK,
0133  * or the depth per pixel for DISPLAY_COLORS_NATIVE
0134  * DISPLAY_DEPTH_2 and DISPLAY_DEPTH_12 have not been tested.
0135  */
0136 typedef enum {
0137     DISPLAY_DEPTH_1   = (1<<8),
0138     DISPLAY_DEPTH_2   = (1<<9),
0139     DISPLAY_DEPTH_4   = (1<<10),
0140     DISPLAY_DEPTH_8   = (1<<11),
0141     DISPLAY_DEPTH_12  = (1<<12),
0142     DISPLAY_DEPTH_16  = (1<<13)
0143     /* unused (1<<14) */
0144     /* unused (1<<15) */
0145 } DISPLAY_FORMAT_DEPTH;
0146 #define DISPLAY_DEPTH_MASK 0xff00L
0147
0148 /* Define whether Red/Cyan should come first,
0149  * or whether Blue/Black should come first
0150  */
0151 typedef enum {
0152     DISPLAY_BIGENDIAN    = (0<<16), /* Red/Cyan first */
0153     DISPLAY_LITTLEENDIAN = (1<<16)  /* Blue/Black first */
0154 } DISPLAY_FORMAT_ENDIAN;
0155 #define DISPLAY_ENDIAN_MASK 0x00010000L
0156
0157 /* Define whether the raster starts at the top or bottom of the bitmap */
0158 typedef enum {
0159     DISPLAY_TOPFIRST    = (0<<17),  /* Unix, Mac */
0160     DISPLAY_BOTTOMFIRST = (1<<17)   /* Windows */
0161 } DISPLAY_FORMAT_FIRSTROW;
0162 #define DISPLAY_FIRSTROW_MASK 0x00020000L
0163
0164 /* Define whether packing RGB in 16-bits should use 555
0165  * or 565 (extra bit for green)
0166  */
0167 typedef enum {
0168     DISPLAY_NATIVE_555 = (0<<18),
0169     DISPLAY_NATIVE_565 = (1<<18)
0170 } DISPLAY_FORMAT_555;
0171 #define DISPLAY_555_MASK 0x00040000L
0172
0173 /* Define the row alignment, which must be equal to or greater than
0174  * the size of a pointer.
0175  * The default (DISPLAY_ROW_ALIGN_DEFAULT) is the size of a pointer,
0176  * 4 bytes (DISPLAY_ROW_ALIGN_4) on 32-bit systems or 8 bytes
0177  * (DISPLAY_ROW_ALIGN_8) on 64-bit systems.
0178  */
0179 typedef enum {
0180     DISPLAY_ROW_ALIGN_DEFAULT = (0<<20),
0181     /* DISPLAY_ROW_ALIGN_1 = (1<<20), */ /* not currently possible */
0182     /* DISPLAY_ROW_ALIGN_2 = (2<<20), */ /* not currently possible */
0183     DISPLAY_ROW_ALIGN_4 = (3<<20),
0184     DISPLAY_ROW_ALIGN_8 = (4<<20),
0185     DISPLAY_ROW_ALIGN_16 = (5<<20),
0186     DISPLAY_ROW_ALIGN_32 = (6<<20),
0187     DISPLAY_ROW_ALIGN_64 = (7<<20)
0188 } DISPLAY_FORMAT_ROW_ALIGN;
0189 #define DISPLAY_ROW_ALIGN_MASK 0x00700000L
0190
0191 /* Define whether we are using chunky, planar or planar interleaved
0192  * representation. */
0193 typedef enum {
0194     DISPLAY_CHUNKY             = (0<<23),
0195     DISPLAY_PLANAR             = (1<<23),
0196     DISPLAY_PLANAR_INTERLEAVED = (2<<23),
0197 } DISPLAY_FORMAT_PLANARNESS;
0198
0199 #ifndef display_callback_DEFINED
0200 #define display_callback_DEFINED
0201 typedef struct display_callback_s display_callback;
0202 #endif
0203
0204 /*
0205  * Note that for Windows, the display callback functions are
0206  * cdecl, not stdcall.  This differs from those in iapi.h.
0207  */
0208
0209 struct display_callback_s {
0210     /* Size of this structure */
0211     /* Used for checking if we have been handed a valid structure */
0212     int size;
0213
0214     /* Major version of this structure  */
0215     /* The major version number will change if this structure changes. */
0216     int version_major;
0217
0218     /* Minor version of this structure */
0219     /* The minor version number will change if new features are added
0220      * without changes to this structure.  For example, a new color
0221      * format.
0222      */
0223     int version_minor;
0224
0225     /* New device has been opened */
0226     /* This is the first event from this device. */
0227     int (*display_open)(void *handle, void *device);
0228
0229     /* Device is about to be closed. */
0230     /* Device will not be closed until this function returns. */
0231     int (*display_preclose)(void *handle, void *device);
0232
0233     /* Device has been closed. */
0234     /* This is the last event from this device. */
0235     int (*display_close)(void *handle, void *device);
0236
0237     /* Device is about to be resized. */
0238     /* Resize will only occur if this function returns 0. */
0239     /* raster is byte count of a row. */
0240     int (*display_presize)(void *handle, void *device,
0241         int width, int height, int raster, unsigned int format);
0242
0243     /* Device has been resized. */
0244     /* New pointer to raster returned in pimage */
0245     int (*display_size)(void *handle, void *device, int width, int height,
0246         int raster, unsigned int format, unsigned char *pimage);
0247
0248     /* flushpage */
0249     int (*display_sync)(void *handle, void *device);
0250
0251     /* showpage */
0252     /* If you want to pause on showpage, then don't return immediately */
0253     int (*display_page)(void *handle, void *device, int copies, int flush);
0254
0255     /* Notify the caller whenever a portion of the raster is updated. */
0256     /* This can be used for cooperative multitasking or for
0257      * progressive update of the display.
0258      * This function pointer may be set to NULL if not required.
0259      * NOTE: This is actually a really bad thing to work on. It may well
0260      * end up not being called back at all during the rendering process,
0261      * in particular if transparency is in use, or if rectangle request
0262      * mode is used.
0263      */
0264     int (*display_update)(void *handle, void *device, int x, int y,
0265         int w, int h);
0266
0267     /* Allocate memory for bitmap */
0268     /* This is provided in case you need to create memory in a special
0269      * way, e.g. shared.  If this is NULL, the Ghostscript memory device
0270      * allocates the bitmap. This will only called to allocate the
0271      * image buffer. The first row will be placed at the address
0272      * returned by display_memalloc.
0273      *
0274      * In the event of this callback returning NULL, Ghostscript will
0275      * look for a display_rectangle_request callback. If one is not
0276      * supplied, then this will be reported as memory exhaustion. If
0277      * one is supplied, then Ghostscript will switch to working in
0278      * rectangle request mode.
0279      */
0280     void *(*display_memalloc)(void *handle, void *device, size_t size);
0281
0282     /* Free memory for bitmap */
0283     /* If this is NULL, the Ghostscript memory device will free the bitmap */
0284     int (*display_memfree)(void *handle, void *device, void *mem);
0285
0286     /* Added in V2 */
0287     /* When using separation color space (DISPLAY_COLORS_SEPARATION),
0288      * give a mapping for one separation component.
0289      * This is called for each new component found.
0290      * It may be called multiple times for each component.
0291      * It may be called at any time between display_size
0292      * and display_close.
0293      * The client uses this to map from the separations to CMYK
0294      * and hence to RGB for display.
0295      * GS must only use this callback if version_major >= 2.
0296      * The unsigned short c,m,y,k values are 65535 = 1.0.
0297      * This function pointer may be set to NULL if not required.
0298      */
0299     int (*display_separation)(void *handle, void *device,
0300         int component, const char *component_name,
0301         unsigned short c, unsigned short m,
0302         unsigned short y, unsigned short k);
0303
0304     /* Added in V3 */
0305     /* If non NULL, then this gives the callback provider a chance to
0306      * a) be informed of and b) control the bandheight used by the
0307      * display device. If a call to allocate the page mode bitmap fails
0308      * (either an internal allocation or a display_memalloc call), then
0309      * Ghostscript will look for the presence of a
0310      * display_rectangle_request callback. If it exists, then it will
0311      * attempt to use retangle request mode.
0312      *
0313      * As part of this, it will pick an appropriate bandheight. If
0314      * this callback exists, it will be called so the callback provider
0315      * can know (and, optionally, tweak) the bandheight to be used.
0316      * This is purely for performance. The callback should only ever
0317      * *reduce* the bandheight given here.
0318      *
0319      * Return the adjusted bandheight (or 0 for no change).
0320      */
0321     int (*display_adjust_band_height)(void *handle, void *device,
0322                                       int bandheight);
0323
0324     /* Ask the callback for a rectangle to render (and a block to render
0325      * it in). Each subsequent call tells the caller that any previous
0326      * call has finished. To signal 'no more rectangles' return with
0327      * *w or *h = 0.
0328      *
0329      * On entry: *raster and *plane_raster are set to the standard
0330      *   values. All other values are undefined.
0331      * On return: *memory should point to a block of memory to use.
0332      *   Pixel (*ox,*oy) is the first pixel represented in that block.
0333      *   *raster = the number of bytes difference between the address of
0334      *   component 0 of Pixel(*ox,*oy) and the address of component 0 of
0335      *   Pixel(*ox,1+*oy).
0336      *   *plane_raster = the number of bytes difference between the
0337      *   address of component 0 of Pixel(*ox,*oy) and the address of
0338      *   component 1 of Pixel(*ox,*oy), if in planar mode, 0 otherwise.
0339      *   *x, *y, *w, *h = rectangle requested within that memory block.
0340      *
0341      */
0342     int (*display_rectangle_request)(void *handle, void *device,
0343                                      void **memory, int *ox, int *oy,
0344                                      int *raster, int *plane_raster,
0345                                      int *x, int *y, int *w, int *h);
0346 };
0347
0348 /* This is the V2 structure, before banding and planar support was added */
0349 struct display_callback_v2_s {
0350     int size; /* sizeof(struct display_callback_v2) */
0351     int version_major; /* DISPLAY_VERSION_MAJOR_V2 */
0352     int version_minor; /* DISPLAY_VERSION_MINOR_V2 */
0353     int (*display_open)(void *handle, void *device);
0354     int (*display_preclose)(void *handle, void *device);
0355     int (*display_close)(void *handle, void *device);
0356     int (*display_presize)(void *handle, void *device,
0357         int width, int height, int raster, unsigned int format);
0358     int (*display_size)(void *handle, void *device, int width, int height,
0359         int raster, unsigned int format, unsigned char *pimage);
0360     int (*display_sync)(void *handle, void *device);
0361     int (*display_page)(void *handle, void *device, int copies, int flush);
0362     int (*display_update)(void *handle, void *device, int x, int y,
0363         int w, int h);
0364     void *(*display_memalloc)(void *handle, void *device, unsigned long size);
0365     int (*display_memfree)(void *handle, void *device, void *mem);
0366     int (*display_separation)(void *handle, void *device,
0367         int component, const char *component_name,
0368         unsigned short c, unsigned short m,
0369         unsigned short y, unsigned short k);
0370 };
0371
0372 /* This is the V1 structure, before separation format was added */
0373 struct display_callback_v1_s {
0374     int size; /* sizeof(struct display_callback_v1) */
0375     int version_major; /* DISPLAY_VERSION_MAJOR_V1 */
0376     int version_minor; /* DISPLAY_VERSION_MINOR_V1 */
0377     int (*display_open)(void *handle, void *device);
0378     int (*display_preclose)(void *handle, void *device);
0379     int (*display_close)(void *handle, void *device);
0380     int (*display_presize)(void *handle, void *device,
0381         int width, int height, int raster, unsigned int format);
0382     int (*display_size)(void *handle, void *device, int width, int height,
0383         int raster, unsigned int format, unsigned char *pimage);
0384     int (*display_sync)(void *handle, void *device);
0385     int (*display_page)(void *handle, void *device, int copies, int flush);
0386     int (*display_update)(void *handle, void *device, int x, int y,
0387         int w, int h);
0388     void *(*display_memalloc)(void *handle, void *device, unsigned long size);
0389     int (*display_memfree)(void *handle, void *device, void *mem);
0390 };
0391
0392 #define DISPLAY_CALLBACK_V1_SIZEOF sizeof(struct display_callback_v1_s)
0393
0394 #define DISPLAY_CALLOUT_GET_CALLBACK 0
0395 #define DISPLAY_CALLOUT_GET_CALLBACK_LEGACY 1
0396
0397 typedef struct {
0398     display_callback *callback;
0399     void *caller_handle;
0400 } gs_display_get_callback_t;
0401
0402 /* The display device calls a callout to find the callback structure
0403  * and caller_handle from the environment (the DLL caller/user of the
0404  * API).
0405  * It passes:
0406  *   id = DISPLAY_CALLOUT_GET_CALLBACK.
0407  *   size = sizeof(gs_display_get_callback_t) (or larger);
0408  *   data = pointer to gs_display_get_callback_t instance for callout
0409  *          handler to fill in.
0410  *
0411  * In order to support the old gsapi_set_display_callback we have a
0412  * related callout, DISPLAY_CALLOUT_GET_CALLBACK_LEGACY. Do not use
0413  * this!
0414  */
0415
0416
0417 #endif /* gdevdsp_INCLUDED */