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