ip/xform.h

   1 /* libhpojip -- HP OfficeJet image-processing library. */
   2
   3 /* Copyright (C) 1995-2002 Hewlett-Packard 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, Hewlett-Packard 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