| 1 | /*
|
|---|
| 2 | * transupp.h
|
|---|
| 3 | *
|
|---|
| 4 | * Copyright (C) 1997-2009, Thomas G. Lane, Guido Vollbeding.
|
|---|
| 5 | * This file is part of the Independent JPEG Group's software.
|
|---|
| 6 | * For conditions of distribution and use, see the accompanying README file.
|
|---|
| 7 | *
|
|---|
| 8 | * This file contains declarations for image transformation routines and
|
|---|
| 9 | * other utility code used by the jpegtran sample application. These are
|
|---|
| 10 | * NOT part of the core JPEG library. But we keep these routines separate
|
|---|
| 11 | * from jpegtran.c to ease the task of maintaining jpegtran-like programs
|
|---|
| 12 | * that have other user interfaces.
|
|---|
| 13 | *
|
|---|
| 14 | * NOTE: all the routines declared here have very specific requirements
|
|---|
| 15 | * about when they are to be executed during the reading and writing of the
|
|---|
| 16 | * source and destination files. See the comments in transupp.c, or see
|
|---|
| 17 | * jpegtran.c for an example of correct usage.
|
|---|
| 18 | */
|
|---|
| 19 |
|
|---|
| 20 | /* If you happen not to want the image transform support, disable it here */
|
|---|
| 21 | #ifndef TRANSFORMS_SUPPORTED
|
|---|
| 22 | #define TRANSFORMS_SUPPORTED 1 /* 0 disables transform code */
|
|---|
| 23 | #endif
|
|---|
| 24 |
|
|---|
| 25 | /*
|
|---|
| 26 | * Although rotating and flipping data expressed as DCT coefficients is not
|
|---|
| 27 | * hard, there is an asymmetry in the JPEG format specification for images
|
|---|
| 28 | * whose dimensions aren't multiples of the iMCU size. The right and bottom
|
|---|
| 29 | * image edges are padded out to the next iMCU boundary with junk data; but
|
|---|
| 30 | * no padding is possible at the top and left edges. If we were to flip
|
|---|
| 31 | * the whole image including the pad data, then pad garbage would become
|
|---|
| 32 | * visible at the top and/or left, and real pixels would disappear into the
|
|---|
| 33 | * pad margins --- perhaps permanently, since encoders & decoders may not
|
|---|
| 34 | * bother to preserve DCT blocks that appear to be completely outside the
|
|---|
| 35 | * nominal image area. So, we have to exclude any partial iMCUs from the
|
|---|
| 36 | * basic transformation.
|
|---|
| 37 | *
|
|---|
| 38 | * Transpose is the only transformation that can handle partial iMCUs at the
|
|---|
| 39 | * right and bottom edges completely cleanly. flip_h can flip partial iMCUs
|
|---|
| 40 | * at the bottom, but leaves any partial iMCUs at the right edge untouched.
|
|---|
| 41 | * Similarly flip_v leaves any partial iMCUs at the bottom edge untouched.
|
|---|
| 42 | * The other transforms are defined as combinations of these basic transforms
|
|---|
| 43 | * and process edge blocks in a way that preserves the equivalence.
|
|---|
| 44 | *
|
|---|
| 45 | * The "trim" option causes untransformable partial iMCUs to be dropped;
|
|---|
| 46 | * this is not strictly lossless, but it usually gives the best-looking
|
|---|
| 47 | * result for odd-size images. Note that when this option is active,
|
|---|
| 48 | * the expected mathematical equivalences between the transforms may not hold.
|
|---|
| 49 | * (For example, -rot 270 -trim trims only the bottom edge, but -rot 90 -trim
|
|---|
| 50 | * followed by -rot 180 -trim trims both edges.)
|
|---|
| 51 | *
|
|---|
| 52 | * We also offer a lossless-crop option, which discards data outside a given
|
|---|
| 53 | * image region but losslessly preserves what is inside. Like the rotate and
|
|---|
| 54 | * flip transforms, lossless crop is restricted by the JPEG format: the upper
|
|---|
| 55 | * left corner of the selected region must fall on an iMCU boundary. If this
|
|---|
| 56 | * does not hold for the given crop parameters, we silently move the upper left
|
|---|
| 57 | * corner up and/or left to make it so, simultaneously increasing the region
|
|---|
| 58 | * dimensions to keep the lower right crop corner unchanged. (Thus, the
|
|---|
| 59 | * output image covers at least the requested region, but may cover more.)
|
|---|
| 60 | *
|
|---|
| 61 | * We also provide a lossless-resize option, which is kind of a lossless-crop
|
|---|
| 62 | * operation in the DCT coefficient block domain - it discards higher-order
|
|---|
| 63 | * coefficients and losslessly preserves lower-order coefficients of a
|
|---|
| 64 | * sub-block.
|
|---|
| 65 | *
|
|---|
| 66 | * Rotate/flip transform, resize, and crop can be requested together in a
|
|---|
| 67 | * single invocation. The crop is applied last --- that is, the crop region
|
|---|
| 68 | * is specified in terms of the destination image after transform/resize.
|
|---|
| 69 | *
|
|---|
| 70 | * We also offer a "force to grayscale" option, which simply discards the
|
|---|
| 71 | * chrominance channels of a YCbCr image. This is lossless in the sense that
|
|---|
| 72 | * the luminance channel is preserved exactly. It's not the same kind of
|
|---|
| 73 | * thing as the rotate/flip transformations, but it's convenient to handle it
|
|---|
| 74 | * as part of this package, mainly because the transformation routines have to
|
|---|
| 75 | * be aware of the option to know how many components to work on.
|
|---|
| 76 | */
|
|---|
| 77 |
|
|---|
| 78 |
|
|---|
| 79 | /* Short forms of external names for systems with brain-damaged linkers. */
|
|---|
| 80 |
|
|---|
| 81 | #ifdef NEED_SHORT_EXTERNAL_NAMES
|
|---|
| 82 | #define jtransform_parse_crop_spec jTrParCrop
|
|---|
| 83 | #define jtransform_request_workspace jTrRequest
|
|---|
| 84 | #define jtransform_adjust_parameters jTrAdjust
|
|---|
| 85 | #define jtransform_execute_transform jTrExec
|
|---|
| 86 | #define jtransform_perfect_transform jTrPerfect
|
|---|
| 87 | #define jcopy_markers_setup jCMrkSetup
|
|---|
| 88 | #define jcopy_markers_execute jCMrkExec
|
|---|
| 89 | #endif /* NEED_SHORT_EXTERNAL_NAMES */
|
|---|
| 90 |
|
|---|
| 91 |
|
|---|
| 92 | /*
|
|---|
| 93 | * Codes for supported types of image transformations.
|
|---|
| 94 | */
|
|---|
| 95 |
|
|---|
| 96 | typedef enum {
|
|---|
| 97 | JXFORM_NONE, /* no transformation */
|
|---|
| 98 | JXFORM_FLIP_H, /* horizontal flip */
|
|---|
| 99 | JXFORM_FLIP_V, /* vertical flip */
|
|---|
| 100 | JXFORM_TRANSPOSE, /* transpose across UL-to-LR axis */
|
|---|
| 101 | JXFORM_TRANSVERSE, /* transpose across UR-to-LL axis */
|
|---|
| 102 | JXFORM_ROT_90, /* 90-degree clockwise rotation */
|
|---|
| 103 | JXFORM_ROT_180, /* 180-degree rotation */
|
|---|
| 104 | JXFORM_ROT_270 /* 270-degree clockwise (or 90 ccw) */
|
|---|
| 105 | } JXFORM_CODE;
|
|---|
| 106 |
|
|---|
| 107 | /*
|
|---|
| 108 | * Codes for crop parameters, which can individually be unspecified,
|
|---|
| 109 | * positive, or negative. (Negative width or height makes no sense, though.)
|
|---|
| 110 | */
|
|---|
| 111 |
|
|---|
| 112 | typedef enum {
|
|---|
| 113 | JCROP_UNSET,
|
|---|
| 114 | JCROP_POS,
|
|---|
| 115 | JCROP_NEG
|
|---|
| 116 | } JCROP_CODE;
|
|---|
| 117 |
|
|---|
| 118 | /*
|
|---|
| 119 | * Transform parameters struct.
|
|---|
| 120 | * NB: application must not change any elements of this struct after
|
|---|
| 121 | * calling jtransform_request_workspace.
|
|---|
| 122 | */
|
|---|
| 123 |
|
|---|
| 124 | typedef struct {
|
|---|
| 125 | /* Options: set by caller */
|
|---|
| 126 | JXFORM_CODE transform; /* image transform operator */
|
|---|
| 127 | boolean perfect; /* if TRUE, fail if partial MCUs are requested */
|
|---|
| 128 | boolean trim; /* if TRUE, trim partial MCUs as needed */
|
|---|
| 129 | boolean force_grayscale; /* if TRUE, convert color image to grayscale */
|
|---|
| 130 | boolean crop; /* if TRUE, crop source image */
|
|---|
| 131 |
|
|---|
| 132 | /* Crop parameters: application need not set these unless crop is TRUE.
|
|---|
| 133 | * These can be filled in by jtransform_parse_crop_spec().
|
|---|
| 134 | */
|
|---|
| 135 | JDIMENSION crop_width; /* Width of selected region */
|
|---|
| 136 | JCROP_CODE crop_width_set;
|
|---|
| 137 | JDIMENSION crop_height; /* Height of selected region */
|
|---|
| 138 | JCROP_CODE crop_height_set;
|
|---|
| 139 | JDIMENSION crop_xoffset; /* X offset of selected region */
|
|---|
| 140 | JCROP_CODE crop_xoffset_set; /* (negative measures from right edge) */
|
|---|
| 141 | JDIMENSION crop_yoffset; /* Y offset of selected region */
|
|---|
| 142 | JCROP_CODE crop_yoffset_set; /* (negative measures from bottom edge) */
|
|---|
| 143 |
|
|---|
| 144 | /* Internal workspace: caller should not touch these */
|
|---|
| 145 | int num_components; /* # of components in workspace */
|
|---|
| 146 | jvirt_barray_ptr * workspace_coef_arrays; /* workspace for transformations */
|
|---|
| 147 | JDIMENSION output_width; /* cropped destination dimensions */
|
|---|
| 148 | JDIMENSION output_height;
|
|---|
| 149 | JDIMENSION x_crop_offset; /* destination crop offsets measured in iMCUs */
|
|---|
| 150 | JDIMENSION y_crop_offset;
|
|---|
| 151 | int iMCU_sample_width; /* destination iMCU size */
|
|---|
| 152 | int iMCU_sample_height;
|
|---|
| 153 | } jpeg_transform_info;
|
|---|
| 154 |
|
|---|
| 155 |
|
|---|
| 156 | #if TRANSFORMS_SUPPORTED
|
|---|
| 157 |
|
|---|
| 158 | /* Parse a crop specification (written in X11 geometry style) */
|
|---|
| 159 | EXTERN(boolean) jtransform_parse_crop_spec
|
|---|
| 160 | JPP((jpeg_transform_info *info, const char *spec));
|
|---|
| 161 | /* Request any required workspace */
|
|---|
| 162 | EXTERN(boolean) jtransform_request_workspace
|
|---|
| 163 | JPP((j_decompress_ptr srcinfo, jpeg_transform_info *info));
|
|---|
| 164 | /* Adjust output image parameters */
|
|---|
| 165 | EXTERN(jvirt_barray_ptr *) jtransform_adjust_parameters
|
|---|
| 166 | JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
|
|---|
| 167 | jvirt_barray_ptr *src_coef_arrays,
|
|---|
| 168 | jpeg_transform_info *info));
|
|---|
| 169 | /* Execute the actual transformation, if any */
|
|---|
| 170 | EXTERN(void) jtransform_execute_transform
|
|---|
| 171 | JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
|
|---|
| 172 | jvirt_barray_ptr *src_coef_arrays,
|
|---|
| 173 | jpeg_transform_info *info));
|
|---|
| 174 | /* Determine whether lossless transformation is perfectly
|
|---|
| 175 | * possible for a specified image and transformation.
|
|---|
| 176 | */
|
|---|
| 177 | EXTERN(boolean) jtransform_perfect_transform
|
|---|
| 178 | JPP((JDIMENSION image_width, JDIMENSION image_height,
|
|---|
| 179 | int MCU_width, int MCU_height,
|
|---|
| 180 | JXFORM_CODE transform));
|
|---|
| 181 |
|
|---|
| 182 | /* jtransform_execute_transform used to be called
|
|---|
| 183 | * jtransform_execute_transformation, but some compilers complain about
|
|---|
| 184 | * routine names that long. This macro is here to avoid breaking any
|
|---|
| 185 | * old source code that uses the original name...
|
|---|
| 186 | */
|
|---|
| 187 | #define jtransform_execute_transformation jtransform_execute_transform
|
|---|
| 188 |
|
|---|
| 189 | #endif /* TRANSFORMS_SUPPORTED */
|
|---|
| 190 |
|
|---|
| 191 |
|
|---|
| 192 | /*
|
|---|
| 193 | * Support for copying optional markers from source to destination file.
|
|---|
| 194 | */
|
|---|
| 195 |
|
|---|
| 196 | typedef enum {
|
|---|
| 197 | JCOPYOPT_NONE, /* copy no optional markers */
|
|---|
| 198 | JCOPYOPT_COMMENTS, /* copy only comment (COM) markers */
|
|---|
| 199 | JCOPYOPT_ALL /* copy all optional markers */
|
|---|
| 200 | } JCOPY_OPTION;
|
|---|
| 201 |
|
|---|
| 202 | #define JCOPYOPT_DEFAULT JCOPYOPT_COMMENTS /* recommended default */
|
|---|
| 203 |
|
|---|
| 204 | /* Setup decompression object to save desired markers in memory */
|
|---|
| 205 | EXTERN(void) jcopy_markers_setup
|
|---|
| 206 | JPP((j_decompress_ptr srcinfo, JCOPY_OPTION option));
|
|---|
| 207 | /* Copy markers saved in the given source object to the destination object */
|
|---|
| 208 | EXTERN(void) jcopy_markers_execute
|
|---|
| 209 | JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
|
|---|
| 210 | JCOPY_OPTION option));
|
|---|
