Home | History | Annotate | Download | only in jpeg-6b
      1 /*
      2  * transupp.h
      3  *
      4  * Copyright (C) 1997, Thomas G. Lane.
      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 /* Short forms of external names for systems with brain-damaged linkers. */
     26 
     27 #ifdef NEED_SHORT_EXTERNAL_NAMES
     28 #define jtransform_request_workspace		jTrRequest
     29 #define jtransform_adjust_parameters		jTrAdjust
     30 #define jtransform_execute_transformation	jTrExec
     31 #define jcopy_markers_setup			jCMrkSetup
     32 #define jcopy_markers_execute			jCMrkExec
     33 #endif /* NEED_SHORT_EXTERNAL_NAMES */
     34 
     35 
     36 /*
     37  * Codes for supported types of image transformations.
     38  */
     39 
     40 typedef enum {
     41 	JXFORM_NONE,		/* no transformation */
     42 	JXFORM_FLIP_H,		/* horizontal flip */
     43 	JXFORM_FLIP_V,		/* vertical flip */
     44 	JXFORM_TRANSPOSE,	/* transpose across UL-to-LR axis */
     45 	JXFORM_TRANSVERSE,	/* transpose across UR-to-LL axis */
     46 	JXFORM_ROT_90,		/* 90-degree clockwise rotation */
     47 	JXFORM_ROT_180,		/* 180-degree rotation */
     48 	JXFORM_ROT_270		/* 270-degree clockwise (or 90 ccw) */
     49 } JXFORM_CODE;
     50 
     51 /*
     52  * Although rotating and flipping data expressed as DCT coefficients is not
     53  * hard, there is an asymmetry in the JPEG format specification for images
     54  * whose dimensions aren't multiples of the iMCU size.  The right and bottom
     55  * image edges are padded out to the next iMCU boundary with junk data; but
     56  * no padding is possible at the top and left edges.  If we were to flip
     57  * the whole image including the pad data, then pad garbage would become
     58  * visible at the top and/or left, and real pixels would disappear into the
     59  * pad margins --- perhaps permanently, since encoders & decoders may not
     60  * bother to preserve DCT blocks that appear to be completely outside the
     61  * nominal image area.  So, we have to exclude any partial iMCUs from the
     62  * basic transformation.
     63  *
     64  * Transpose is the only transformation that can handle partial iMCUs at the
     65  * right and bottom edges completely cleanly.  flip_h can flip partial iMCUs
     66  * at the bottom, but leaves any partial iMCUs at the right edge untouched.
     67  * Similarly flip_v leaves any partial iMCUs at the bottom edge untouched.
     68  * The other transforms are defined as combinations of these basic transforms
     69  * and process edge blocks in a way that preserves the equivalence.
     70  *
     71  * The "trim" option causes untransformable partial iMCUs to be dropped;
     72  * this is not strictly lossless, but it usually gives the best-looking
     73  * result for odd-size images.  Note that when this option is active,
     74  * the expected mathematical equivalences between the transforms may not hold.
     75  * (For example, -rot 270 -trim trims only the bottom edge, but -rot 90 -trim
     76  * followed by -rot 180 -trim trims both edges.)
     77  *
     78  * We also offer a "force to grayscale" option, which simply discards the
     79  * chrominance channels of a YCbCr image.  This is lossless in the sense that
     80  * the luminance channel is preserved exactly.  It's not the same kind of
     81  * thing as the rotate/flip transformations, but it's convenient to handle it
     82  * as part of this package, mainly because the transformation routines have to
     83  * be aware of the option to know how many components to work on.
     84  */
     85 
     86 typedef struct {
     87   /* Options: set by caller */
     88   JXFORM_CODE transform;	/* image transform operator */
     89   boolean trim;			/* if TRUE, trim partial MCUs as needed */
     90   boolean force_grayscale;	/* if TRUE, convert color image to grayscale */
     91 
     92   /* Internal workspace: caller should not touch these */
     93   int num_components;		/* # of components in workspace */
     94   jvirt_barray_ptr * workspace_coef_arrays; /* workspace for transformations */
     95 } jpeg_transform_info;
     96 
     97 
     98 #if TRANSFORMS_SUPPORTED
     99 
    100 /* Request any required workspace */
    101 EXTERN(void) jtransform_request_workspace
    102 	JPP((j_decompress_ptr srcinfo, jpeg_transform_info *info));
    103 /* Adjust output image parameters */
    104 EXTERN(jvirt_barray_ptr *) jtransform_adjust_parameters
    105 	JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
    106 	     jvirt_barray_ptr *src_coef_arrays,
    107 	     jpeg_transform_info *info));
    108 /* Execute the actual transformation, if any */
    109 EXTERN(void) jtransform_execute_transformation
    110 	JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
    111 	     jvirt_barray_ptr *src_coef_arrays,
    112 	     jpeg_transform_info *info));
    113 
    114 #endif /* TRANSFORMS_SUPPORTED */
    115 
    116 
    117 /*
    118  * Support for copying optional markers from source to destination file.
    119  */
    120 
    121 typedef enum {
    122 	JCOPYOPT_NONE,		/* copy no optional markers */
    123 	JCOPYOPT_COMMENTS,	/* copy only comment (COM) markers */
    124 	JCOPYOPT_ALL		/* copy all optional markers */
    125 } JCOPY_OPTION;
    126 
    127 #define JCOPYOPT_DEFAULT  JCOPYOPT_COMMENTS	/* recommended default */
    128 
    129 /* Setup decompression object to save desired markers in memory */
    130 EXTERN(void) jcopy_markers_setup
    131 	JPP((j_decompress_ptr srcinfo, JCOPY_OPTION option));
    132 /* Copy markers saved in the given source object to the destination object */
    133 EXTERN(void) jcopy_markers_execute
    134 	JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo,
    135 	     JCOPY_OPTION option));
    136