jpegint.h

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