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
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
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.
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.
33 #define OPENJPEG_VERSION "1.0.0"
36 ==========================================================
38 ==========================================================
41 #if defined(HAVE_STDBOOL_H)
43 The C language implementation does correctly provide the standard header
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
63 #endif /* __cplusplus */
66 ==========================================================
67 Useful constant definitions
68 ==========================================================
72 #define MAX_PATH 260 /**< Maximum allowed size for filenames */
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 */
79 ==========================================================
81 ==========================================================
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 */
95 Supported image color spaces
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 */
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 */
115 ==========================================================
116 event manager typedef definitions
117 ==========================================================
121 Callback function prototype for events
122 @param msg Event message
125 typedef void (*opj_msg_callback) (const char *msg, void *client_data);
128 Message handler object
133 <li>Debugging messages
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;
147 ==========================================================
148 codec typedef definitions
149 ==========================================================
153 Progression order changes
155 typedef struct opj_poc {
157 int layno1, resno1, compno1;
164 Compression parameters
166 typedef struct opj_cparameters {
167 /** size of tile: tile_size_on = false (not in argument) or = true (in argument) */
177 /** allocation by rate/distortion */
179 /** allocation by fixed layer */
181 /** add fixed_quality */
182 int cp_fixed_quality;
185 /** comment for coding */
187 /** csty : coding style */
189 /** progression order (default LRCP) */
190 OPJ_PROG_ORDER prog_order;
191 /** progression order changes */
193 /** number of progression order changes (POC), default to 0 */
195 /** number of layers */
197 /** rates of layers */
199 /** different psnr for successive layers */
200 float tcp_distoratio[100];
201 /** number of resolutions */
203 /** initial code block width, default to 64 */
205 /** initial code block height, default to 64 */
207 /** mode switch (cblk_style) */
209 /** 1 : use the irreversible DWT 9-7, 0 : use lossless compression (default) */
211 /** region of interest: affected component in [0..3], -1 means no ROI */
213 /** region of interest: upshift value */
215 /* number of precinct size specifications */
217 /** initial precinct width */
218 int prcw_init[J2K_MAXRLVLS];
219 /** initial precinct height */
220 int prch_init[J2K_MAXRLVLS];
222 /**@name command line encoder parameters (not used inside the library) */
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) */
230 /** index file name */
231 char index[MAX_PATH];
232 /** subimage encoding: origin image offset in x direction */
234 /** subimage encoding: origin image offset in y direction */
236 /** subsampling value for dx */
238 /** subsampling value for dy */
240 /** input file format 0: PGX, 1: PxM, 2: BMP */
242 /** output file format 0: J2K, 1: JP2, 2: JPT */
248 Decompression parameters
250 typedef struct opj_dparameters {
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
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
267 /**@name command line encoder parameters (not used inside the library) */
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 */
275 /** output file format 0: PGX, 1: PxM, 2: BMP */
280 /** Common fields between JPEG-2000 compression and decompression master structs. */
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 */
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.
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++.)
300 } opj_common_struct_t;
302 typedef opj_common_struct_t * opj_common_ptr;
305 Compression context info
307 typedef struct opj_cinfo {
308 /** Fields shared with opj_dinfo_t */
310 /* other specific fields go here */
314 Decompression context info
316 typedef struct opj_dinfo {
317 /** Fields shared with opj_cinfo_t */
319 /* other specific fields go here */
323 ==========================================================
324 I/O stream typedef definitions
325 ==========================================================
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
337 Byte input-output stream (CIO)
339 typedef struct opj_cio {
341 opj_common_ptr cinfo;
343 /** open mode (read/write) either OPJ_STREAM_READ or OPJ_STREAM_WRITE */
345 /** pointer to the start of the buffer */
346 unsigned char *buffer;
347 /** buffer size in bytes */
350 /** pointer to the start of the stream */
351 unsigned char *start;
352 /** pointer to the end of the stream */
354 /** pointer to the current position */
359 ==========================================================
360 image typedef definitions
361 ==========================================================
365 Defines a single image component
367 typedef struct opj_image_comp {
368 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
370 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
376 /** x component offset compared to the whole image */
378 /** y component offset compared to the whole image */
382 /** image depth in bits */
384 /** signed (1) / unsigned (0) */
386 /** number of decoded resolution */
388 /** number of division by 2 of the out image compared to the original size of image */
390 /** image component data */
395 Defines image data and characteristics
397 typedef struct opj_image {
398 /** XOsiz: horizontal offset from the origin of the reference grid to the left side of the image area */
400 /** YOsiz: vertical offset from the origin of the reference grid to the top side of the image area */
402 /** Xsiz: width of the reference grid */
404 /** Ysiz: height of the reference grid */
406 /** number of components in the image */
408 /** color space: sRGB, Greyscale or YUV */
409 OPJ_COLOR_SPACE color_space;
410 /** image components */
411 opj_image_comp_t *comps;
415 Component parameters structure used by the opj_image_create function
417 typedef struct opj_image_comptparm {
418 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
420 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
426 /** x component offset compared to the whole image */
428 /** y component offset compared to the whole image */
432 /** image depth in bits */
434 /** signed (1) / unsigned (0) */
436 } opj_image_cmptparm_t;
444 ==========================================================
446 ==========================================================
449 const char * opj_version();
452 ==========================================================
453 image functions definitions
454 ==========================================================
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
464 opj_image_t *opj_image_create(int numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc);
467 Deallocate any resources associated with an image
468 @param image image to be destroyed
470 void opj_image_destroy(opj_image_t *image);
473 ==========================================================
474 stream functions definitions
475 ==========================================================
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
489 opj_cio_t* opj_cio_open(opj_common_ptr cinfo, unsigned char *buffer, int length);
492 Close and free a CIO handle
493 @param cio CIO handle to free
495 void opj_cio_close(opj_cio_t *cio);
498 Get position in byte stream
499 @param cio CIO handle
500 @return Returns the position in bytes
502 int cio_tell(opj_cio_t *cio);
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
508 void cio_seek(opj_cio_t *cio, int pos);
511 ==========================================================
512 event manager functions definitions
513 ==========================================================
516 opj_event_mgr_t* opj_set_event_mgr(opj_common_ptr cinfo, opj_event_mgr_t *event_mgr, void *context);
519 ==========================================================
520 codec functions definitions
521 ==========================================================
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
528 opj_dinfo_t* opj_create_decompress(OPJ_CODEC_FORMAT format);
530 Destroy a decompressor handle
531 @param dinfo decompressor handle to destroy
533 void opj_destroy_decompress(opj_dinfo_t *dinfo);
535 Set decoding parameters to default values
536 @param parameters Decompression parameters
538 void opj_set_default_decoder_parameters(opj_dparameters_t *parameters);
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
545 void opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters);
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
552 opj_image_t* opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio);
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
558 opj_cinfo_t* opj_create_compress(OPJ_CODEC_FORMAT format);
560 Destroy a compressor handle
561 @param cinfo compressor handle to destroy
563 void opj_destroy_compress(opj_cinfo_t *cinfo);
565 Set encoding parameters to default values, that means :
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
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
583 @param parameters Compression parameters
585 void opj_set_default_encoder_parameters(opj_cparameters_t *parameters);
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
592 void opj_setup_encoder(opj_cinfo_t *cinfo, opj_cparameters_t *parameters, opj_image_t *image);
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
601 bool opj_encode(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, char *index);
607 #endif /* OPENJPEG_H */