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