Home | History | Annotate | Download | only in libjpeg-turbo
      1 /*
      2  * jpegint.h
      3  *
      4  * This file was part of the Independent JPEG Group's software:
      5  * Copyright (C) 1991-1997, Thomas G. Lane.
      6  * Modified 1997-2009 by Guido Vollbeding.
      7  * libjpeg-turbo Modifications:
      8  * Copyright (C) 2015-2016, D. R. Commander
      9  * Copyright (C) 2015, Google, Inc.
     10  * For conditions of distribution and use, see the accompanying README.ijg
     11  * file.
     12  *
     13  * This file provides common declarations for the various JPEG modules.
     14  * These declarations are considered internal to the JPEG library; most
     15  * applications using the library shouldn't need to include this file.
     16  */
     17 
     18 
     19 /* Declarations for both compression & decompression */
     20 
     21 typedef enum {            /* Operating modes for buffer controllers */
     22   JBUF_PASS_THRU,         /* Plain stripwise operation */
     23   /* Remaining modes require a full-image buffer to have been created */
     24   JBUF_SAVE_SOURCE,       /* Run source subobject only, save output */
     25   JBUF_CRANK_DEST,        /* Run dest subobject only, using saved data */
     26   JBUF_SAVE_AND_PASS      /* Run both subobjects, save output */
     27 } J_BUF_MODE;
     28 
     29 /* Values of global_state field (jdapi.c has some dependencies on ordering!) */
     30 #define CSTATE_START    100     /* after create_compress */
     31 #define CSTATE_SCANNING 101     /* start_compress done, write_scanlines OK */
     32 #define CSTATE_RAW_OK   102     /* start_compress done, write_raw_data OK */
     33 #define CSTATE_WRCOEFS  103     /* jpeg_write_coefficients done */
     34 #define DSTATE_START    200     /* after create_decompress */
     35 #define DSTATE_INHEADER 201     /* reading header markers, no SOS yet */
     36 #define DSTATE_READY    202     /* found SOS, ready for start_decompress */
     37 #define DSTATE_PRELOAD  203     /* reading multiscan file in start_decompress*/
     38 #define DSTATE_PRESCAN  204     /* performing dummy pass for 2-pass quant */
     39 #define DSTATE_SCANNING 205     /* start_decompress done, read_scanlines OK */
     40 #define DSTATE_RAW_OK   206     /* start_decompress done, read_raw_data OK */
     41 #define DSTATE_BUFIMAGE 207     /* expecting jpeg_start_output */
     42 #define DSTATE_BUFPOST  208     /* looking for SOS/EOI in jpeg_finish_output */
     43 #define DSTATE_RDCOEFS  209     /* reading file in jpeg_read_coefficients */
     44 #define DSTATE_STOPPING 210     /* looking for EOI in jpeg_finish_decompress */
     45 
     46 
     47 /*
     48  * Left shift macro that handles a negative operand without causing any
     49  * sanitizer warnings
     50  */
     51 
     52 #ifdef __INT32_IS_ACTUALLY_LONG
     53 #define LEFT_SHIFT(a, b) ((INT32)((unsigned long)(a) << (b)))
     54 #else
     55 #define LEFT_SHIFT(a, b) ((INT32)((unsigned int)(a) << (b)))
     56 #endif
     57 
     58 
     59 /* Declarations for compression modules */
     60 
     61 /* Master control module */
     62 struct jpeg_comp_master {
     63   void (*prepare_for_pass) (j_compress_ptr cinfo);
     64   void (*pass_startup) (j_compress_ptr cinfo);
     65   void (*finish_pass) (j_compress_ptr cinfo);
     66 
     67   /* State variables made visible to other modules */
     68   boolean call_pass_startup;    /* True if pass_startup must be called */
     69   boolean is_last_pass;         /* True during last pass */
     70 };
     71 
     72 /* Main buffer control (downsampled-data buffer) */
     73 struct jpeg_c_main_controller {
     74   void (*start_pass) (j_compress_ptr cinfo, J_BUF_MODE pass_mode);
     75   void (*process_data) (j_compress_ptr cinfo, JSAMPARRAY input_buf,
     76                         JDIMENSION *in_row_ctr, JDIMENSION in_rows_avail);
     77 };
     78 
     79 /* Compression preprocessing (downsampling input buffer control) */
     80 struct jpeg_c_prep_controller {
     81   void (*start_pass) (j_compress_ptr cinfo, J_BUF_MODE pass_mode);
     82   void (*pre_process_data) (j_compress_ptr cinfo, JSAMPARRAY input_buf,
     83                             JDIMENSION *in_row_ctr, JDIMENSION in_rows_avail,
     84                             JSAMPIMAGE output_buf,
     85                             JDIMENSION *out_row_group_ctr,
     86                             JDIMENSION out_row_groups_avail);
     87 };
     88 
     89 /* Coefficient buffer control */
     90 struct jpeg_c_coef_controller {
     91   void (*start_pass) (j_compress_ptr cinfo, J_BUF_MODE pass_mode);
     92   boolean (*compress_data) (j_compress_ptr cinfo, JSAMPIMAGE input_buf);
     93 };
     94 
     95 /* Colorspace conversion */
     96 struct jpeg_color_converter {
     97   void (*start_pass) (j_compress_ptr cinfo);
     98   void (*color_convert) (j_compress_ptr cinfo, JSAMPARRAY input_buf,
     99                          JSAMPIMAGE output_buf, JDIMENSION output_row,
    100                          int num_rows);
    101 };
    102 
    103 /* Downsampling */
    104 struct jpeg_downsampler {
    105   void (*start_pass) (j_compress_ptr cinfo);
    106   void (*downsample) (j_compress_ptr cinfo, JSAMPIMAGE input_buf,
    107                       JDIMENSION in_row_index, JSAMPIMAGE output_buf,
    108                       JDIMENSION out_row_group_index);
    109 
    110   boolean need_context_rows;    /* TRUE if need rows above & below */
    111 };
    112 
    113 /* Forward DCT (also controls coefficient quantization) */
    114 struct jpeg_forward_dct {
    115   void (*start_pass) (j_compress_ptr cinfo);
    116   /* perhaps this should be an array??? */
    117   void (*forward_DCT) (j_compress_ptr cinfo, jpeg_component_info * compptr,
    118                        JSAMPARRAY sample_data, JBLOCKROW coef_blocks,
    119                        JDIMENSION start_row, JDIMENSION start_col,
    120                        JDIMENSION num_blocks);
    121 };
    122 
    123 /* Entropy encoding */
    124 struct jpeg_entropy_encoder {
    125   void (*start_pass) (j_compress_ptr cinfo, boolean gather_statistics);
    126   boolean (*encode_mcu) (j_compress_ptr cinfo, JBLOCKROW *MCU_data);
    127   void (*finish_pass) (j_compress_ptr cinfo);
    128 };
    129 
    130 /* Marker writing */
    131 struct jpeg_marker_writer {
    132   void (*write_file_header) (j_compress_ptr cinfo);
    133   void (*write_frame_header) (j_compress_ptr cinfo);
    134   void (*write_scan_header) (j_compress_ptr cinfo);
    135   void (*write_file_trailer) (j_compress_ptr cinfo);
    136   void (*write_tables_only) (j_compress_ptr cinfo);
    137   /* These routines are exported to allow insertion of extra markers */
    138   /* Probably only COM and APPn markers should be written this way */
    139   void (*write_marker_header) (j_compress_ptr cinfo, int marker,
    140                                unsigned int datalen);
    141   void (*write_marker_byte) (j_compress_ptr cinfo, int val);
    142 };
    143 
    144 
    145 /* Declarations for decompression modules */
    146 
    147 /* Master control module */
    148 struct jpeg_decomp_master {
    149   void (*prepare_for_output_pass) (j_decompress_ptr cinfo);
    150   void (*finish_output_pass) (j_decompress_ptr cinfo);
    151 
    152   /* State variables made visible to other modules */
    153   boolean is_dummy_pass;        /* True during 1st pass for 2-pass quant */
    154 
    155   /* Partial decompression variables */
    156   JDIMENSION first_iMCU_col;
    157   JDIMENSION last_iMCU_col;
    158   JDIMENSION first_MCU_col[MAX_COMPS_IN_SCAN];
    159   JDIMENSION last_MCU_col[MAX_COMPS_IN_SCAN];
    160   boolean jinit_upsampler_no_alloc;
    161 };
    162 
    163 /* Input control module */
    164 struct jpeg_input_controller {
    165   int (*consume_input) (j_decompress_ptr cinfo);
    166   void (*reset_input_controller) (j_decompress_ptr cinfo);
    167   void (*start_input_pass) (j_decompress_ptr cinfo);
    168   void (*finish_input_pass) (j_decompress_ptr cinfo);
    169 
    170   /* State variables made visible to other modules */
    171   boolean has_multiple_scans;   /* True if file has multiple scans */
    172   boolean eoi_reached;          /* True when EOI has been consumed */
    173 };
    174 
    175 /* Main buffer control (downsampled-data buffer) */
    176 struct jpeg_d_main_controller {
    177   void (*start_pass) (j_decompress_ptr cinfo, J_BUF_MODE pass_mode);
    178   void (*process_data) (j_decompress_ptr cinfo, JSAMPARRAY output_buf,
    179                         JDIMENSION *out_row_ctr, JDIMENSION out_rows_avail);
    180 };
    181 
    182 /* Coefficient buffer control */
    183 struct jpeg_d_coef_controller {
    184   void (*start_input_pass) (j_decompress_ptr cinfo);
    185   int (*consume_data) (j_decompress_ptr cinfo);
    186   void (*start_output_pass) (j_decompress_ptr cinfo);
    187   int (*decompress_data) (j_decompress_ptr cinfo, JSAMPIMAGE output_buf);
    188   /* Pointer to array of coefficient virtual arrays, or NULL if none */
    189   jvirt_barray_ptr *coef_arrays;
    190 };
    191 
    192 /* Decompression postprocessing (color quantization buffer control) */
    193 struct jpeg_d_post_controller {
    194   void (*start_pass) (j_decompress_ptr cinfo, J_BUF_MODE pass_mode);
    195   void (*post_process_data) (j_decompress_ptr cinfo, JSAMPIMAGE input_buf,
    196                              JDIMENSION *in_row_group_ctr,
    197                              JDIMENSION in_row_groups_avail,
    198                              JSAMPARRAY output_buf, JDIMENSION *out_row_ctr,
    199                              JDIMENSION out_rows_avail);
    200 };
    201 
    202 /* Marker reading & parsing */
    203 struct jpeg_marker_reader {
    204   void (*reset_marker_reader) (j_decompress_ptr cinfo);
    205   /* Read markers until SOS or EOI.
    206    * Returns same codes as are defined for jpeg_consume_input:
    207    * JPEG_SUSPENDED, JPEG_REACHED_SOS, or JPEG_REACHED_EOI.
    208    */
    209   int (*read_markers) (j_decompress_ptr cinfo);
    210   /* Read a restart marker --- exported for use by entropy decoder only */
    211   jpeg_marker_parser_method read_restart_marker;
    212 
    213   /* State of marker reader --- nominally internal, but applications
    214    * supplying COM or APPn handlers might like to know the state.
    215    */
    216   boolean saw_SOI;              /* found SOI? */
    217   boolean saw_SOF;              /* found SOF? */
    218   int next_restart_num;         /* next restart number expected (0-7) */
    219   unsigned int discarded_bytes; /* # of bytes skipped looking for a marker */
    220 };
    221 
    222 /* Entropy decoding */
    223 struct jpeg_entropy_decoder {
    224   void (*start_pass) (j_decompress_ptr cinfo);
    225   boolean (*decode_mcu) (j_decompress_ptr cinfo, JBLOCKROW *MCU_data);
    226 
    227   /* This is here to share code between baseline and progressive decoders; */
    228   /* other modules probably should not use it */
    229   boolean insufficient_data;    /* set TRUE after emitting warning */
    230 };
    231 
    232 /* Inverse DCT (also performs dequantization) */
    233 typedef void (*inverse_DCT_method_ptr) (j_decompress_ptr cinfo,
    234                                         jpeg_component_info * compptr,
    235                                         JCOEFPTR coef_block,
    236                                         JSAMPARRAY output_buf,
    237                                         JDIMENSION output_col);
    238 
    239 struct jpeg_inverse_dct {
    240   void (*start_pass) (j_decompress_ptr cinfo);
    241   /* It is useful to allow each component to have a separate IDCT method. */
    242   inverse_DCT_method_ptr inverse_DCT[MAX_COMPONENTS];
    243 };
    244 
    245 /* Upsampling (note that upsampler must also call color converter) */
    246 struct jpeg_upsampler {
    247   void (*start_pass) (j_decompress_ptr cinfo);
    248   void (*upsample) (j_decompress_ptr cinfo, JSAMPIMAGE input_buf,
    249                     JDIMENSION *in_row_group_ctr,
    250                     JDIMENSION in_row_groups_avail, JSAMPARRAY output_buf,
    251                     JDIMENSION *out_row_ctr, JDIMENSION out_rows_avail);
    252 
    253   boolean need_context_rows;    /* TRUE if need rows above & below */
    254 };
    255 
    256 /* Colorspace conversion */
    257 struct jpeg_color_deconverter {
    258   void (*start_pass) (j_decompress_ptr cinfo);
    259   void (*color_convert) (j_decompress_ptr cinfo, JSAMPIMAGE input_buf,
    260                          JDIMENSION input_row, JSAMPARRAY output_buf,
    261                          int num_rows);
    262 };
    263 
    264 /* Color quantization or color precision reduction */
    265 struct jpeg_color_quantizer {
    266   void (*start_pass) (j_decompress_ptr cinfo, boolean is_pre_scan);
    267   void (*color_quantize) (j_decompress_ptr cinfo, JSAMPARRAY input_buf,
    268                           JSAMPARRAY output_buf, int num_rows);
    269   void (*finish_pass) (j_decompress_ptr cinfo);
    270   void (*new_color_map) (j_decompress_ptr cinfo);
    271 };
    272 
    273 
    274 /* Miscellaneous useful macros */
    275 
    276 #undef MAX
    277 #define MAX(a,b)        ((a) > (b) ? (a) : (b))
    278 #undef MIN
    279 #define MIN(a,b)        ((a) < (b) ? (a) : (b))
    280 
    281 
    282 /* We assume that right shift corresponds to signed division by 2 with
    283  * rounding towards minus infinity.  This is correct for typical "arithmetic
    284  * shift" instructions that shift in copies of the sign bit.  But some
    285  * C compilers implement >> with an unsigned shift.  For these machines you
    286  * must define RIGHT_SHIFT_IS_UNSIGNED.
    287  * RIGHT_SHIFT provides a proper signed right shift of an INT32 quantity.
    288  * It is only applied with constant shift counts.  SHIFT_TEMPS must be
    289  * included in the variables of any routine using RIGHT_SHIFT.
    290  */
    291 
    292 #ifdef RIGHT_SHIFT_IS_UNSIGNED
    293 #define SHIFT_TEMPS     INT32 shift_temp;
    294 #define RIGHT_SHIFT(x,shft)  \
    295         ((shift_temp = (x)) < 0 ? \
    296          (shift_temp >> (shft)) | ((~((INT32) 0)) << (32-(shft))) : \
    297          (shift_temp >> (shft)))
    298 #else
    299 #define SHIFT_TEMPS
    300 #define RIGHT_SHIFT(x,shft)     ((x) >> (shft))
    301 #endif
    302 
    303 
    304 /* Compression module initialization routines */
    305 EXTERN(void) jinit_compress_master (j_compress_ptr cinfo);
    306 EXTERN(void) jinit_c_master_control (j_compress_ptr cinfo,
    307                                      boolean transcode_only);
    308 EXTERN(void) jinit_c_main_controller (j_compress_ptr cinfo,
    309                                       boolean need_full_buffer);
    310 EXTERN(void) jinit_c_prep_controller (j_compress_ptr cinfo,
    311                                       boolean need_full_buffer);
    312 EXTERN(void) jinit_c_coef_controller (j_compress_ptr cinfo,
    313                                       boolean need_full_buffer);
    314 EXTERN(void) jinit_color_converter (j_compress_ptr cinfo);
    315 EXTERN(void) jinit_downsampler (j_compress_ptr cinfo);
    316 EXTERN(void) jinit_forward_dct (j_compress_ptr cinfo);
    317 EXTERN(void) jinit_huff_encoder (j_compress_ptr cinfo);
    318 EXTERN(void) jinit_phuff_encoder (j_compress_ptr cinfo);
    319 EXTERN(void) jinit_arith_encoder (j_compress_ptr cinfo);
    320 EXTERN(void) jinit_marker_writer (j_compress_ptr cinfo);
    321 /* Decompression module initialization routines */
    322 EXTERN(void) jinit_master_decompress (j_decompress_ptr cinfo);
    323 EXTERN(void) jinit_d_main_controller (j_decompress_ptr cinfo,
    324                                       boolean need_full_buffer);
    325 EXTERN(void) jinit_d_coef_controller (j_decompress_ptr cinfo,
    326                                       boolean need_full_buffer);
    327 EXTERN(void) jinit_d_post_controller (j_decompress_ptr cinfo,
    328                                       boolean need_full_buffer);
    329 EXTERN(void) jinit_input_controller (j_decompress_ptr cinfo);
    330 EXTERN(void) jinit_marker_reader (j_decompress_ptr cinfo);
    331 EXTERN(void) jinit_huff_decoder (j_decompress_ptr cinfo);
    332 EXTERN(void) jinit_phuff_decoder (j_decompress_ptr cinfo);
    333 EXTERN(void) jinit_arith_decoder (j_decompress_ptr cinfo);
    334 EXTERN(void) jinit_inverse_dct (j_decompress_ptr cinfo);
    335 EXTERN(void) jinit_upsampler (j_decompress_ptr cinfo);
    336 EXTERN(void) jinit_color_deconverter (j_decompress_ptr cinfo);
    337 EXTERN(void) jinit_1pass_quantizer (j_decompress_ptr cinfo);
    338 EXTERN(void) jinit_2pass_quantizer (j_decompress_ptr cinfo);
    339 EXTERN(void) jinit_merged_upsampler (j_decompress_ptr cinfo);
    340 /* Memory manager initialization */
    341 EXTERN(void) jinit_memory_mgr (j_common_ptr cinfo);
    342 
    343 /* Utility routines in jutils.c */
    344 EXTERN(long) jdiv_round_up (long a, long b);
    345 EXTERN(long) jround_up (long a, long b);
    346 EXTERN(void) jcopy_sample_rows (JSAMPARRAY input_array, int source_row,
    347                                 JSAMPARRAY output_array, int dest_row,
    348                                 int num_rows, JDIMENSION num_cols);
    349 EXTERN(void) jcopy_block_row (JBLOCKROW input_row, JBLOCKROW output_row,
    350                               JDIMENSION num_blocks);
    351 EXTERN(void) jzero_far (void * target, size_t bytestozero);
    352 /* Constant tables in jutils.c */
    353 #if 0                           /* This table is not actually needed in v6a */
    354 extern const int jpeg_zigzag_order[]; /* natural coef order to zigzag order */
    355 #endif
    356 extern const int jpeg_natural_order[]; /* zigzag coef order to natural order */
    357 
    358 /* Arithmetic coding probability estimation tables in jaricom.c */
    359 extern const INT32 jpeg_aritab[];
    360 
    361 /* Suppress undefined-structure complaints if necessary. */
    362 
    363 #ifdef INCOMPLETE_TYPES_BROKEN
    364 #ifndef AM_MEMORY_MANAGER       /* only jmemmgr.c defines these */
    365 struct jvirt_sarray_control { long dummy; };
    366 struct jvirt_barray_control { long dummy; };
    367 #endif
    368 #endif /* INCOMPLETE_TYPES_BROKEN */
    369