libopenjpeg/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 struct opj_image;
 314 struct opj_cp_v2;
 315 struct opj_tcp_v2;
 316 /**
 317 Tile coder/decoder
 318 */
 319 typedef struct opj_tcd_v2
 320 {
 321         /** Position of the tilepart flag in Progression order*/
 322         OPJ_INT32 tp_pos;
 323         /** Tile part number*/
 324         OPJ_UINT32 tp_num;
 325         /** Current tile part number*/
 326         OPJ_UINT32 cur_tp_num;
 327         /** Total number of tileparts of the current tile*/
 328         OPJ_UINT32 cur_totnum_tp;
 329         /** Current Packet iterator number */
 330         OPJ_UINT32 cur_pino;
 331         /** info on each image tile */
 332         opj_tcd_image_v2_t *tcd_image;
 333         /** image header */
 334         opj_image_t *image;
 335         /** coding parameters */
 336         struct opj_cp_v2 *cp;
 337         /** coding/decoding parameters common to all tiles */
 338         struct opj_tcp_v2 *tcp;
 339         /** current encoded/decoded tile */
 340         OPJ_UINT32 tcd_tileno;
 341         /** tell if the tcd is a decoder. */
 342         OPJ_UINT32 m_is_decoder : 1;
 343 } opj_tcd_v2_t;
 344
 345 /** @name Exported functions */
 346 /*@{*/
 347 /* ----------------------------------------------------------------------- */
 348
 349 /**
 350 Dump the content of a tcd structure
 351 */
 352 void tcd_dump(FILE *fd, opj_tcd_t *tcd, opj_tcd_image_t *img);
 353 /**
 354 Create a new TCD handle
 355 @param cinfo Codec context info
 356 @return Returns a new TCD handle if successful returns NULL otherwise
 357 */
 358 opj_tcd_t* tcd_create(opj_common_ptr cinfo);
 359
 360 /**
 361 Create a new TCD handle
 362 @param FIXME
 363 @return Returns a new TCD handle if successful returns NULL otherwise
 364 */
 365 opj_tcd_v2_t* tcd_create_v2(opj_bool p_is_decoder);
 366
 367 /**
 368 Destroy a previously created TCD handle
 369 @param tcd TCD handle to destroy
 370 */
 371 void tcd_destroy_v2(opj_tcd_v2_t *tcd);
 372
 373 /**
 374  * Initialize the tile coder and may reuse some memory.
 375  * @param       p_tcd           TCD handle.
 376  * @param       p_image         raw image.
 377  * @param       p_cp            coding parameters.
 378  *
 379  * @return true if the encoding values could be set (false otherwise).
 380 */
 381 opj_bool tcd_init_v2(   opj_tcd_v2_t *p_tcd,
 382                                                 opj_image_t * p_image,
 383                                                 opj_cp_v2_t * p_cp
 384                                         );
 385
 386 /**
 387  * Allocates memory for decoding a specific tile.
 388  *
 389  * @param       p_tcd           the tile decoder.
 390  * @param       p_tile_no       the index of the tile received in sequence. This not necessarily lead to the
 391  * tile at index p_tile_no.
 392  *
 393  * @return      true if the remaining data is sufficient.
 394  */
 395 opj_bool tcd_init_decode_tile(
 396                                                         opj_tcd_v2_t *p_tcd,
 397                                                         OPJ_UINT32 p_tile_no
 398                                                         );
 399
 400 /**
 401 Destroy a previously created TCD handle
 402 @param tcd TCD handle to destroy
 403 */
 404 void tcd_destroy(opj_tcd_t *tcd);
 405 /**
 406 Initialize the tile coder (allocate the memory)
 407 @param tcd TCD handle
 408 @param image Raw image
 409 @param cp Coding parameters
 410 @param curtileno Number that identifies the tile that will be encoded
 411 */
 412 void tcd_malloc_encode(opj_tcd_t *tcd, opj_image_t * image, opj_cp_t * cp, int curtileno);
 413 /**
 414 Free the memory allocated for encoding
 415 @param tcd TCD handle
 416 */
 417 void tcd_free_encode(opj_tcd_t *tcd);
 418 /**
 419 Initialize the tile coder (reuses the memory allocated by tcd_malloc_encode)
 420 @param tcd TCD handle
 421 @param image Raw image
 422 @param cp Coding parameters
 423 @param curtileno Number that identifies the tile that will be encoded
 424 */
 425 void tcd_init_encode(opj_tcd_t *tcd, opj_image_t * image, opj_cp_t * cp, int curtileno);
 426 /**
 427 Initialize the tile decoder
 428 @param tcd TCD handle
 429 @param image Raw image
 430 @param cp Coding parameters
 431 */
 432 void tcd_malloc_decode(opj_tcd_t *tcd, opj_image_t * image, opj_cp_t * cp);
 433 void tcd_malloc_decode_tile(opj_tcd_t *tcd, opj_image_t * image, opj_cp_t * cp, int tileno, opj_codestream_info_t *cstr_info);
 434 void tcd_makelayer_fixed(opj_tcd_t *tcd, int layno, int final);
 435 void tcd_rateallocate_fixed(opj_tcd_t *tcd);
 436 void tcd_makelayer(opj_tcd_t *tcd, int layno, double thresh, int final);
 437 opj_bool tcd_rateallocate(opj_tcd_t *tcd, unsigned char *dest, int len, opj_codestream_info_t *cstr_info);
 438 /**
 439 Encode a tile from the raw image into a buffer
 440 @param tcd TCD handle
 441 @param tileno Number that identifies one of the tiles to be encoded
 442 @param dest Destination buffer
 443 @param len Length of destination buffer
 444 @param cstr_info Codestream information structure
 445 @return
 446 */
 447 int tcd_encode_tile(opj_tcd_t *tcd, int tileno, unsigned char *dest, int len, opj_codestream_info_t *cstr_info);
 448 /**
 449 Decode a tile from a buffer into a raw image
 450 @param tcd TCD handle
 451 @param src Source buffer
 452 @param len Length of source buffer
 453 @param tileno Number that identifies one of the tiles to be decoded
 454 @param cstr_info Codestream information structure
 455 */
 456 opj_bool tcd_decode_tile(opj_tcd_t *tcd, unsigned char *src, int len, int tileno, opj_codestream_info_t *cstr_info);
 457 /**
 458 Free the memory allocated for decoding
 459 @param tcd TCD handle
 460 */
 461 void tcd_free_decode(opj_tcd_t *tcd);
 462 void tcd_free_decode_tile(opj_tcd_t *tcd, int tileno);
 463
 464
 465 /**
 466  * Gets the maximum tile size that will be taken by the tile once decoded.
 467  */
 468 OPJ_UINT32 tcd_get_decoded_tile_size (
 469                                                  opj_tcd_v2_t *p_tcd
 470                                                  );
 471
 472 /**
 473 Decode a tile from a buffer into a raw image
 474 @param tcd TCD handle
 475 @param src Source buffer
 476 @param len Length of source buffer
 477 @param tileno Number that identifies one of the tiles to be decoded
 478 */
 479 opj_bool tcd_decode_tile_v2(opj_tcd_v2_t *tcd,
 480                                                         OPJ_BYTE *src,
 481                                                         OPJ_UINT32 len,
 482                                                         OPJ_UINT32 tileno,
 483                                                         opj_codestream_index_t *cstr_info);
 484
 485
 486 /**
 487  * Copies tile data from the system onto the given memory block.
 488  */
 489 opj_bool tcd_update_tile_data (
 490                                                  opj_tcd_v2_t *p_tcd,
 491                                                  OPJ_BYTE * p_dest,
 492                                                  OPJ_UINT32 p_dest_length
 493                                                  );
 494
 495 /* ----------------------------------------------------------------------- */
 496 /*@}*/
 497
 498 /*@}*/
 499
 500 #endif /* __TCD_H */