1 /* libhpojip -- HP OfficeJet image-processing library. */ 2 3 /* Copyright (C) 1995-2002 HP Company 4 * 5 * This program is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU General Public License as 7 * published by the Free Software Foundation; either version 2 of the 8 * License, or (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, but 11 * is provided AS IS, WITHOUT ANY WARRANTY; without even the implied 12 * warranty of MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, and 13 * NON-INFRINGEMENT. See the GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, 18 * MA 02111-1307, USA. 19 * 20 * In addition, as a special exception, HP Company 21 * gives permission to link the code of this program with any 22 * version of the OpenSSL library which is distributed under a 23 * license identical to that listed in the included LICENSE.OpenSSL 24 * file, and distribute linked combinations including the two. 25 * You must obey the GNU General Public License in all respects 26 * for all of the code used other than OpenSSL. If you modify 27 * this file, you may extend this exception to your version of the 28 * file, but you are not obligated to do so. If you do not wish to 29 * do so, delete this exception statement from your version. 30 */ 31 32 /* Original author: Mark Overton and others. 33 * 34 * Ported to Linux by David Paschal. 35 */ 36 37 /* xform.h - Interface into the transform drivers 38 * 39 * Mark Overton, Jan 2000 - Extracted from hpojip.h 40 */ 41 42 #if ! defined XFORM_H_INC 43 #define XFORM_H_INC 44 45 46 /*****************************************************************************\ 47 ***************************************************************************** 48 * 49 * TRANSFORM DRIVER interface 50 * 51 ***************************************************************************** 52 \*****************************************************************************/ 53 54 55 /* In some ways, this driver interface is very similar to the main ip 56 * interface. Please don't get them confused. 57 * 58 * One of the parameters of the ipOpen function is an array of structures. 59 * Each such structure defines a transform, and contains, among other things, 60 * a pointer to a jump-table for the transform-driver. The jump-table is 61 * a structure containing function-pointers for all the driver's functions. 62 * These functions and the jump-table are defined below. 63 * 64 * Function Call Order 65 * 66 * openXform; 67 * setDefaultInputTraits, setXformSpec, getHeaderBufSize (any order); 68 * getActualTraits (possibly multiple calls); 69 * getActualBufSizes; 70 * convert, insertedData, newPage (usually multiple calls); 71 * closeXform. 72 * 73 * Raw Data Format 74 * 75 * A decoder outputs raw data, an encoder inputs raw data, and all data passed 76 * between xforms consists of raw data. 77 * Such raw raster data consists of fixed-length raster rows of packed pixels. 78 * The pixels are packed as follows: 79 * 80 * bi-level: 8 pixels/byte, left pixel in msb, 0=white, 1=black. 81 * 4-bit gray: 2 pixels/byte, left pixel in hi nibble, 0=black, 15=white. 82 * 8-bit gray: 1 pixel/byte, 0=black, 255=white. 83 * color: three bytes per pixel, in some color space. 84 * 85 * Driver Documentation 86 * 87 * The .c file for an xform driver starts with a comment-section documenting 88 * the following items: 89 * 90 * - the capabilities of the driver, and its limitations. 91 * - the name of the global jump-table (of type IP_XFORM_TBL). 92 * - what should be put in the aXformInfo array passed to setXformSpec. 93 * - which items in default input traits are ignored versus used. 94 * - what the output image traits are. 95 * 96 * Note that image traits, such as pixels per row, should *not* be put in 97 * aXformInfo because such info is provided by setDefaultInputTraits. 98 * Things like the JPEG quality-factor should be in aXformInfo. 99 * 100 * An xform driver is allowed to overrun its input or output buffer by 101 * up to 12 bytes. This is allowed because some image processing algorithms 102 * are faster if they operate on multiple pixels at a time, which will cause 103 * them to read or write a little past the end of the buffer. Reading or 104 * writing before the beginning of a buffer is not allowed. 105 */ 106 107 108 typedef void* IP_XFORM_HANDLE; /* handle for an xform driver */ 109 110 111 /* IP_XFORM_TBL - Jump-table for a transform driver (all the entry points) 112 */ 113 typedef struct IP_XFORM_TBL_s { 114 115 /* openXform - Creates a new instance of the transformer 116 * 117 * This returns a handle for the new instance to be passed into 118 * all subsequent calls. 119 * 120 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 121 */ 122 WORD (*openXform) ( 123 IP_XFORM_HANDLE *pXform); /* out: returned handle */ 124 125 126 /* setDefaultInputTraits - Specifies default input image traits 127 * 128 * The header of the file-type handled by the transform probably does 129 * not include *all* the image traits we'd like to know. Those not 130 * specified in the file-header are filled in from info provided by 131 * this routine. 132 * 133 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 134 */ 135 WORD (*setDefaultInputTraits) ( 136 IP_XFORM_HANDLE hXform, /* in: handle for xform */ 137 PIP_IMAGE_TRAITS pTraits); /* in: default image traits */ 138 139 140 /* setXformSpec - Provides xform-specific information 141 * 142 * The aXformInfo array provides the transform-specific info. 143 * For example, for a scaling transform, this array would contain 144 * the horizontal and vertical scaling factors and possibly additional 145 * info about whether to scale quickly by simple pixel-replication. 146 * For a JPEG-encode transform, the array would contain the quality 147 * factor and subsampling information. 148 * 149 * Each transform documents what it needs in aXformInfo. 150 * 151 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 152 */ 153 WORD (*setXformSpec) ( 154 IP_XFORM_HANDLE hXform, /* in: handle for xform */ 155 DWORD_OR_PVOID aXformInfo[]); /* in: xform information */ 156 157 158 /* getHeaderBufSize- Returns size of input buf needed to hold header 159 * 160 * Returns size of input buffer that's guaranteed to hold the file 161 * header. If that's too big, the xform code will have to parse the 162 * header across several calls, and return a suitable buffer size. 163 * If there is no header, this function returns 0 in pwInBufLen. 164 * 165 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 166 */ 167 WORD (*getHeaderBufSize) ( 168 IP_XFORM_HANDLE hXform, /* in: handle for xform */ 169 DWORD *pdwInBufLen); /* out: buf size for parsing header */ 170 171 172 /* getActualTraits - Parses header, and returns input & output traits 173 * 174 * This function may need to be called multiple times to parse the 175 * file header. And it can consume input in each call. 176 * Once the header has been parsed, it returns IP_DONE, meaning that 177 * it is not to be called again and that the in-traits and out-traits 178 * structures have been filled in. The output traits are computed based 179 * on the input traits and the xform information provided by setXformSpec. 180 * 181 * See the description of 'convert' below for how the input-buffer 182 * parameters are used. The final value returned in pdwInputNextPos 183 * (where this returns IP_DONE) is the one that applies to the 184 * 'convert' function. This function MUST be called even if there is 185 * no header because you need that pdwInputNextPos value. 186 * 187 * NOTE: In addition to IP_DONE, the IP_READY_FOR_DATA bit must also 188 * be set if the xform will want data on the first call to 'convert'. 189 * 190 * Return value: 191 * 0 = call again with more input, 192 * IP_DONE = normal end (IP_READY_FOR_DATA set if data needed) 193 * IP_INPUT_ERROR = error in input data, 194 * IP_FATAL_ERROR = misc error. 195 */ 196 WORD (*getActualTraits) ( 197 IP_XFORM_HANDLE hXform, /* in: handle for xform */ 198 DWORD dwInputAvail, /* in: # avail bytes in input buf */ 199 PBYTE pbInputBuf, /* in: ptr to input buffer */ 200 PDWORD pdwInputUsed, /* out: # bytes used from input buf */ 201 PDWORD pdwInputNextPos,/* out: file-pos to read from next */ 202 PIP_IMAGE_TRAITS pInTraits, /* out: input image traits */ 203 PIP_IMAGE_TRAITS pOutTraits); /* out: output image traits */ 204 205 206 /* getActualBufSizes - Returns buf sizes needed for remainder of session 207 * 208 * Since the input and output row-lengths are now known because 209 * getActualTraits has parsed the header, and actual buffer sizes needed 210 * for the remainder of the conversion session can now be fetched. 211 * 212 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 213 */ 214 WORD (*getActualBufSizes) ( 215 IP_XFORM_HANDLE hXform, /* in: handle for xform */ 216 PDWORD pwMinInBufLen, /* out: min input buf size */ 217 PDWORD pwMinOutBufLen); /* out: min output buf size */ 218 219 220 /* convert - The work-horse conversion routine 221 * 222 * This function consumes input data and produces output data via the 223 * input- and output-buffer parameters. And it tells you what's happening 224 * via its function return value. 225 * 226 * On entry, pbInputBuf and wInputAvail specify the location and number of 227 * data-bytes in the input buffer. On return, pwInputUsed tells you how 228 * many of those input bytes were consumed. pdwInputNextPos tells you 229 * where in the input file you should read next for the following call; 230 * 0 is the beginning of the file. This is almost always the current file 231 * position plus pwInputUsed; if not, a file-seek is being requested. 232 * 233 * The output buffer parameters are analogous to the input parameters, 234 * except that pdwOutputThisPos tells you where the bytes just output 235 * should be written in the output file. That is, it applies to *this* 236 * write, not the *next* write, unlike the input arrangement. 237 * 238 * The function return value is a bit-mask that tells you if anything 239 * interesting happened. Multiple bits can be set. This information 240 * should be treated as independent of the data-transfers occuring via 241 * the parameters. The IP_CONSUMED_ROW and IP_PRODUCED_ROW bits can 242 * be used to count how many rows have been input and output. 243 * 244 * The IP_READY_FOR_DATA bit indicates that the next call to 'convert' 245 * definitely will consume data. If this bit is 0, the next call 246 * definitely will NOT consume data. The main converter code that calls 247 * these xform functions uses this ready-for-data info to control the 248 * order of xform calls. The IP_READY_FOR_DATA bit must be set correctly. 249 * 250 * The IP_NEW_INPUT_PAGE bit is set when or after the last row of the 251 * input page has been parsed. It may be a few rows before you get the 252 * corresponding IP_NEW_OUTPUT_PAGE bit. 253 * 254 * The IP_NEW_OUTPUT_PAGE bit is set when or after the last row of the 255 * page has been sent, and before the first row of the following page (if 256 * any) is sent. 257 * 258 * You may wish to insert secret data, such as thumbnails, into the 259 * output stream. When 'convert' returns the IP_WRITE_INSERT_OK bit, 260 * it is giving you permission to write stuff AFTER you write the output 261 * buffer it gave you. After adding your secret data, you must call 262 * insertedData to tell us how many bytes were added. 263 * 264 * When there is no more input data, 'convert' must be called repeatedly 265 * with a NULL pbInputBuf parameter, which tells the xform to flush out 266 * any buffered rows. Keep calling it until it returns the IP_DONE bit. 267 * 268 * Do not call 'convert' again after it has returned either error bit or 269 * IP_DONE. 270 * 271 * If the input or output data consists of fixed-length uncompressed rows, 272 * then it is permissible for the xform to read up to 8 bytes past the 273 * end of the (fixed-length) input row, or to write up to 8 bytes past the 274 * end of the (fixed-length) output row. The caller of the xform routines 275 * allocates at least this many extra overrun-zone bytes so that algorithms 276 * can process pixels multiple-bytes at a time without worrying about 277 * running past the end of the row. These overrun-zone bytes must NOT be 278 * reported by getActualBufSizes, which should report only what's needed 279 * for the actual row-data. 280 * 281 * Return value: Zero or more of these bits may be set: 282 * 283 * IP_CONSUMED_ROW = an input row was parsed 284 * IP_PRODUCED_ROW = an output row was produced 285 * IP_INPUT_ERROR = syntax error in input data 286 * IP_FATAL_ERROR = misc error (internal error or bad param) 287 * IP_NEW_INPUT_PAGE = just finished parsing the input page 288 * IP_NEW_OUTPUT_PAGE = just finished outputting a page 289 * IP_WRITE_INSERT_OK = okay to insert data in output file 290 * IP_DONE = conversion is completed. 291 */ 292 WORD (*convert) ( 293 IP_XFORM_HANDLE hXform, 294 DWORD dwInputAvail, /* in: # avail bytes in in-buf */ 295 PBYTE pbInputBuf, /* in: ptr to in-buffer */ 296 PDWORD pdwInputUsed, /* out: # bytes used from in-buf */ 297 PDWORD pdwInputNextPos, /* out: file-pos to read from next */ 298 DWORD dwOutputAvail, /* in: # avail bytes in out-buf */ 299 PBYTE pbOutputBuf, /* in: ptr to out-buffer */ 300 PDWORD pdwOutputUsed, /* out: # bytes written in out-buf */ 301 PDWORD pdwOutputThisPos); /* out: file-pos to write the data */ 302 303 304 /* newPage - Tells xform to flush rest of this page, and start a new page 305 * 306 * Uncompressed input-data formats do not have page-boundary info, so 307 * calling this function between rows fed into 'convert' is how you tell 308 * xform to output a page-boundary. After this is called, 'convert' will 309 * first flush any buffered rows, then return the IP_NEW_OUTPUT_PAGE bit, 310 * and finally start a new page. 311 * 312 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 313 */ 314 WORD (*newPage) (IP_XFORM_HANDLE hXform); 315 316 317 /* insertedData - Tells us that bytes were inserted into output stream 318 * 319 * See IP_WRITE_INSERT_OK discussion above. You call this routine to tell 320 * the xform code how many bytes were secretly added to the output stream. 321 * 322 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 323 */ 324 WORD (*insertedData) ( 325 IP_XFORM_HANDLE hXform, 326 DWORD dwNumBytes); 327 328 329 /* closeXform - destroys instance of xform 330 * 331 * This may be called at any time to remove an instance of the xform. 332 * It deallocates all dynamic memory associated with the xform. 333 * 334 * Return value: IP_DONE=success; IP_FATAL_ERROR=misc error. 335 */ 336 WORD (*closeXform)(IP_XFORM_HANDLE hXform); 337 338 } IP_XFORM_TBL, *PIP_XFORM_TBL, FAR*LPIP_XFORM_TBL; 339 340 #endif 341