src/lib/openjp2/tcd.h

   1 /*
   2  * Copyright (c) 2002-2007, Communications and Remote Sensing Laboratory, Universite catholique de Louvain (UCL), Belgium
   3  * Copyright (c) 2002-2007, Professor Benoit Macq
   4  * Copyright (c) 2001-2003, David Janssens
   5  * Copyright (c) 2002-2003, Yannick Verschueren
   6  * Copyright (c) 2003-2007, Francois-Olivier Devaux and Antonin Descampe
   7  * Copyright (c) 2005, Herve Drolon, FreeImage Team
   8  * All rights reserved.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  23  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29  * POSSIBILITY OF SUCH DAMAGE.
  30  */
  31 #ifndef __TCD_H
  32 #define __TCD_H
  33 /**
  34 @file tcd.h
  35 @brief Implementation of a tile coder/decoder (TCD)
  36
  37 The functions in TCD.C encode or decode each tile independently from
  38 each other. The functions in TCD.C are used by other functions in J2K.C.
  39 */
  40
  41 /** @defgroup TCD TCD - Implementation of a tile coder/decoder */
  42 /*@{*/
  43
  44 /**
  45 FIXME: documentation
  46 */
  47 /*typedef struct opj_tcd_seg { */
  48 /*  unsigned char** data; */
  49 /*  int dataindex; */
  50 /*  int numpasses; */
  51 /*  int len; */
  52 /*  int maxpasses; */
  53 /*  int numnewpasses; */
  54 /*  int newlen; */
  55 /*} opj_tcd_seg_t; */
  56
  57 /**
  58 FIXME: documentation
  59 */
  60 typedef struct opj_tcd_seg {
  61         OPJ_BYTE ** data;
  62         OPJ_UINT32 dataindex;
  63         OPJ_UINT32 numpasses;
  64         OPJ_UINT32 real_num_passes;
  65         OPJ_UINT32 len;
  66         OPJ_UINT32 maxpasses;
  67         OPJ_UINT32 numnewpasses;
  68         OPJ_UINT32 newlen;
  69 } opj_tcd_seg_t;
  70
  71 /**
  72 FIXME: documentation
  73 */
  74 typedef struct opj_tcd_pass {
  75   int rate;
  76   double distortiondec;
  77   int term, len;
  78 } opj_tcd_pass_t;
  79
  80 typedef struct opj_tcd_pass_v2 {
  81         OPJ_UINT32 rate;
  82         OPJ_FLOAT64 distortiondec;
  83         OPJ_UINT32 len;
  84         OPJ_UINT32 term : 1;
  85 } opj_tcd_pass_v2_t;
  86
  87 /**
  88 FIXME: documentation
  89 */
  90 typedef struct opj_tcd_layer {
  91         OPJ_UINT32 numpasses;           /* Number of passes in the layer */
  92         OPJ_UINT32 len;                         /* len of information */
  93         OPJ_FLOAT64 disto;                      /* add for index (Cfr. Marcela) */
  94         OPJ_BYTE *data;                         /* data */
  95 } opj_tcd_layer_t;
  96
  97 /**
  98 FIXME: documentation
  99 */
 100 typedef struct opj_tcd_cblk_enc {
 101   unsigned char* data;  /* Data */
 102   opj_tcd_layer_t* layers;      /* layer information */
 103   opj_tcd_pass_t* passes;       /* information about the passes */
 104   int x0, y0, x1, y1;           /* dimension of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */
 105   int numbps;
 106   int numlenbits;
 107   int numpasses;                /* number of pass already done for the code-blocks */
 108   int numpassesinlayers;        /* number of passes in the layer */
 109   int totalpasses;              /* total number of passes */
 110 } opj_tcd_cblk_enc_t;
 111
 112 /**
 113 FIXME: documentation
 114 */
 115 typedef struct opj_tcd_cblk_enc_v2 {
 116         OPJ_BYTE* data;                                 /* Data */
 117         opj_tcd_layer_t* layers;                /* layer information */
 118         opj_tcd_pass_v2_t* passes;              /* information about the passes */
 119         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */
 120         OPJ_UINT32 numbps;
 121         OPJ_UINT32 numlenbits;
 122         OPJ_UINT32 numpasses;                   /* number of pass already done for the code-blocks */
 123         OPJ_UINT32 numpassesinlayers;   /* number of passes in the layer */
 124         OPJ_UINT32 totalpasses;                 /* total number of passes */
 125 } opj_tcd_cblk_enc_v2_t;
 126
 127 typedef struct opj_tcd_cblk_dec {
 128   unsigned char* data;  /* Data */
 129   opj_tcd_seg_t* segs;          /* segments information */
 130         int x0, y0, x1, y1;             /* dimension of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */
 131   int numbps;
 132   int numlenbits;
 133   int len;                      /* length */
 134   int numnewpasses;             /* number of pass added to the code-blocks */
 135   int numsegs;                  /* number of segments */
 136 } opj_tcd_cblk_dec_t;
 137
 138
 139 typedef struct opj_tcd_cblk_dec_v2 {
 140         OPJ_BYTE * data;                                /* Data */
 141         opj_tcd_seg_t* segs;                    /* segments information */
 142         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the code-blocks : left upper corner (x0, y0) right low corner (x1,y1) */
 143         OPJ_UINT32 numbps;
 144         OPJ_UINT32 numlenbits;
 145         OPJ_UINT32 len;                                 /* length */
 146         OPJ_UINT32 numnewpasses;                /* number of pass added to the code-blocks */
 147         OPJ_UINT32 numsegs;                             /* number of segments */
 148         OPJ_UINT32 real_num_segs;
 149         OPJ_UINT32 m_current_max_segs;
 150 } opj_tcd_cblk_dec_v2_t;
 151
 152 /**
 153 FIXME: documentation
 154 */
 155 typedef struct opj_tcd_precinct {
 156   int x0, y0, x1, y1;           /* dimension of the precinct : left upper corner (x0, y0) right low corner (x1,y1) */
 157   int cw, ch;                   /* number of precinct in width and height */
 158   union{                /* code-blocks information */
 159           opj_tcd_cblk_enc_t* enc;
 160           opj_tcd_cblk_dec_t* dec;
 161   } cblks;
 162   opj_tgt_tree_t *incltree;             /* inclusion tree */
 163   opj_tgt_tree_t *imsbtree;             /* IMSB tree */
 164 } opj_tcd_precinct_t;
 165
 166
 167 typedef struct opj_tcd_precinct_v2 {
 168         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the precinct : left upper corner (x0, y0) right low corner (x1,y1) */
 169         OPJ_UINT32 cw, ch;                              /* number of precinct in width and height */
 170         union{                                                  /* code-blocks information */
 171                 opj_tcd_cblk_enc_v2_t* enc;
 172                 opj_tcd_cblk_dec_v2_t* dec;
 173         } cblks;
 174         OPJ_UINT32 block_size;                  /* size taken by cblks (in bytes) */
 175         opj_tgt_tree_t *incltree;       /* inclusion tree */
 176         opj_tgt_tree_t *imsbtree;       /* IMSB tree */
 177 } opj_tcd_precinct_v2_t;
 178
 179 /**
 180 FIXME: documentation
 181 */
 182 typedef struct opj_tcd_band {
 183   int x0, y0, x1, y1;           /* dimension of the subband : left upper corner (x0, y0) right low corner (x1,y1) */
 184   int bandno;
 185   opj_tcd_precinct_t *precincts;        /* precinct information */
 186   int numbps;
 187   float stepsize;
 188 } opj_tcd_band_t;
 189
 190 typedef struct opj_tcd_band_v2 {
 191         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the subband : left upper corner (x0, y0) right low corner (x1,y1) */
 192         OPJ_UINT32 bandno;
 193         opj_tcd_precinct_v2_t *precincts;       /* precinct information */
 194         OPJ_UINT32 precincts_data_size; /* size of data taken by precincts */
 195         OPJ_INT32 numbps;
 196         OPJ_FLOAT32 stepsize;
 197 } opj_tcd_band_v2_t;
 198
 199 /**
 200 FIXME: documentation
 201 */
 202 typedef struct opj_tcd_resolution {
 203   int x0, y0, x1, y1;           /* dimension of the resolution level : left upper corner (x0, y0) right low corner (x1,y1) */
 204   int pw, ph;
 205   int numbands;                 /* number sub-band for the resolution level */
 206   opj_tcd_band_t bands[3];              /* subband information */
 207 } opj_tcd_resolution_t;
 208
 209 typedef struct opj_tcd_resolution_v2 {
 210         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the resolution level : left upper corner (x0, y0) right low corner (x1,y1) */
 211         OPJ_UINT32 pw, ph;
 212         OPJ_UINT32 numbands;                    /* number sub-band for the resolution level */
 213         opj_tcd_band_v2_t bands[3];             /* subband information */
 214 } opj_tcd_resolution_v2_t;
 215
 216 /**
 217 FIXME: documentation
 218 */
 219 typedef struct opj_tcd_tilecomp {
 220   int x0, y0, x1, y1;           /* dimension of component : left upper corner (x0, y0) right low corner (x1,y1) */
 221   int numresolutions;           /* number of resolutions level */
 222   opj_tcd_resolution_t *resolutions;    /* resolutions information */
 223   int *data;                    /* data of the component */
 224   int numpix;                   /* add fixed_quality */
 225 } opj_tcd_tilecomp_t;
 226
 227 typedef struct opj_tcd_tilecomp_v2
 228 {
 229         OPJ_INT32 x0, y0, x1, y1;                               /* dimension of component : left upper corner (x0, y0) right low corner (x1,y1) */
 230         OPJ_UINT32 numresolutions;                              /* number of resolutions level */
 231         OPJ_UINT32 minimum_num_resolutions;             /* number of resolutions level to decode (at max)*/
 232         opj_tcd_resolution_v2_t *resolutions;   /* resolutions information */
 233         OPJ_UINT32 resolutions_size;                    /* size of data for resolutions (in bytes) */
 234         OPJ_INT32 *data;                                                /* data of the component */
 235         OPJ_UINT32 data_size;                                   /* size of the data of the component */
 236         OPJ_INT32 numpix;                                               /* add fixed_quality */
 237 } opj_tcd_tilecomp_v2_t;
 238
 239
 240 /**
 241 FIXME: documentation
 242 */
 243 typedef struct opj_tcd_tile {
 244   int x0, y0, x1, y1;           /* dimension of the tile : left upper corner (x0, y0) right low corner (x1,y1) */
 245   int numcomps;                 /* number of components in tile */
 246   opj_tcd_tilecomp_t *comps;    /* Components information */
 247   int numpix;                   /* add fixed_quality */
 248   double distotile;             /* add fixed_quality */
 249   double distolayer[100];       /* add fixed_quality */
 250   /** packet number */
 251   int packno;
 252 } opj_tcd_tile_t;
 253
 254 typedef struct opj_tcd_tile_v2 {
 255         OPJ_INT32 x0, y0, x1, y1;               /* dimension of the tile : left upper corner (x0, y0) right low corner (x1,y1) */
 256         OPJ_UINT32 numcomps;                    /* number of components in tile */
 257         opj_tcd_tilecomp_v2_t *comps;   /* Components information */
 258         OPJ_INT32 numpix;                               /* add fixed_quality */
 259         OPJ_FLOAT64 distotile;                  /* add fixed_quality */
 260         OPJ_FLOAT64 distolayer[100];    /* add fixed_quality */
 261         /** packet number */
 262         OPJ_UINT32 packno;
 263 } opj_tcd_tile_v2_t;
 264
 265 /**
 266 FIXME: documentation
 267 */
 268 typedef struct opj_tcd_image {
 269   int tw, th;                   /* number of tiles in width and height */
 270   opj_tcd_tile_t *tiles;                /* Tiles information */
 271 } opj_tcd_image_t;
 272
 273 typedef struct opj_tcd_image_v2
 274 {
 275         opj_tcd_tile_v2_t *tiles;               /* Tiles information */
 276 }
 277 opj_tcd_image_v2_t;
 278
 279 /**
 280 Tile coder/decoder
 281 */
 282 typedef struct opj_tcd {
 283         /** Position of the tilepart flag in Progression order*/
 284         int tp_pos;
 285         /** Tile part number*/
 286         int tp_num;
 287         /** Current tile part number*/
 288         int cur_tp_num;
 289         /** Total number of tileparts of the current tile*/
 290         int cur_totnum_tp;
 291         /** Current Packet iterator number */
 292         int cur_pino;
 293         /** codec context */
 294         opj_common_ptr cinfo;
 295
 296         /** info on each image tile */
 297         opj_tcd_image_t *tcd_image;
 298         /** image */
 299         opj_image_t *image;
 300         /** coding parameters */
 301         opj_cp_t *cp;
 302         /** pointer to the current encoded/decoded tile */
 303         opj_tcd_tile_t *tcd_tile;
 304         /** coding/decoding parameters common to all tiles */
 305         opj_tcp_t *tcp;
 306         /** current encoded/decoded tile */
 307         int tcd_tileno;
 308         /** Time taken to encode a tile*/
 309         double encoding_time;
 310 } opj_tcd_t;
 311
 312
 313 /**
 314 Tile coder/decoder
 315 */
 316 typedef struct opj_tcd_v2
 317 {
 318         /** Position of the tilepart flag in Progression order*/
 319         OPJ_INT32 tp_pos;
 320         /** Tile part number*/
 321         OPJ_UINT32 tp_num;
 322         /** Current tile part number*/
 323         OPJ_UINT32 cur_tp_num;
 324         /** Total number of tileparts of the current tile*/
 325         OPJ_UINT32 cur_totnum_tp;
 326         /** Current Packet iterator number */
 327         OPJ_UINT32 cur_pino;
 328         /** info on each image tile */
 329         opj_tcd_image_v2_t *tcd_image;
 330         /** image header */
 331         opj_image_t *image;
 332         /** coding parameters */
 333         opj_cp_v2_t *cp;
 334         /** coding/decoding parameters common to all tiles */
 335         opj_tcp_v2_t *tcp;
 336         /** current encoded/decoded tile */
 337         OPJ_UINT32 tcd_tileno;
 338         /** tell if the tcd is a decoder. */
 339         OPJ_UINT32 m_is_decoder : 1;
 340 } opj_tcd_v2_t;
 341
 342 /** @name Exported functions */
 343 /*@{*/
 344 /* ----------------------------------------------------------------------- */
 345
 346 /**
 347 Dump the content of a tcd structure
 348 */
 349 void tcd_dump(FILE *fd, opj_tcd_t *tcd, opj_tcd_image_t *img);
 350
 351 /**
 352 Create a new TCD handle
 353 @param p_is_decoder FIXME DOC
 354 @return Returns a new TCD handle if successful returns NULL otherwise
 355 */
 356 opj_tcd_v2_t* opj_tcd_create(opj_bool p_is_decoder);
 357
 358 /**
 359 Destroy a previously created TCD handle
 360 @param tcd TCD handle to destroy
 361 */
 362 void opj_tcd_destroy(opj_tcd_v2_t *tcd);
 363
 364 /**
 365  * Initialize the tile coder and may reuse some memory.
 366  * @param       p_tcd           TCD handle.
 367  * @param       p_image         raw image.
 368  * @param       p_cp            coding parameters.
 369  *
 370  * @return true if the encoding values could be set (false otherwise).
 371 */
 372 opj_bool opj_tcd_init(  opj_tcd_v2_t *p_tcd,
 373                                                 opj_image_t * p_image,
 374                                                 opj_cp_v2_t * p_cp );
 375
 376 /**
 377  * Allocates memory for decoding a specific tile.
 378  *
 379  * @param       p_tcd           the tile decoder.
 380  * @param       p_tile_no       the index of the tile received in sequence. This not necessarily lead to the
 381  * tile at index p_tile_no.
 382  *
 383  * @return      true if the remaining data is sufficient.
 384  */
 385 opj_bool opj_tcd_init_decode_tile(opj_tcd_v2_t *p_tcd, OPJ_UINT32 p_tile_no);
 386
 387 void opj_tcd_makelayer_fixed(opj_tcd_v2_t *tcd, OPJ_UINT32 layno, OPJ_UINT32 final);
 388
 389 void opj_tcd_rateallocate_fixed(opj_tcd_v2_t *tcd);
 390
 391 void opj_tcd_makelayer( opj_tcd_v2_t *tcd,
 392                                                 OPJ_UINT32 layno,
 393                                                 OPJ_FLOAT64 thresh,
 394                                                 OPJ_UINT32 final);
 395
 396 opj_bool opj_tcd_rateallocate(  opj_tcd_v2_t *tcd,
 397                                                                 OPJ_BYTE *dest,
 398                                                                 OPJ_UINT32 * p_data_written,
 399                                                                 OPJ_UINT32 len,
 400                                                                 opj_codestream_info_t *cstr_info);
 401
 402 /**
 403  * Gets the maximum tile size that will be taken by the tile once decoded.
 404  */
 405 OPJ_UINT32 opj_tcd_get_decoded_tile_size (opj_tcd_v2_t *p_tcd );
 406
 407 /**
 408  * Encodes a tile from the raw image into the given buffer.
 409  * @param       p_tcd                   Tile Coder handle
 410  * @param       p_tile_no               Index of the tile to encode.
 411  * @param       p_dest                  Destination buffer
 412  * @param       p_data_written  pointer to an int that is incremented by the number of bytes really written on p_dest
 413  * @param       p_len                   Maximum length of the destination buffer
 414  * @param       p_cstr_info             Codestream information structure
 415  * @return  true if the coding is successfull.
 416 */
 417 opj_bool opj_tcd_encode_tile(   opj_tcd_v2_t *p_tcd,
 418                                                             OPJ_UINT32 p_tile_no,
 419                                                             OPJ_BYTE *p_dest,
 420                                                             OPJ_UINT32 * p_data_written,
 421                                                             OPJ_UINT32 p_len,
 422                                                             struct opj_codestream_info *p_cstr_info);
 423
 424
 425 /**
 426 Decode a tile from a buffer into a raw image
 427 @param tcd TCD handle
 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 */
 433 opj_bool opj_tcd_decode_tile(   opj_tcd_v2_t *tcd,
 434                                                             OPJ_BYTE *src,
 435                                                             OPJ_UINT32 len,
 436                                                             OPJ_UINT32 tileno,
 437                                                             opj_codestream_index_t *cstr_info);
 438
 439
 440 /**
 441  * Copies tile data from the system onto the given memory block.
 442  */
 443 opj_bool opj_tcd_update_tile_data (     opj_tcd_v2_t *p_tcd,
 444                                                                     OPJ_BYTE * p_dest,
 445                                                                     OPJ_UINT32 p_dest_length );
 446
 447 /**
 448  *
 449  */
 450 OPJ_UINT32 opj_tcd_get_encoded_tile_size ( opj_tcd_v2_t *p_tcd );
 451
 452 /**
 453  * Initialize the tile coder and may reuse some meory.
 454  *
 455  * @param       p_tcd           TCD handle.
 456  * @param       p_tile_no       current tile index to encode.
 457  *
 458  * @return true if the encoding values could be set (false otherwise).
 459 */
 460 opj_bool opj_tcd_init_encode_tile (     opj_tcd_v2_t *p_tcd,
 461                                                                     OPJ_UINT32 p_tile_no );
 462
 463 /**
 464  * Copies tile data from the given memory block onto the system.
 465  */
 466 opj_bool opj_tcd_copy_tile_data (opj_tcd_v2_t *p_tcd,
 467                                  OPJ_BYTE * p_src,
 468                                  OPJ_UINT32 p_src_length );
 469
 470 /* ----------------------------------------------------------------------- */
 471 /*@}*/
 472
 473 /*@}*/
 474
 475 #endif /* __TCD_H */