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