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