transupp.h

00001 /*
00002  * transupp.h
00003  *
00004  * Copyright (C) 1997-2013, Thomas G. Lane, Guido Vollbeding.
00005  * This file is part of the Independent JPEG Group's software.
00006  * For conditions of distribution and use, see the accompanying README file.
00007  *
00008  * This file contains declarations for image transformation routines and
00009  * other utility code used by the jpegtran sample application.  These are
00010  * NOT part of the core JPEG library.  But we keep these routines separate
00011  * from jpegtran.c to ease the task of maintaining jpegtran-like programs
00012  * that have other user interfaces.
00013  *
00014  * NOTE: all the routines declared here have very specific requirements
00015  * about when they are to be executed during the reading and writing of the
00016  * source and destination files.  See the comments in transupp.c, or see
00017  * jpegtran.c for an example of correct usage.
00018  */
00019 
00020 /* If you happen not to want the image transform support, disable it here */
00021 #ifndef TRANSFORMS_SUPPORTED
00022 #define TRANSFORMS_SUPPORTED 1      /* 0 disables transform code */
00023 #endif
00024 
00025 /*
00026  * Although rotating and flipping data expressed as DCT coefficients is not
00027  * hard, there is an asymmetry in the JPEG format specification for images
00028  * whose dimensions aren't multiples of the iMCU size.  The right and bottom
00029  * image edges are padded out to the next iMCU boundary with junk data; but
00030  * no padding is possible at the top and left edges.  If we were to flip
00031  * the whole image including the pad data, then pad garbage would become
00032  * visible at the top and/or left, and real pixels would disappear into the
00033  * pad margins --- perhaps permanently, since encoders & decoders may not
00034  * bother to preserve DCT blocks that appear to be completely outside the
00035  * nominal image area.  So, we have to exclude any partial iMCUs from the
00036  * basic transformation.
00037  *
00038  * Transpose is the only transformation that can handle partial iMCUs at the
00039  * right and bottom edges completely cleanly.  flip_h can flip partial iMCUs
00040  * at the bottom, but leaves any partial iMCUs at the right edge untouched.
00041  * Similarly flip_v leaves any partial iMCUs at the bottom edge untouched.
00042  * The other transforms are defined as combinations of these basic transforms
00043  * and process edge blocks in a way that preserves the equivalence.
00044  *
00045  * The "trim" option causes untransformable partial iMCUs to be dropped;
00046  * this is not strictly lossless, but it usually gives the best-looking
00047  * result for odd-size images.  Note that when this option is active,
00048  * the expected mathematical equivalences between the transforms may not hold.
00049  * (For example, -rot 270 -trim trims only the bottom edge, but -rot 90 -trim
00050  * followed by -rot 180 -trim trims both edges.)
00051  *
00052  * We also offer a lossless-crop option, which discards data outside a given
00053  * image region but losslessly preserves what is inside.  Like the rotate and
00054  * flip transforms, lossless crop is restricted by the current JPEG format: the
00055  * upper left corner of the selected region must fall on an iMCU boundary.  If
00056  * this does not hold for the given crop parameters, we silently move the upper
00057  * left corner up and/or left to make it so, simultaneously increasing the
00058  * region dimensions to keep the lower right crop corner unchanged.  (Thus, the
00059  * output image covers at least the requested region, but may cover more.)
00060  * The adjustment of the region dimensions may be optionally disabled.
00061  *
00062  * A complementary lossless-wipe option is provided to discard (gray out) data
00063  * inside a given image region while losslessly preserving what is outside.
00064  *
00065  * We also provide a lossless-resize option, which is kind of a lossless-crop
00066  * operation in the DCT coefficient block domain - it discards higher-order
00067  * coefficients and losslessly preserves lower-order coefficients of a
00068  * sub-block.
00069  *
00070  * Rotate/flip transform, resize, and crop can be requested together in a
00071  * single invocation.  The crop is applied last --- that is, the crop region
00072  * is specified in terms of the destination image after transform/resize.
00073  *
00074  * We also offer a "force to grayscale" option, which simply discards the
00075  * chrominance channels of a YCbCr image.  This is lossless in the sense that
00076  * the luminance channel is preserved exactly.  It's not the same kind of
00077  * thing as the rotate/flip transformations, but it's convenient to handle it
00078  * as part of this package, mainly because the transformation routines have to
00079  * be aware of the option to know how many components to work on.
00080  */
00081 
00082 
00083 /* Short forms of external names for systems with brain-damaged linkers. */
00084 
00085 #ifdef NEED_SHORT_EXTERNAL_NAMES
00086 #define jtransform_parse_crop_spec  jTrParCrop
00087 #define jtransform_request_workspace    jTrRequest
00088 #define jtransform_adjust_parameters    jTrAdjust
00089 #define jtransform_execute_transform    jTrExec
00090 #define jtransform_perfect_transform    jTrPerfect
00091 #define jcopy_markers_setup     jCMrkSetup
00092 #define jcopy_markers_execute       jCMrkExec
00093 #endif /* NEED_SHORT_EXTERNAL_NAMES */
00094 
00095 
00096 /*
00097  * Codes for supported types of image transformations.
00098  */
00099 
00100 typedef enum {
00101     JXFORM_NONE,        /* no transformation */
00102     JXFORM_FLIP_H,      /* horizontal flip */
00103     JXFORM_FLIP_V,      /* vertical flip */
00104     JXFORM_TRANSPOSE,   /* transpose across UL-to-LR axis */
00105     JXFORM_TRANSVERSE,  /* transpose across UR-to-LL axis */
00106     JXFORM_ROT_90,      /* 90-degree clockwise rotation */
00107     JXFORM_ROT_180,     /* 180-degree rotation */
00108     JXFORM_ROT_270,     /* 270-degree clockwise (or 90 ccw) */
00109     JXFORM_WIPE     /* wipe */
00110 } JXFORM_CODE;
00111 
00112 /*
00113  * Codes for crop parameters, which can individually be unspecified,
00114  * positive or negative for xoffset or yoffset,
00115  * positive or forced for width or height.
00116  */
00117 
00118 typedef enum {
00119         JCROP_UNSET,
00120         JCROP_POS,
00121         JCROP_NEG,
00122         JCROP_FORCE
00123 } JCROP_CODE;
00124 
00125 /*
00126  * Transform parameters struct.
00127  * NB: application must not change any elements of this struct after
00128  * calling jtransform_request_workspace.
00129  */
00130 
00131 typedef struct {
00132   /* Options: set by caller */
00133   JXFORM_CODE transform;    /* image transform operator */
00134   boolean perfect;      /* if TRUE, fail if partial MCUs are requested */
00135   boolean trim;         /* if TRUE, trim partial MCUs as needed */
00136   boolean force_grayscale;  /* if TRUE, convert color image to grayscale */
00137   boolean crop;         /* if TRUE, crop or wipe source image */
00138 
00139   /* Crop parameters: application need not set these unless crop is TRUE.
00140    * These can be filled in by jtransform_parse_crop_spec().
00141    */
00142   JDIMENSION crop_width;    /* Width of selected region */
00143   JCROP_CODE crop_width_set;    /* (forced disables adjustment) */
00144   JDIMENSION crop_height;   /* Height of selected region */
00145   JCROP_CODE crop_height_set;   /* (forced disables adjustment) */
00146   JDIMENSION crop_xoffset;  /* X offset of selected region */
00147   JCROP_CODE crop_xoffset_set;  /* (negative measures from right edge) */
00148   JDIMENSION crop_yoffset;  /* Y offset of selected region */
00149   JCROP_CODE crop_yoffset_set;  /* (negative measures from bottom edge) */
00150 
00151   /* Internal workspace: caller should not touch these */
00152   int num_components;       /* # of components in workspace */
00153   jvirt_barray_ptr * workspace_coef_arrays; /* workspace for transformations */
00154   JDIMENSION output_width;  /* cropped destination dimensions */
00155   JDIMENSION output_height;
00156   JDIMENSION x_crop_offset; /* destination crop offsets measured in iMCUs */
00157   JDIMENSION y_crop_offset;
00158   JDIMENSION drop_width;    /* drop/wipe dimensions measured in iMCUs */
00159   JDIMENSION drop_height;
00160   int iMCU_sample_width;    /* destination iMCU size */
00161   int iMCU_sample_height;
00162 } jpeg_transform_info;
00163 
00164 
00165 #if TRANSFORMS_SUPPORTED
00166 
00167 /* Parse a crop specification (written in X11 geometry style) */
00168 EXTERN(boolean) jtransform_parse_crop_spec
00169     JPP((jpeg_transform_info *info, const char *spec));
00170 /* Request any required workspace */
00171 EXTERN(boolean) jtransform_request_workspace
00172     JPP((j_decompress_ptr srcinfo, jpeg_transform_info *info));
00173 /* Adjust output image parameters */
00174 EXTERN(jvirt_barray_ptr *) jtransform_adjust_parameters
00175     JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
00176          jvirt_barray_ptr *src_coef_arrays,
00177          jpeg_transform_info *info));
00178 /* Execute the actual transformation, if any */
00179 EXTERN(void) jtransform_execute_transform
00180     JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
00181          jvirt_barray_ptr *src_coef_arrays,
00182          jpeg_transform_info *info));
00183 /* Determine whether lossless transformation is perfectly
00184  * possible for a specified image and transformation.
00185  */
00186 EXTERN(boolean) jtransform_perfect_transform
00187     JPP((JDIMENSION image_width, JDIMENSION image_height,
00188          int MCU_width, int MCU_height,
00189          JXFORM_CODE transform));
00190 
00191 /* jtransform_execute_transform used to be called
00192  * jtransform_execute_transformation, but some compilers complain about
00193  * routine names that long.  This macro is here to avoid breaking any
00194  * old source code that uses the original name...
00195  */
00196 #define jtransform_execute_transformation   jtransform_execute_transform
00197 
00198 #endif /* TRANSFORMS_SUPPORTED */
00199 
00200 
00201 /*
00202  * Support for copying optional markers from source to destination file.
00203  */
00204 
00205 typedef enum {
00206     JCOPYOPT_NONE,      /* copy no optional markers */
00207     JCOPYOPT_COMMENTS,  /* copy only comment (COM) markers */
00208     JCOPYOPT_ALL        /* copy all optional markers */
00209 } JCOPY_OPTION;
00210 
00211 #define JCOPYOPT_DEFAULT  JCOPYOPT_COMMENTS /* recommended default */
00212 
00213 /* Setup decompression object to save desired markers in memory */
00214 EXTERN(void) jcopy_markers_setup
00215     JPP((j_decompress_ptr srcinfo, JCOPY_OPTION option));
00216 /* Copy markers saved in the given source object to the destination object */
00217 EXTERN(void) jcopy_markers_execute
00218     JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
00219          JCOPY_OPTION option));