1 /* Copyright (C) 1992, 1995, 1996, 1998, 1999, 2000 Aladdin Enterprises. 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: gsimage.h,v 1.9 2005/06/21 16:50:51 igor Exp $ */ 18 /* Generic image rendering interface */ 19 /* Requires gsstate.h */ 20 21 #ifndef gsimage_INCLUDED 22 # define gsimage_INCLUDED 23 24 #include "gsiparam.h" 25 26 /* 27 The API defined in this file and implemented in gsimage.c provides a 28 layer of buffering between clients and the underlying image processing 29 interface defined in gxdevcli.h (begin_[typed_]image device procedure) and 30 gxiparam.h (image processing procedures). 31 32 Two of the underlying image processing procedures defined in gxiparam.h 33 define and process the actual data: 34 35 - The underlying planes_wanted image processing procedure indicates which 36 data planes are needed (not necessarily all of them, in the case of 37 images with differently scaled planes), and may also change the widths 38 and/or depths of the planes. It may return different results at 39 different times, if the widths, depths, or planes wanted changes in the 40 course of the image. 41 42 - The underlying plane_data procedure actually processes the image. Each 43 call of plane_data requires an integral number of scan lines for each 44 wanted plane. If the widths, depths, or planes wanted vary from call to 45 call, plane_data may choose to accept fewer scan lines than provided. 46 If this happens, it is the client's responsibility to call planes_wanted 47 to find out which planes are now wanted, and then call plane_data again 48 with data for (only) the wanted planes. 49 50 Conceptually, the gs_image_next_planes procedure defined here provides the 51 same function as the plane_data procedure, except that: 52 53 - The data need not consist of complete scan lines, or be aligned in any 54 way; 55 56 - If a single call passes multiple scan lines for a single plane, each 57 scan line is only padded to a byte boundary, not to an alignment 58 boundary; 59 60 - Different amounts of data (including none) may be passed for each plane, 61 independent of which planes need data or the amount of data that makes 62 up a complete scan line for a plane; 63 64 - The amount actually used is returned as a count of bytes used 65 (separately for each plane) rather than a count of scan lines. 66 67 There is one added complication. To avoid allocating large amounts of 68 storage, gs_image_next_planes may choose to copy only part of the data, 69 retaining the rest of it by reference. Clients must be informed about 70 this, since if the data is in a stream buffer, the data may move. To 71 accommodate this possibility, on subsequent calls, any data passed by the 72 client for a plane with retained data *replaces* the retained data rather 73 than (as one might expect) appending to it; if the client passes no data 74 for that plane, the retained data stays retained if needed. 75 gs_image_next_planes returns information about retained data on each call, 76 so the client need not keep track of it. 77 78 The gs_image_planes_wanted procedure is analogous to planes_wanted. It 79 identifies a plane as wanted if both of the following are true: 80 81 - The underlying planes_wanted procedure says the plane is wanted. 82 83 - Less than a full scan line of data is already buffered for that plane 84 (including retained data if any). 85 86 This is not sufficient information for the PostScript interpreter for the 87 case where the data sources are procedures, which must be called in a 88 cyclic order even if they return less than a full scan line. For this 89 case, the interpreter must keep track of a plane index itself, cycling 90 through the planes that gs_image_planes_wanted says are wanted (which may 91 vary from cycle to cycle). 92 93 There is an older, simpler procedure gs_image_next that simply cycles 94 through the planes in order. It does not offer the option of replacing 95 retained data, of passing data for more than one plane at a time, or of 96 passing data for planes in an arbitrary order. Consequently, it is only 97 usable with image types where all planes are always wanted. gs_image_next 98 should also only be used when all planes have the same width and depth and 99 the same amount of data is passed for each plane in a given cycle of 100 calls. This is not currently checked; however, gs_image_next will give an 101 error if an attempt is made to pass data for a plane that has any retained 102 data. 103 */ 104 105 /* 106 * The image painting interface uses an enumeration style: 107 * the client initializes an enumerator, then supplies data incrementally. 108 */ 109 110 /* 111 * Create an image enumerator given image parameters and a graphics state. 112 * This calls the device's begin_typed_image procedure with appropriate 113 * parameters. Note that this is an enumerator that requires entire 114 * rows of data, not the buffered enumerator used by the procedures below: 115 * for this reason, we may move the prototype elsewhere in the future. 116 */ 117 #ifndef gx_image_enum_common_t_DEFINED 118 # define gx_image_enum_common_t_DEFINED 119 typedef struct gx_image_enum_common_s gx_image_enum_common_t; 120 #endif 121 122 int gs_image_begin_typed(const gs_image_common_t * pic, gs_state * pgs, 123 bool uses_color, gx_image_enum_common_t ** ppie); 124 125 typedef struct gs_image_enum_s gs_image_enum; 126 gs_image_enum *gs_image_enum_alloc(gs_memory_t *, client_name_t); 127 128 /* 129 * gs_image_init returns 1 for an empty image, 0 normally, <0 on error. 130 * Note that gs_image_init serves for both image and imagemask, 131 * depending on the value of ImageMask in the image structure. 132 */ 133 #ifndef gx_device_DEFINED 134 # define gx_device_DEFINED 135 typedef struct gx_device_s gx_device; 136 #endif 137 138 /* Initialize an enumerator for an ImageType 1 image. */ 139 int gs_image_init(gs_image_enum * penum, const gs_image_t * pim, 140 bool MultipleDataSources, gs_state * pgs); 141 142 /* Initialize an enumerator for a general image. 143 penum->memory must be initialized in advance. 144 */ 145 int gs_image_enum_init(gs_image_enum * penum, 146 gx_image_enum_common_t * pie, 147 const gs_data_image_t * pim, gs_state *pgs); 148 149 /* 150 * Return the number of bytes of data per row 151 * (per plane, if there are multiple planes). 152 */ 153 uint gs_image_bytes_per_plane_row(const gs_image_enum * penum, int plane); 154 155 #define gs_image_bytes_per_row(penum)\ 156 gs_image_bytes_per_plane_row(penum, 0) 157 158 /* 159 * Return a byte vector indicating which planes (still) need data for the 160 * current row. See above for details. 161 */ 162 const byte *gs_image_planes_wanted(gs_image_enum *penum); 163 164 /* 165 * Pass multiple or selected planes of data for an image. See above for 166 * details. 167 * 168 * plane_data[] is an array of size num_planes of gs_const_string type 169 * which contains the pointer and the length for each. 170 * used[] is also of size num_planes and will be set to the number of 171 * bytes consumed for each plane. 172 * 173 * The amount of data available for a plane (i.e., the size of a 174 * plane_data[] element) can be 0 in order to provide data for a single 175 * plane or only some of the planes. Note that if data is retained, 176 * it is not "consumed": e.g., if all of the data for a given plane is 177 * retained, used[] for that plane will be set to 0. 178 * 179 * Returns 1 if end of image, < 0 error code, otherwise 0. In any case, 180 * stores pointers to the retained strings into plane_data[]. Note that 181 * used[] and plane_data[] are set even in the error or end-of-image case. 182 */ 183 int gs_image_next_planes(gs_image_enum *penum, gs_const_string *plane_data, 184 uint *used); 185 186 /* Pass the next plane of data for an image. See above for details. */ 187 int gs_image_next(gs_image_enum * penum, const byte * dbytes, 188 uint dsize, uint * pused); 189 190 /* Clean up after processing an image. */ 191 int gs_image_cleanup(gs_image_enum * penum); 192 193 /* Clean up after processing an image and free the enumerator. */ 194 int gs_image_cleanup_and_free_enum(gs_image_enum * penum); 195 196 #endif /* gsimage_INCLUDED */ 197