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 */