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 #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 ==========================================================
 445    openjpeg version
 446 ==========================================================
 447 */
 448
 449 const char * opj_version();
 450
 451 /*
 452 ==========================================================
 453    image functions definitions
 454 ==========================================================
 455 */
 456
 457 /**
 458 Create an image
 459 @param numcmpts number of components
 460 @param cmptparms components parameters
 461 @param clrspc image color space
 462 @return returns a new image structure if successful, returns NULL otherwise
 463 */
 464 opj_image_t *opj_image_create(int numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc);
 465
 466 /**
 467 Deallocate any resources associated with an image
 468 @param image image to be destroyed
 469 */
 470 void opj_image_destroy(opj_image_t *image);
 471
 472 /*
 473 ==========================================================
 474    stream functions definitions
 475 ==========================================================
 476 */
 477
 478 /**
 479 Open and allocate a memory stream for read / write.
 480 On reading, the user must provide a buffer containing encoded data. The buffer will be
 481 wrapped by the returned CIO handle.
 482 On writing, buffer parameters must be set to 0: a buffer will be allocated by the library
 483 to contain encoded data.
 484 @param cinfo Codec context info
 485 @param buffer Reading: buffer address. Writing: NULL
 486 @param length Reading: buffer length. Writing: 0
 487 @return Returns a CIO handle if successful, returns NULL otherwise
 488 */
 489 opj_cio_t* opj_cio_open(opj_common_ptr cinfo, unsigned char *buffer, int length);
 490
 491 /**
 492 Close and free a CIO handle
 493 @param cio CIO handle to free
 494 */
 495 void opj_cio_close(opj_cio_t *cio);
 496
 497 /**
 498 Get position in byte stream
 499 @param cio CIO handle
 500 @return Returns the position in bytes
 501 */
 502 int cio_tell(opj_cio_t *cio);
 503 /**
 504 Set position in byte stream
 505 @param cio CIO handle
 506 @param pos Position, in number of bytes, from the beginning of the stream
 507 */
 508 void cio_seek(opj_cio_t *cio, int pos);
 509
 510 /*
 511 ==========================================================
 512    event manager functions definitions
 513 ==========================================================
 514 */
 515
 516 opj_event_mgr_t* opj_set_event_mgr(opj_common_ptr cinfo, opj_event_mgr_t *event_mgr, void *context);
 517
 518 /*
 519 ==========================================================
 520    codec functions definitions
 521 ==========================================================
 522 */
 523 /**
 524 Creates a J2K/JPT/JP2 decompression structure
 525 @param format Decoder to select
 526 @return Returns a handle to a decompressor if successful, returns NULL otherwise
 527 */
 528 opj_dinfo_t* opj_create_decompress(OPJ_CODEC_FORMAT format);
 529 /**
 530 Destroy a decompressor handle
 531 @param dinfo decompressor handle to destroy
 532 */
 533 void opj_destroy_decompress(opj_dinfo_t *dinfo);
 534 /**
 535 Set decoding parameters to default values
 536 @param parameters Decompression parameters
 537 */
 538 void opj_set_default_decoder_parameters(opj_dparameters_t *parameters);
 539 /**
 540 Setup the decoder decoding parameters using user parameters.
 541 Decoding parameters are returned in j2k->cp.
 542 @param dinfo decompressor handle
 543 @param parameters decompression parameters
 544 */
 545 void opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters);
 546 /**
 547 Decode an image from a JPEG-2000 codestream
 548 @param dinfo decompressor handle
 549 @param cio Input buffer stream
 550 @return Returns a decoded image if successful, returns NULL otherwise
 551 */
 552 opj_image_t* opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio);
 553 /**
 554 Creates a J2K/JP2 compression structure
 555 @param format Coder to select
 556 @return Returns a handle to a compressor if successful, returns NULL otherwise
 557 */
 558 opj_cinfo_t* opj_create_compress(OPJ_CODEC_FORMAT format);
 559 /**
 560 Destroy a compressor handle
 561 @param cinfo compressor handle to destroy
 562 */
 563 void opj_destroy_compress(opj_cinfo_t *cinfo);
 564 /**
 565 Set encoding parameters to default values, that means :
 566 <ul>
 567 <li>Lossless
 568 <li>1 tile
 569 <li>Size of precinct : 2^15 x 2^15 (means 1 precinct)
 570 <li>Size of code-block : 64 x 64
 571 <li>Number of resolutions: 6
 572 <li>No SOP marker in the codestream
 573 <li>No EPH marker in the codestream
 574 <li>No sub-sampling in x or y direction
 575 <li>No mode switch activated
 576 <li>Progression order: LRCP
 577 <li>No index file
 578 <li>No ROI upshifted
 579 <li>No offset of the origin of the image
 580 <li>No offset of the origin of the tiles
 581 <li>Reversible DWT 5-3
 582 </ul>
 583 @param parameters Compression parameters
 584 */
 585 void opj_set_default_encoder_parameters(opj_cparameters_t *parameters);
 586 /**
 587 Setup the encoder parameters using the current image and using user parameters.
 588 @param cinfo compressor handle
 589 @param parameters compression parameters
 590 @param image input filled image
 591 */
 592 void opj_setup_encoder(opj_cinfo_t *cinfo, opj_cparameters_t *parameters, opj_image_t *image);
 593 /**
 594 Encode an image into a JPEG-2000 codestream
 595 @param cinfo compressor handle
 596 @param cio Output buffer stream
 597 @param image Image to encode
 598 @param index Name of the index file if required, NULL otherwise
 599 @return Returns true if successful, returns false otherwise
 600 */
 601 bool opj_encode(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, char *index);
 602
 603 #ifdef __cplusplus
 604 }
 605 #endif
 606
 607 #endif /* OPENJPEG_H */