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