libopenjpeg/openjpeg.h

   1 /*
   2  * Copyright (c) 2001-2003, David Janssens
   3  * Copyright (c) 2002-2003, Yannick Verschueren
   4  * Copyright (c) 2003-2005, Francois Devaux and Antonin Descampe
   5  * Copyright (c) 2005, Herv� Drolon, FreeImage Team
   6  * Copyright (c) 2002-2005, Communications and remote sensing Laboratory, Universite catholique de Louvain, Belgium
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in the
  16  *    documentation and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31
  32 #ifndef OPENJPEG_H
  33 #define OPENJPEG_H
  34
  35 /*
  36 ==========================================================
  37    Compiler directives
  38 ==========================================================
  39 */
  40 #ifndef __cplusplus
  41 #if defined(HAVE_STDBOOL_H)
  42 /*
  43 The C language implementation does correctly provide the standard header
  44 file "stdbool.h".
  45  */
  46 #include <stdbool.h>
  47 #else
  48 /*
  49 The C language implementation does not provide the standard header file
  50 "stdbool.h" as required by ISO/IEC 9899:1999.  Try to compensate for this
  51 braindamage below.
  52 */
  53 #if !defined(bool)
  54 #define bool  int
  55 #endif
  56 #if !defined(true)
  57 #define true  1
  58 #endif
  59 #if !defined(false)
  60 #define false 0
  61 #endif
  62 #endif
  63 #endif /* __cplusplus */
  64
  65 /*
  66 ==========================================================
  67    Useful constant definitions
  68 ==========================================================
  69 */
  70
  71 #ifndef MAX_PATH
  72 #define MAX_PATH 260  /**< Maximum allowed size for filenames */
  73 #endif /* MAX_PATH */
  74
  75 #define J2K_MAXRLVLS 33         /**< Number of maximum resolution level authorized */
  76 #define J2K_MAXBANDS (3*J2K_MAXRLVLS-2) /**< Number of maximum sub-band linked to number of resolution level */
  77
  78 /*
  79 ==========================================================
  80    enum definitions
  81 ==========================================================
  82 */
  83
  84 /** Progression order */
  85 typedef enum PROG_ORDER {
  86   PROG_UNKNOWN = -1,  /**< place-holder */
  87   LRCP = 0,   /**< layer-resolution-component-precinct order */
  88   RLCP = 1,   /**< resolution-layer-component-precinct order */
  89   RPCL = 2,   /**< resolution-precinct-component-layer order */
  90   PCRL = 3,   /**< precinct-component-resolution-layer order */
  91   CPRL = 4    /**< component-precinct-resolution-layer order */
  92 } OPJ_PROG_ORDER;
  93
  94 /**
  95 Supported image color spaces
  96 */
  97 typedef enum COLOR_SPACE {
  98   CLRSPC_UNKNOWN = -1,  /**< place-holder */
  99   CLRSPC_SRGB = 1,    /**< sRGB */
 100   CLRSPC_GRAY = 2,    /**< grayscale */
 101   CLRSPC_SYCC = 3     /**< YUV */
 102 } OPJ_COLOR_SPACE;
 103
 104 /**
 105 Supported codec
 106 */
 107 typedef enum CODEC_FORMAT {
 108   CODEC_UNKNOWN = -1, /**< place-holder */
 109   CODEC_J2K = 0,    /**< JPEG-2000 codestream : read/write */
 110   CODEC_JPT = 1,    /**< JPT-stream (JPEG 2000, JPIP) : read only */
 111   CODEC_JP2 = 2   /**< JPEG-2000 file format : read/write */
 112 } OPJ_CODEC_FORMAT;
 113
 114 /*
 115 ==========================================================
 116    event manager typedef definitions
 117 ==========================================================
 118 */
 119
 120 /**
 121 Callback function prototype for events
 122 @param msg Event message
 123 @param client_data
 124 */
 125 typedef void (*opj_msg_callback) (const char *msg, void *client_data);
 126
 127 /**
 128 Message handler object
 129 used for
 130 <ul>
 131 <li>Error messages
 132 <li>Warning messages
 133 <li>Debugging messages
 134 </ul>
 135 */
 136 typedef struct opj_event_mgr {
 137   /** Error message callback if available, NULL otherwise */
 138   opj_msg_callback error_handler;
 139   /** Warning message callback if available, NULL otherwise */
 140   opj_msg_callback warning_handler;
 141   /** Debug message callback if available, NULL otherwise */
 142   opj_msg_callback info_handler;
 143 } opj_event_mgr_t;
 144
 145
 146 /*
 147 ==========================================================
 148    codec typedef definitions
 149 ==========================================================
 150 */
 151
 152 /**
 153 Progression order changes
 154 */
 155 typedef struct opj_poc {
 156   int resno0, compno0;
 157   int layno1, resno1, compno1;
 158   OPJ_PROG_ORDER prg;
 159   int tile;
 160   char progorder[4];
 161 } opj_poc_t;
 162
 163 /**
 164 Compression parameters
 165 */
 166 typedef struct opj_cparameters {
 167   /** size of tile: tile_size_on = false (not in argument) or = true (in argument) */
 168   bool tile_size_on;
 169   /** XTOsiz */
 170   int cp_tx0;
 171   /** YTOsiz */
 172   int cp_ty0;
 173   /** XTsiz */
 174   int cp_tdx;
 175   /** YTsiz */
 176   int cp_tdy;
 177   /** allocation by rate/distortion */
 178   int cp_disto_alloc;
 179   /** allocation by fixed layer */
 180   int cp_fixed_alloc;
 181   /** add fixed_quality */
 182   int cp_fixed_quality;
 183   /** fixed layer */
 184   int *cp_matrice;
 185   /** comment for coding */
 186   char *cp_comment;
 187   /** csty : coding style */
 188   int csty;
 189   /** progression order (default LRCP) */
 190   OPJ_PROG_ORDER prog_order;
 191   /** progression order changes */
 192   opj_poc_t POC[32];
 193   /** number of progression order changes (POC), default to 0 */
 194   int numpocs;
 195   /** number of layers */
 196   int tcp_numlayers;
 197   /** rates of layers */
 198   int tcp_rates[100];
 199   /** different psnr for successive layers */
 200   float tcp_distoratio[100];
 201   /** number of resolutions */
 202   int numresolution;
 203   /** initial code block width, default to 64 */
 204   int cblockw_init;
 205   /** initial code block height, default to 64 */
 206   int cblockh_init;
 207   /** mode switch (cblk_style) */
 208   int mode;
 209   /** 1 : use the irreversible DWT 9-7, 0 : use lossless compression (default) */
 210   int irreversible;
 211   /** region of interest: affected component in [0..3], -1 means no ROI */
 212   int roi_compno;
 213   /** region of interest: upshift value */
 214   int roi_shift;
 215   /* number of precinct size specifications */
 216   int res_spec;
 217   /** initial precinct width */
 218   int prcw_init[J2K_MAXRLVLS];
 219   /** initial precinct height */
 220   int prch_init[J2K_MAXRLVLS];
 221
 222   /**@name command line encoder parameters (not used inside the library) */
 223   /*@{*/
 224   /** input file name */
 225   char infile[MAX_PATH];
 226   /** output file name */
 227   char outfile[MAX_PATH];
 228   /** creation of an index file, default to 0 (false) */
 229   int index_on;
 230   /** index file name */
 231   char index[MAX_PATH];
 232   /** subimage encoding: origin image offset in x direction */
 233   int image_offset_x0;
 234   /** subimage encoding: origin image offset in y direction */
 235   int image_offset_y0;
 236   /** subsampling value for dx */
 237   int subsampling_dx;
 238   /** subsampling value for dy */
 239   int subsampling_dy;
 240   /** input file format 0: PGX, 1: PxM, 2: BMP */
 241   int decod_format;
 242   /** output file format 0: J2K, 1: JP2, 2: JPT */
 243   int cod_format;
 244   /*@}*/
 245 } opj_cparameters_t;
 246
 247 /**
 248 Decompression parameters
 249 */
 250 typedef struct opj_dparameters {
 251   /**
 252   Set the number of highest resolution levels to be discarded.
 253   The image resolution is effectively divided by 2 to the power of the number of discarded levels.
 254   The reduce factor is limited by the smallest total number of decomposition levels among tiles.
 255   if != 0, then original dimension divided by 2^(reduce);
 256   if == 0 or not used, image is decoded to the full resolution
 257   */
 258   int cp_reduce;
 259   /**
 260   Set the maximum number of quality layers to decode.
 261   If there are less quality layers than the specified number, all the quality layers are decoded.
 262   if != 0, then only the first "layer" layers are decoded;
 263   if == 0 or not used, all the quality layers are decoded
 264   */
 265   int cp_layer;
 266
 267   /**@name command line encoder parameters (not used inside the library) */
 268   /*@{*/
 269   /** input file name */
 270   char infile[MAX_PATH];
 271   /** output file name */
 272   char outfile[MAX_PATH];
 273   /** input file format 0: J2K, 1: JP2, 2: JPT */
 274   int decod_format;
 275   /** output file format 0: PGX, 1: PxM, 2: BMP */
 276   int cod_format;
 277   /*@}*/
 278 } opj_dparameters_t;
 279
 280 /** Common fields between JPEG-2000 compression and decompression master structs. */
 281
 282 #define opj_common_fields \
 283   opj_event_mgr_t *event_mgr; /**< pointer to the event manager */\
 284   void * client_data;     /**< Available for use by application */\
 285   bool is_decompressor;   /**< So common code can tell which is which */\
 286   OPJ_CODEC_FORMAT codec_format;  /**< selected codec */\
 287   void *j2k_handle;     /**< pointer to the J2K codec */\
 288   void *jp2_handle      /**< pointer to the JP2 codec */
 289
 290 /* Routines that are to be used by both halves of the library are declared
 291  * to receive a pointer to this structure.  There are no actual instances of
 292  * opj_common_struct_t, only of opj_cinfo_t and opj_dinfo_t.
 293  */
 294 typedef struct opj_common_struct {
 295   opj_common_fields;    /* Fields common to both master struct types */
 296   /* Additional fields follow in an actual opj_cinfo_t or
 297    * opj_dinfo_t.  All three structs must agree on these
 298    * initial fields!  (This would be a lot cleaner in C++.)
 299    */
 300 } opj_common_struct_t;
 301
 302 typedef opj_common_struct_t * opj_common_ptr;
 303
 304 /**
 305 Compression context info
 306 */
 307 typedef struct opj_cinfo {
 308   /** Fields shared with opj_dinfo_t */
 309   opj_common_fields;
 310   /* other specific fields go here */
 311 } opj_cinfo_t;
 312
 313 /**
 314 Decompression context info
 315 */
 316 typedef struct opj_dinfo {
 317   /** Fields shared with opj_cinfo_t */
 318   opj_common_fields;
 319   /* other specific fields go here */
 320 } opj_dinfo_t;
 321
 322 /*
 323 ==========================================================
 324    I/O stream typedef definitions
 325 ==========================================================
 326 */
 327
 328 /*
 329  * Stream open flags.
 330  */
 331 /** The stream was opened for reading. */
 332 #define OPJ_STREAM_READ 0x0001
 333 /** The stream was opened for writing. */
 334 #define OPJ_STREAM_WRITE 0x0002
 335
 336 /**
 337 Byte input-output stream (CIO)
 338 */
 339 typedef struct opj_cio {
 340   /** codec context */
 341   opj_common_ptr cinfo;
 342
 343   /** open mode (read/write) either OPJ_STREAM_READ or OPJ_STREAM_WRITE */
 344   int openmode;
 345   /** pointer to the start of the buffer */
 346   unsigned char *buffer;
 347   /** buffer size in bytes */
 348   int length;
 349
 350   /** pointer to the start of the stream */
 351   unsigned char *start;
 352   /** pointer to the end of the stream */
 353   unsigned char *end;
 354   /** pointer to the current position */
 355   unsigned char *bp;
 356 } opj_cio_t;
 357
 358 /*
 359 ==========================================================
 360    image typedef definitions
 361 ==========================================================
 362 */
 363
 364 /**
 365 Defines a single image component
 366 */
 367 typedef struct opj_image_comp {
 368   /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
 369   int dx;
 370   /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
 371   int dy;
 372   /** data width */
 373   int w;
 374   /** data height */
 375   int h;
 376   /** x component offset compared to the whole image */
 377   int x0;
 378   /** y component offset compared to the whole image */
 379   int y0;
 380   /** precision */
 381   int prec;
 382   /** image depth in bits */
 383   int bpp;
 384   /** signed (1) / unsigned (0) */
 385   int sgnd;
 386   /** number of decoded resolution */
 387   int resno_decoded;
 388   /** number of division by 2 of the out image compared to the original size of image */
 389   int factor;
 390   /** image component data */
 391   int *data;
 392 } opj_image_comp_t;
 393
 394 /**
 395 Defines image data and characteristics
 396 */
 397 typedef struct opj_image {
 398   /** XOsiz: horizontal offset from the origin of the reference grid to the left side of the image area */
 399   int x0;
 400   /** YOsiz: vertical offset from the origin of the reference grid to the top side of the image area */
 401   int y0;
 402   /** Xsiz: width of the reference grid */
 403   int x1;
 404   /** Ysiz: height of the reference grid */
 405   int y1;
 406   /** number of components in the image */
 407   int numcomps;
 408   /** color space: sRGB, Greyscale or YUV */
 409   OPJ_COLOR_SPACE color_space;
 410   /** image components */
 411   opj_image_comp_t *comps;
 412 } opj_image_t;
 413
 414 /**
 415 Component parameters structure used by the opj_image_create function
 416 */
 417 typedef struct opj_image_comptparm {
 418   /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
 419   int dx;
 420   /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
 421   int dy;
 422   /** data width */
 423   int w;
 424   /** data height */
 425   int h;
 426   /** x component offset compared to the whole image */
 427   int x0;
 428   /** y component offset compared to the whole image */
 429   int y0;
 430   /** precision */
 431   int prec;
 432   /** image depth in bits */
 433   int bpp;
 434   /** signed (1) / unsigned (0) */
 435   int sgnd;
 436 } opj_image_cmptparm_t;
 437
 438 #ifdef __cplusplus
 439 extern "C" {
 440 #endif
 441
 442 /*
 443 ==========================================================
 444    image functions definitions
 445 ==========================================================
 446 */
 447
 448 /**
 449 Create an image
 450 @param numcmpts number of components
 451 @param cmptparms components parameters
 452 @param clrspc image color space
 453 @return returns a new image structure if successful, returns NULL otherwise
 454 */
 455 opj_image_t *opj_image_create(int numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc);
 456
 457 /**
 458 Deallocate any resources associated with an image
 459 @param image image to be destroyed
 460 */
 461 void opj_image_destroy(opj_image_t *image);
 462
 463 /*
 464 ==========================================================
 465    stream functions definitions
 466 ==========================================================
 467 */
 468
 469 /**
 470 Open and allocate a memory stream for read / write.
 471 On reading, the user must provide a buffer containing encoded data. The buffer will be
 472 wrapped by the returned CIO handle.
 473 On writing, buffer parameters must be set to 0: a buffer will be allocated by the library
 474 to contain encoded data.
 475 @param cinfo Codec context info
 476 @param buffer Reading: buffer address. Writing: NULL
 477 @param length Reading: buffer length. Writing: 0
 478 @return Returns a CIO handle if successful, returns NULL otherwise
 479 */
 480 opj_cio_t* opj_cio_open(opj_common_ptr cinfo, unsigned char *buffer, int length);
 481
 482 /**
 483 Close and free a CIO handle
 484 @param cio CIO handle to free
 485 */
 486 void opj_cio_close(opj_cio_t *cio);
 487
 488 /**
 489 Get position in byte stream
 490 @param cio CIO handle
 491 @return Returns the position in bytes
 492 */
 493 int cio_tell(opj_cio_t *cio);
 494 /**
 495 Set position in byte stream
 496 @param cio CIO handle
 497 @param pos Position, in number of bytes, from the beginning of the stream
 498 */
 499 void cio_seek(opj_cio_t *cio, int pos);
 500
 501 /*
 502 ==========================================================
 503    event manager functions definitions
 504 ==========================================================
 505 */
 506
 507 opj_event_mgr_t* opj_set_event_mgr(opj_common_ptr cinfo, opj_event_mgr_t *event_mgr, void *context);
 508
 509 /*
 510 ==========================================================
 511    codec functions definitions
 512 ==========================================================
 513 */
 514 /**
 515 Creates a J2K/JPT/JP2 decompression structure
 516 @param format Decoder to select
 517 @return Returns a handle to a decompressor if successful, returns NULL otherwise
 518 */
 519 opj_dinfo_t* opj_create_decompress(OPJ_CODEC_FORMAT format);
 520 /**
 521 Destroy a decompressor handle
 522 @param dinfo decompressor handle to destroy
 523 */
 524 void opj_destroy_decompress(opj_dinfo_t *dinfo);
 525 /**
 526 Set decoding parameters to default values
 527 @param parameters Decompression parameters
 528 */
 529 void opj_set_default_decoder_parameters(opj_dparameters_t *parameters);
 530 /**
 531 Setup the decoder decoding parameters using user parameters.
 532 Decoding parameters are returned in j2k->cp.
 533 @param dinfo decompressor handle
 534 @param parameters decompression parameters
 535 */
 536 void opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters);
 537 /**
 538 Decode an image from a JPEG-2000 codestream
 539 @param dinfo decompressor handle
 540 @param cio Input buffer stream
 541 @return Returns a decoded image if successful, returns NULL otherwise
 542 */
 543 opj_image_t* opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio);
 544 /**
 545 Creates a J2K/JP2 compression structure
 546 @param format Coder to select
 547 @return Returns a handle to a compressor if successful, returns NULL otherwise
 548 */
 549 opj_cinfo_t* opj_create_compress(OPJ_CODEC_FORMAT format);
 550 /**
 551 Destroy a compressor handle
 552 @param cinfo compressor handle to destroy
 553 */
 554 void opj_destroy_compress(opj_cinfo_t *cinfo);
 555 /**
 556 Set encoding parameters to default values, that means :
 557 <ul>
 558 <li>Lossless
 559 <li>1 tile
 560 <li>Size of precinct : 2^15 x 2^15 (means 1 precinct)
 561 <li>Size of code-block : 64 x 64
 562 <li>Number of resolutions: 6
 563 <li>No SOP marker in the codestream
 564 <li>No EPH marker in the codestream
 565 <li>No sub-sampling in x or y direction
 566 <li>No mode switch activated
 567 <li>Progression order: LRCP
 568 <li>No index file
 569 <li>No ROI upshifted
 570 <li>No offset of the origin of the image
 571 <li>No offset of the origin of the tiles
 572 <li>Reversible DWT 5-3
 573 </ul>
 574 @param parameters Compression parameters
 575 */
 576 void opj_set_default_encoder_parameters(opj_cparameters_t *parameters);
 577 /**
 578 Setup the encoder parameters using the current image and using user parameters.
 579 @param cinfo compressor handle
 580 @param parameters compression parameters
 581 @param image input filled image
 582 */
 583 void opj_setup_encoder(opj_cinfo_t *cinfo, opj_cparameters_t *parameters, opj_image_t *image);
 584 /**
 585 Encode an image into a JPEG-2000 codestream
 586 @param cinfo compressor handle
 587 @param cio Output buffer stream
 588 @param image Image to encode
 589 @param index Name of the index file if required, NULL otherwise
 590 @return Returns true if successful, returns false otherwise
 591 */
 592 bool opj_encode(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, char *index);
 593
 594 #ifdef __cplusplus
 595 }
 596 #endif
 597
 598 #endif /* OPENJPEG_H */