1 /* 2 * The copyright in this software is being made available under the 2-clauses 3 * BSD License, included below. This software may be subject to other third 4 * party and contributor rights, including patent rights, and no such rights 5 * are granted under this license. 6 * 7 * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium 8 * Copyright (c) 2002-2014, Professor Benoit Macq 9 * Copyright (c) 2001-2003, David Janssens 10 * Copyright (c) 2002-2003, Yannick Verschueren 11 * Copyright (c) 2003-2007, Francois-Olivier Devaux 12 * Copyright (c) 2003-2014, Antonin Descampe 13 * Copyright (c) 2005, Herve Drolon, FreeImage Team 14 * Copyright (c) 2008, 2011-2012, Centre National d'Etudes Spatiales (CNES), FR 15 * Copyright (c) 2012, CS Systemes d'Information, France 16 * Copyright (c) 2017, IntoPIX SA <support@intopix.com> 17 * All rights reserved. 18 * 19 * Redistribution and use in source and binary forms, with or without 20 * modification, are permitted provided that the following conditions 21 * are met: 22 * 1. Redistributions of source code must retain the above copyright 23 * notice, this list of conditions and the following disclaimer. 24 * 2. Redistributions in binary form must reproduce the above copyright 25 * notice, this list of conditions and the following disclaimer in the 26 * documentation and/or other materials provided with the distribution. 27 * 28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS' 29 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 30 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 31 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 32 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 33 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 34 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 35 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 36 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 37 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 38 * POSSIBILITY OF SUCH DAMAGE. 39 */ 40 #ifndef OPJ_TCD_H 41 #define OPJ_TCD_H 42 /** 43 @file tcd.h 44 @brief Implementation of a tile coder/decoder (TCD) 45 46 The functions in TCD.C encode or decode each tile independently from 47 each other. The functions in TCD.C are used by other functions in J2K.C. 48 */ 49 50 /** @defgroup TCD TCD - Implementation of a tile coder/decoder */ 51 /*@{*/ 52 53 54 /** 55 FIXME DOC 56 */ 57 typedef struct opj_tcd_pass { 58 OPJ_UINT32 rate; 59 OPJ_FLOAT64 distortiondec; 60 OPJ_UINT32 len; 61 OPJ_BITFIELD term : 1; 62 } opj_tcd_pass_t; 63 64 /** 65 FIXME DOC 66 */ 67 typedef struct opj_tcd_layer { 68 OPJ_UINT32 numpasses; /* Number of passes in the layer */ 69 OPJ_UINT32 len; /* len of information */ 70 OPJ_FLOAT64 disto; /* add for index (Cfr. Marcela) */ 71 OPJ_BYTE *data; /* data */ 72 } opj_tcd_layer_t; 73 74 /** 75 FIXME DOC 76 */ 77 typedef struct opj_tcd_cblk_enc { 78 OPJ_BYTE* data; /* Data */ 79 opj_tcd_layer_t* layers; /* layer information */ 80 opj_tcd_pass_t* passes; /* information about the passes */ 81 OPJ_INT32 x0, y0, x1, 82 y1; /* dimension of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */ 83 OPJ_UINT32 numbps; 84 OPJ_UINT32 numlenbits; 85 OPJ_UINT32 data_size; /* Size of allocated data buffer */ 86 OPJ_UINT32 87 numpasses; /* number of pass already done for the code-blocks */ 88 OPJ_UINT32 numpassesinlayers; /* number of passes in the layer */ 89 OPJ_UINT32 totalpasses; /* total number of passes */ 90 } opj_tcd_cblk_enc_t; 91 92 93 /** Chunk of codestream data that is part of a code block */ 94 typedef struct opj_tcd_seg_data_chunk { 95 /* Point to tilepart buffer. We don't make a copy ! 96 So the tilepart buffer must be kept alive 97 as long as we need to decode the codeblocks */ 98 OPJ_BYTE * data; 99 OPJ_UINT32 len; /* Usable length of data */ 100 } opj_tcd_seg_data_chunk_t; 101 102 /** Segment of a code-block. 103 * A segment represent a number of consecutive coding passes, without termination 104 * of MQC or RAW between them. */ 105 typedef struct opj_tcd_seg { 106 OPJ_UINT32 len; /* Size of data related to this segment */ 107 /* Number of passes decoded. Including those that we skip */ 108 OPJ_UINT32 numpasses; 109 /* Number of passes actually to be decoded. To be used for code-block decoding */ 110 OPJ_UINT32 real_num_passes; 111 /* Maximum number of passes for this segment */ 112 OPJ_UINT32 maxpasses; 113 /* Number of new passes for current packed. Transitory value */ 114 OPJ_UINT32 numnewpasses; 115 /* Codestream length for this segment for current packed. Transitory value */ 116 OPJ_UINT32 newlen; 117 } opj_tcd_seg_t; 118 119 /** Code-block for decoding */ 120 typedef struct opj_tcd_cblk_dec { 121 opj_tcd_seg_t* segs; /* segments information */ 122 opj_tcd_seg_data_chunk_t* chunks; /* Array of chunks */ 123 /* position of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */ 124 OPJ_INT32 x0, y0, x1, y1; 125 /* Mb is The maximum number of bit-planes available for the representation of 126 coefficients in any sub-band, b, as defined in Equation (E-2). See 127 Section B.10.5 of the standard */ 128 OPJ_UINT32 Mb; /* currently used only to check if HT decoding is correct */ 129 /* numbps is Mb - P as defined in Section B.10.5 of the standard */ 130 OPJ_UINT32 numbps; 131 /* number of bits for len, for the current packet. Transitory value */ 132 OPJ_UINT32 numlenbits; 133 /* number of pass added to the code-blocks, for the current packet. Transitory value */ 134 OPJ_UINT32 numnewpasses; 135 /* number of segments, including those of packet we skip */ 136 OPJ_UINT32 numsegs; 137 /* number of segments, to be used for code block decoding */ 138 OPJ_UINT32 real_num_segs; 139 OPJ_UINT32 m_current_max_segs; /* allocated number of segs[] items */ 140 OPJ_UINT32 numchunks; /* Number of valid chunks items */ 141 OPJ_UINT32 numchunksalloc; /* Number of chunks item allocated */ 142 /* Decoded code-block. Only used for subtile decoding. Otherwise tilec->data is directly updated */ 143 OPJ_INT32* decoded_data; 144 } opj_tcd_cblk_dec_t; 145 146 /** Precinct structure */ 147 typedef struct opj_tcd_precinct { 148 /* dimension of the precinct : left upper corner (x0, y0) right low corner (x1,y1) */ 149 OPJ_INT32 x0, y0, x1, y1; 150 OPJ_UINT32 cw, ch; /* number of code-blocks, in width and height */ 151 union { /* code-blocks information */ 152 opj_tcd_cblk_enc_t* enc; 153 opj_tcd_cblk_dec_t* dec; 154 void* blocks; 155 } cblks; 156 OPJ_UINT32 block_size; /* size taken by cblks (in bytes) */ 157 opj_tgt_tree_t *incltree; /* inclusion tree */ 158 opj_tgt_tree_t *imsbtree; /* IMSB tree */ 159 } opj_tcd_precinct_t; 160 161 /** Sub-band structure */ 162 typedef struct opj_tcd_band { 163 /* dimension of the subband : left upper corner (x0, y0) right low corner (x1,y1) */ 164 OPJ_INT32 x0, y0, x1, y1; 165 /* band number: for lowest resolution level (0=LL), otherwise (1=HL, 2=LH, 3=HH) */ 166 OPJ_UINT32 bandno; 167 /* precinct information */ 168 opj_tcd_precinct_t *precincts; 169 /* size of data taken by precincts */ 170 OPJ_UINT32 precincts_data_size; 171 OPJ_INT32 numbps; 172 OPJ_FLOAT32 stepsize; 173 } opj_tcd_band_t; 174 175 /** Tile-component resolution structure */ 176 typedef struct opj_tcd_resolution { 177 /* dimension of the resolution level : left upper corner (x0, y0) right low corner (x1,y1) */ 178 OPJ_INT32 x0, y0, x1, y1; 179 /* number of precincts, in width and height, for this resolution level */ 180 OPJ_UINT32 pw, ph; 181 /* number of sub-bands for the resolution level (1 for lowest resolution level, 3 otherwise) */ 182 OPJ_UINT32 numbands; 183 /* subband information */ 184 opj_tcd_band_t bands[3]; 185 186 /* dimension of the resolution limited to window of interest. Only valid if tcd->whole_tile_decoding is set */ 187 OPJ_UINT32 win_x0; 188 OPJ_UINT32 win_y0; 189 OPJ_UINT32 win_x1; 190 OPJ_UINT32 win_y1; 191 } opj_tcd_resolution_t; 192 193 /** Tile-component structure */ 194 typedef struct opj_tcd_tilecomp { 195 /* dimension of component : left upper corner (x0, y0) right low corner (x1,y1) */ 196 OPJ_INT32 x0, y0, x1, y1; 197 /* component number */ 198 OPJ_UINT32 compno; 199 /* number of resolutions level */ 200 OPJ_UINT32 numresolutions; 201 /* number of resolutions level to decode (at max)*/ 202 OPJ_UINT32 minimum_num_resolutions; 203 /* resolutions information */ 204 opj_tcd_resolution_t *resolutions; 205 /* size of data for resolutions (in bytes) */ 206 OPJ_UINT32 resolutions_size; 207 208 /* data of the component. For decoding, only valid if tcd->whole_tile_decoding is set (so exclusive of data_win member) */ 209 OPJ_INT32 *data; 210 /* if true, then need to free after usage, otherwise do not free */ 211 OPJ_BOOL ownsData; 212 /* we may either need to allocate this amount of data, or re-use image data and ignore this value */ 213 size_t data_size_needed; 214 /* size of the data of the component */ 215 size_t data_size; 216 217 /** data of the component limited to window of interest. Only valid for decoding and if tcd->whole_tile_decoding is NOT set (so exclusive of data member) */ 218 OPJ_INT32 *data_win; 219 /* dimension of the component limited to window of interest. Only valid for decoding and if tcd->whole_tile_decoding is NOT set */ 220 OPJ_UINT32 win_x0; 221 OPJ_UINT32 win_y0; 222 OPJ_UINT32 win_x1; 223 OPJ_UINT32 win_y1; 224 225 /* add fixed_quality */ 226 OPJ_INT32 numpix; 227 } opj_tcd_tilecomp_t; 228 229 230 /** 231 FIXME DOC 232 */ 233 typedef struct opj_tcd_tile { 234 /* dimension of the tile : left upper corner (x0, y0) right low corner (x1,y1) */ 235 OPJ_INT32 x0, y0, x1, y1; 236 OPJ_UINT32 numcomps; /* number of components in tile */ 237 opj_tcd_tilecomp_t *comps; /* Components information */ 238 OPJ_INT32 numpix; /* add fixed_quality */ 239 OPJ_FLOAT64 distotile; /* add fixed_quality */ 240 OPJ_FLOAT64 distolayer[100]; /* add fixed_quality */ 241 OPJ_UINT32 packno; /* packet number */ 242 } opj_tcd_tile_t; 243 244 /** 245 FIXME DOC 246 */ 247 typedef struct opj_tcd_image { 248 opj_tcd_tile_t *tiles; /* Tiles information */ 249 } 250 opj_tcd_image_t; 251 252 253 /** 254 Tile coder/decoder 255 */ 256 typedef struct opj_tcd { 257 /** Position of the tilepart flag in Progression order*/ 258 OPJ_INT32 tp_pos; 259 /** Tile part number*/ 260 OPJ_UINT32 tp_num; 261 /** Current tile part number*/ 262 OPJ_UINT32 cur_tp_num; 263 /** Total number of tileparts of the current tile*/ 264 OPJ_UINT32 cur_totnum_tp; 265 /** Current Packet iterator number */ 266 OPJ_UINT32 cur_pino; 267 /** info on each image tile */ 268 opj_tcd_image_t *tcd_image; 269 /** image header */ 270 opj_image_t *image; 271 /** coding parameters */ 272 opj_cp_t *cp; 273 /** coding/decoding parameters common to all tiles */ 274 opj_tcp_t *tcp; 275 /** current encoded/decoded tile */ 276 OPJ_UINT32 tcd_tileno; 277 /** tell if the tcd is a decoder. */ 278 OPJ_BITFIELD m_is_decoder : 1; 279 /** Thread pool */ 280 opj_thread_pool_t* thread_pool; 281 /** Coordinates of the window of interest, in grid reference space */ 282 OPJ_UINT32 win_x0; 283 OPJ_UINT32 win_y0; 284 OPJ_UINT32 win_x1; 285 OPJ_UINT32 win_y1; 286 /** Only valid for decoding. Whether the whole tile is decoded, or just the region in win_x0/win_y0/win_x1/win_y1 */ 287 OPJ_BOOL whole_tile_decoding; 288 /* Array of size image->numcomps indicating if a component must be decoded. NULL if all components must be decoded */ 289 OPJ_BOOL* used_component; 290 } opj_tcd_t; 291 292 /** 293 * Structure to hold information needed to generate some markers. 294 * Used by encoder. 295 */ 296 typedef struct opj_tcd_marker_info { 297 /** In: Whether information to generate PLT markers in needed */ 298 OPJ_BOOL need_PLT; 299 300 /** OUT: Number of elements in p_packet_size[] array */ 301 OPJ_UINT32 packet_count; 302 303 /** OUT: Array of size packet_count, such that p_packet_size[i] is 304 * the size in bytes of the ith packet */ 305 OPJ_UINT32* p_packet_size; 306 } opj_tcd_marker_info_t; 307 308 /** @name Exported functions */ 309 /*@{*/ 310 /* ----------------------------------------------------------------------- */ 311 312 /** 313 Dump the content of a tcd structure 314 */ 315 /*void tcd_dump(FILE *fd, opj_tcd_t *tcd, opj_tcd_image_t *img);*/ /* TODO MSD shoul use the new v2 structures */ 316 317 /** 318 Create a new TCD handle 319 @param p_is_decoder FIXME DOC 320 @return Returns a new TCD handle if successful returns NULL otherwise 321 */ 322 opj_tcd_t* opj_tcd_create(OPJ_BOOL p_is_decoder); 323 324 /** 325 Destroy a previously created TCD handle 326 @param tcd TCD handle to destroy 327 */ 328 void opj_tcd_destroy(opj_tcd_t *tcd); 329 330 331 /** 332 * Create a new opj_tcd_marker_info_t* structure 333 * @param need_PLT Whether information is needed to generate PLT markers. 334 */ 335 opj_tcd_marker_info_t* opj_tcd_marker_info_create(OPJ_BOOL need_PLT); 336 337 338 /** 339 Destroy a previously created opj_tcd_marker_info_t* structure 340 @param p_tcd_marker_info Structure to destroy 341 */ 342 void opj_tcd_marker_info_destroy(opj_tcd_marker_info_t *p_tcd_marker_info); 343 344 345 /** 346 * Initialize the tile coder and may reuse some memory. 347 * @param p_tcd TCD handle. 348 * @param p_image raw image. 349 * @param p_cp coding parameters. 350 * @param p_tp thread pool 351 * 352 * @return true if the encoding values could be set (false otherwise). 353 */ 354 OPJ_BOOL opj_tcd_init(opj_tcd_t *p_tcd, 355 opj_image_t * p_image, 356 opj_cp_t * p_cp, 357 opj_thread_pool_t* p_tp); 358 359 /** 360 * Allocates memory for decoding a specific tile. 361 * 362 * @param p_tcd the tile decoder. 363 * @param p_tile_no the index of the tile received in sequence. This not necessarily lead to the 364 * tile at index p_tile_no. 365 * @param p_manager the event manager. 366 * 367 * @return true if the remaining data is sufficient. 368 */ 369 OPJ_BOOL opj_tcd_init_decode_tile(opj_tcd_t *p_tcd, OPJ_UINT32 p_tile_no, 370 opj_event_mgr_t* p_manager); 371 372 void opj_tcd_makelayer_fixed(opj_tcd_t *tcd, OPJ_UINT32 layno, 373 OPJ_UINT32 final); 374 375 void opj_tcd_rateallocate_fixed(opj_tcd_t *tcd); 376 377 void opj_tcd_makelayer(opj_tcd_t *tcd, 378 OPJ_UINT32 layno, 379 OPJ_FLOAT64 thresh, 380 OPJ_UINT32 final); 381 382 OPJ_BOOL opj_tcd_rateallocate(opj_tcd_t *tcd, 383 OPJ_BYTE *dest, 384 OPJ_UINT32 * p_data_written, 385 OPJ_UINT32 len, 386 opj_codestream_info_t *cstr_info, 387 opj_event_mgr_t *p_manager); 388 389 /** 390 * Gets the maximum tile size that will be taken by the tile once decoded. 391 */ 392 OPJ_UINT32 opj_tcd_get_decoded_tile_size(opj_tcd_t *p_tcd, 393 OPJ_BOOL take_into_account_partial_decoding); 394 395 /** 396 * Encodes a tile from the raw image into the given buffer. 397 * @param p_tcd Tile Coder handle 398 * @param p_tile_no Index of the tile to encode. 399 * @param p_dest Destination buffer 400 * @param p_data_written pointer to an int that is incremented by the number of bytes really written on p_dest 401 * @param p_len Maximum length of the destination buffer 402 * @param p_cstr_info Codestream information structure 403 * @param p_marker_info Marker information structure 404 * @param p_manager the user event manager 405 * @return true if the coding is successful. 406 */ 407 OPJ_BOOL opj_tcd_encode_tile(opj_tcd_t *p_tcd, 408 OPJ_UINT32 p_tile_no, 409 OPJ_BYTE *p_dest, 410 OPJ_UINT32 * p_data_written, 411 OPJ_UINT32 p_len, 412 struct opj_codestream_info *p_cstr_info, 413 opj_tcd_marker_info_t* p_marker_info, 414 opj_event_mgr_t *p_manager); 415 416 417 /** 418 Decode a tile from a buffer into a raw image 419 @param tcd TCD handle 420 @param win_x0 Upper left x of region to decode (in grid coordinates) 421 @param win_y0 Upper left y of region to decode (in grid coordinates) 422 @param win_x1 Lower right x of region to decode (in grid coordinates) 423 @param win_y1 Lower right y of region to decode (in grid coordinates) 424 @param numcomps_to_decode Size of the comps_indices array, or 0 if decoding all components. 425 @param comps_indices Array of numcomps values representing the indices 426 of the components to decode (relative to the 427 codestream, starting at 0). Or NULL if decoding all components. 428 @param src Source buffer 429 @param len Length of source buffer 430 @param tileno Number that identifies one of the tiles to be decoded 431 @param cstr_info FIXME DOC 432 @param manager the event manager. 433 */ 434 OPJ_BOOL opj_tcd_decode_tile(opj_tcd_t *tcd, 435 OPJ_UINT32 win_x0, 436 OPJ_UINT32 win_y0, 437 OPJ_UINT32 win_x1, 438 OPJ_UINT32 win_y1, 439 OPJ_UINT32 numcomps_to_decode, 440 const OPJ_UINT32 *comps_indices, 441 OPJ_BYTE *src, 442 OPJ_UINT32 len, 443 OPJ_UINT32 tileno, 444 opj_codestream_index_t *cstr_info, 445 opj_event_mgr_t *manager); 446 447 448 /** 449 * Copies tile data from the system onto the given memory block. 450 */ 451 OPJ_BOOL opj_tcd_update_tile_data(opj_tcd_t *p_tcd, 452 OPJ_BYTE * p_dest, 453 OPJ_UINT32 p_dest_length); 454 455 /** 456 * Get the size in bytes of the input buffer provided before encoded. 457 * This must be the size provided to the p_src_length argument of 458 * opj_tcd_copy_tile_data() 459 */ 460 OPJ_SIZE_T opj_tcd_get_encoder_input_buffer_size(opj_tcd_t *p_tcd); 461 462 /** 463 * Initialize the tile coder and may reuse some meory. 464 * 465 * @param p_tcd TCD handle. 466 * @param p_tile_no current tile index to encode. 467 * @param p_manager the event manager. 468 * 469 * @return true if the encoding values could be set (false otherwise). 470 */ 471 OPJ_BOOL opj_tcd_init_encode_tile(opj_tcd_t *p_tcd, 472 OPJ_UINT32 p_tile_no, opj_event_mgr_t* p_manager); 473 474 /** 475 * Copies tile data from the given memory block onto the system. 476 * 477 * p_src_length must be equal to opj_tcd_get_encoder_input_buffer_size() 478 */ 479 OPJ_BOOL opj_tcd_copy_tile_data(opj_tcd_t *p_tcd, 480 OPJ_BYTE * p_src, 481 OPJ_SIZE_T p_src_length); 482 483 /** 484 * Allocates tile component data 485 * 486 * 487 */ 488 OPJ_BOOL opj_alloc_tile_component_data(opj_tcd_tilecomp_t *l_tilec); 489 490 /** Returns whether a sub-band is empty (i.e. whether it has a null area) 491 * @param band Sub-band handle. 492 * @return OPJ_TRUE whether the sub-band is empty. 493 */ 494 OPJ_BOOL opj_tcd_is_band_empty(opj_tcd_band_t* band); 495 496 /** Reinitialize a segment */ 497 void opj_tcd_reinit_segment(opj_tcd_seg_t* seg); 498 499 500 /** Returns whether a sub-band region contributes to the area of interest 501 * tcd->win_x0,tcd->win_y0,tcd->win_x1,tcd->win_y1. 502 * 503 * @param tcd TCD handle. 504 * @param compno Component number 505 * @param resno Resolution number 506 * @param bandno Band number (*not* band index, ie 0, 1, 2 or 3) 507 * @param x0 Upper left x in subband coordinates 508 * @param y0 Upper left y in subband coordinates 509 * @param x1 Lower right x in subband coordinates 510 * @param y1 Lower right y in subband coordinates 511 * @return OPJ_TRUE whether the sub-band region contributs to the area of 512 * interest. 513 */ 514 OPJ_BOOL opj_tcd_is_subband_area_of_interest(opj_tcd_t *tcd, 515 OPJ_UINT32 compno, 516 OPJ_UINT32 resno, 517 OPJ_UINT32 bandno, 518 OPJ_UINT32 x0, 519 OPJ_UINT32 y0, 520 OPJ_UINT32 x1, 521 OPJ_UINT32 y1); 522 523 /* ----------------------------------------------------------------------- */ 524 /*@}*/ 525 526 /*@}*/ 527 528 #endif /* OPJ_TCD_H */ 529