1 /* Copyright (C) 2001-2019 Artifex Software, Inc. 2 All Rights Reserved. 3 4 This software is provided AS-IS with no warranty, either express or 5 implied. 6 7 This software is distributed under license and may not be copied, 8 modified or distributed except as expressly authorized under the terms 9 of the license contained in the file LICENSE in this distribution. 10 11 Refer to licensing information at http://www.artifex.com or contact 12 Artifex Software, Inc., 1305 Grant Avenue - Suite 200, Novato, 13 CA 94945, U.S.A., +1(415)492-9861, for further information. 14 */ 15 16 /* gdevdsp.h - callback structure for DLL based display device */ 17 18 #ifndef gdevdsp_INCLUDED 19 # define gdevdsp_INCLUDED 20 21 /* 22 * The callback structure must be provided by calling the 23 * Ghostscript APIs in the following order: 24 * gsapi_new_instance(&minst); 25 * gsapi_set_display_callback(minst, callback); 26 * gsapi_init_with_args(minst, argc, argv); 27 * 28 * Supported parameters and default values are: 29 * -sDisplayHandle=16#04d2 or 1234 string 30 * Caller supplied handle as a decimal or hexadecimal number 31 * in a string. On 32-bit platforms, it may be set 32 * using -dDisplayHandle=1234 for backward compatibility. 33 * Included as first parameter of all callback functions. 34 * 35 * -dDisplayFormat=0 long 36 * Color format specified using bitfields below. 37 * Included as argument of display_size() and display_presize() 38 * These can only be changed when the device is closed. 39 * 40 * The second parameter of all callback functions "void *device" 41 * is the address of the Ghostscript display device instance. 42 * The arguments "void *handle" and "void *device" together 43 * uniquely identify an instance of the display device. 44 * 45 * A typical sequence of callbacks would be 46 * open, presize, memalloc, size, sync, page 47 * presize, memfree, memalloc, size, sync, page 48 * preclose, memfree, close 49 * The caller should not access the image buffer: 50 * - before the first sync 51 * - between presize and size 52 * - after preclose 53 * If opening the device fails, you might see the following: 54 * open, presize, memalloc, memfree, close 55 * 56 */ 57 58 #define DISPLAY_VERSION_MAJOR 2 59 #define DISPLAY_VERSION_MINOR 0 60 61 #define DISPLAY_VERSION_MAJOR_V1 1 /* before separation format was added */ 62 #define DISPLAY_VERSION_MINOR_V1 0 63 64 /* The display format is set by a combination of the following bitfields */ 65 66 /* Define the color space alternatives */ 67 typedef enum { 68 DISPLAY_COLORS_NATIVE = (1<<0), 69 DISPLAY_COLORS_GRAY = (1<<1), 70 DISPLAY_COLORS_RGB = (1<<2), 71 DISPLAY_COLORS_CMYK = (1<<3), 72 DISPLAY_COLORS_SEPARATION = (1<<19) 73 } DISPLAY_FORMAT_COLOR; 74 #define DISPLAY_COLORS_MASK 0x8000fL 75 76 /* Define whether alpha information, or an extra unused bytes is included */ 77 /* DISPLAY_ALPHA_FIRST and DISPLAY_ALPHA_LAST are not implemented */ 78 typedef enum { 79 DISPLAY_ALPHA_NONE = (0<<4), 80 DISPLAY_ALPHA_FIRST = (1<<4), 81 DISPLAY_ALPHA_LAST = (1<<5), 82 DISPLAY_UNUSED_FIRST = (1<<6), /* e.g. Mac xRGB */ 83 DISPLAY_UNUSED_LAST = (1<<7) /* e.g. Windows BGRx */ 84 } DISPLAY_FORMAT_ALPHA; 85 #define DISPLAY_ALPHA_MASK 0x00f0L 86 87 /* Define the depth per component for DISPLAY_COLORS_GRAY, 88 * DISPLAY_COLORS_RGB and DISPLAY_COLORS_CMYK, 89 * or the depth per pixel for DISPLAY_COLORS_NATIVE 90 * DISPLAY_DEPTH_2 and DISPLAY_DEPTH_12 have not been tested. 91 */ 92 typedef enum { 93 DISPLAY_DEPTH_1 = (1<<8), 94 DISPLAY_DEPTH_2 = (1<<9), 95 DISPLAY_DEPTH_4 = (1<<10), 96 DISPLAY_DEPTH_8 = (1<<11), 97 DISPLAY_DEPTH_12 = (1<<12), 98 DISPLAY_DEPTH_16 = (1<<13) 99 /* unused (1<<14) */ 100 /* unused (1<<15) */ 101 } DISPLAY_FORMAT_DEPTH; 102 #define DISPLAY_DEPTH_MASK 0xff00L 103 104 /* Define whether Red/Cyan should come first, 105 * or whether Blue/Black should come first 106 */ 107 typedef enum { 108 DISPLAY_BIGENDIAN = (0<<16), /* Red/Cyan first */ 109 DISPLAY_LITTLEENDIAN = (1<<16) /* Blue/Black first */ 110 } DISPLAY_FORMAT_ENDIAN; 111 #define DISPLAY_ENDIAN_MASK 0x00010000L 112 113 /* Define whether the raster starts at the top or bottom of the bitmap */ 114 typedef enum { 115 DISPLAY_TOPFIRST = (0<<17), /* Unix, Mac */ 116 DISPLAY_BOTTOMFIRST = (1<<17) /* Windows */ 117 } DISPLAY_FORMAT_FIRSTROW; 118 #define DISPLAY_FIRSTROW_MASK 0x00020000L 119 120 /* Define whether packing RGB in 16-bits should use 555 121 * or 565 (extra bit for green) 122 */ 123 typedef enum { 124 DISPLAY_NATIVE_555 = (0<<18), 125 DISPLAY_NATIVE_565 = (1<<18) 126 } DISPLAY_FORMAT_555; 127 #define DISPLAY_555_MASK 0x00040000L 128 129 /* Define the row alignment, which must be equal to or greater than 130 * the size of a pointer. 131 * The default (DISPLAY_ROW_ALIGN_DEFAULT) is the size of a pointer, 132 * 4 bytes (DISPLAY_ROW_ALIGN_4) on 32-bit systems or 8 bytes 133 * (DISPLAY_ROW_ALIGN_8) on 64-bit systems. 134 */ 135 typedef enum { 136 DISPLAY_ROW_ALIGN_DEFAULT = (0<<20), 137 /* DISPLAY_ROW_ALIGN_1 = (1<<20), */ /* not currently possible */ 138 /* DISPLAY_ROW_ALIGN_2 = (2<<20), */ /* not currently possible */ 139 DISPLAY_ROW_ALIGN_4 = (3<<20), 140 DISPLAY_ROW_ALIGN_8 = (4<<20), 141 DISPLAY_ROW_ALIGN_16 = (5<<20), 142 DISPLAY_ROW_ALIGN_32 = (6<<20), 143 DISPLAY_ROW_ALIGN_64 = (7<<20) 144 } DISPLAY_FORMAT_ROW_ALIGN; 145 #define DISPLAY_ROW_ALIGN_MASK 0x00700000L 146 147 #ifndef display_callback_DEFINED 148 #define display_callback_DEFINED 149 typedef struct display_callback_s display_callback; 150 #endif 151 152 /* 153 * Note that for Windows, the display callback functions are 154 * cdecl, not stdcall. This differs from those in iapi.h. 155 */ 156 157 struct display_callback_s { 158 /* Size of this structure */ 159 /* Used for checking if we have been handed a valid structure */ 160 int size; 161 162 /* Major version of this structure */ 163 /* The major version number will change if this structure changes. */ 164 int version_major; 165 166 /* Minor version of this structure */ 167 /* The minor version number will change if new features are added 168 * without changes to this structure. For example, a new color 169 * format. 170 */ 171 int version_minor; 172 173 /* New device has been opened */ 174 /* This is the first event from this device. */ 175 int (*display_open)(void *handle, void *device); 176 177 /* Device is about to be closed. */ 178 /* Device will not be closed until this function returns. */ 179 int (*display_preclose)(void *handle, void *device); 180 181 /* Device has been closed. */ 182 /* This is the last event from this device. */ 183 int (*display_close)(void *handle, void *device); 184 185 /* Device is about to be resized. */ 186 /* Resize will only occur if this function returns 0. */ 187 /* raster is byte count of a row. */ 188 int (*display_presize)(void *handle, void *device, 189 int width, int height, int raster, unsigned int format); 190 191 /* Device has been resized. */ 192 /* New pointer to raster returned in pimage */ 193 int (*display_size)(void *handle, void *device, int width, int height, 194 int raster, unsigned int format, unsigned char *pimage); 195 196 /* flushpage */ 197 int (*display_sync)(void *handle, void *device); 198 199 /* showpage */ 200 /* If you want to pause on showpage, then don't return immediately */ 201 int (*display_page)(void *handle, void *device, int copies, int flush); 202 203 /* Notify the caller whenever a portion of the raster is updated. */ 204 /* This can be used for cooperative multitasking or for 205 * progressive update of the display. 206 * This function pointer may be set to NULL if not required. 207 */ 208 int (*display_update)(void *handle, void *device, int x, int y, 209 int w, int h); 210 211 /* Allocate memory for bitmap */ 212 /* This is provided in case you need to create memory in a special 213 * way, e.g. shared. If this is NULL, the Ghostscript memory device 214 * allocates the bitmap. This will only called to allocate the 215 * image buffer. The first row will be placed at the address 216 * returned by display_memalloc. 217 */ 218 void *(*display_memalloc)(void *handle, void *device, unsigned long size); 219 220 /* Free memory for bitmap */ 221 /* If this is NULL, the Ghostscript memory device will free the bitmap */ 222 int (*display_memfree)(void *handle, void *device, void *mem); 223 224 /* Added in V2 */ 225 /* When using separation color space (DISPLAY_COLORS_SEPARATION), 226 * give a mapping for one separation component. 227 * This is called for each new component found. 228 * It may be called multiple times for each component. 229 * It may be called at any time between display_size 230 * and display_close. 231 * The client uses this to map from the separations to CMYK 232 * and hence to RGB for display. 233 * GS must only use this callback if version_major >= 2. 234 * The unsigned short c,m,y,k values are 65535 = 1.0. 235 * This function pointer may be set to NULL if not required. 236 */ 237 int (*display_separation)(void *handle, void *device, 238 int component, const char *component_name, 239 unsigned short c, unsigned short m, 240 unsigned short y, unsigned short k); 241 }; 242 243 /* This is the V1 structure, before separation format was added */ 244 struct display_callback_v1_s { 245 int size; 246 int version_major; 247 int version_minor; 248 int (*display_open)(void *handle, void *device); 249 int (*display_preclose)(void *handle, void *device); 250 int (*display_close)(void *handle, void *device); 251 int (*display_presize)(void *handle, void *device, 252 int width, int height, int raster, unsigned int format); 253 int (*display_size)(void *handle, void *device, int width, int height, 254 int raster, unsigned int format, unsigned char *pimage); 255 int (*display_sync)(void *handle, void *device); 256 int (*display_page)(void *handle, void *device, int copies, int flush); 257 int (*display_update)(void *handle, void *device, int x, int y, 258 int w, int h); 259 void *(*display_memalloc)(void *handle, void *device, unsigned long size); 260 int (*display_memfree)(void *handle, void *device, void *mem); 261 }; 262 263 #define DISPLAY_CALLBACK_V1_SIZEOF sizeof(struct display_callback_v1_s) 264 265 #endif /* gdevdsp_INCLUDED */ 266