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