2 * Copyright (c) 2001-2003, David Janssens
\r
3 * Copyright (c) 2002-2003, Yannick Verschueren
\r
4 * Copyright (c) 2003-2005, Francois Devaux and Antonin Descampe
\r
5 * Copyright (c) 2005, Hervé Drolon, FreeImage Team
\r
6 * Copyright (c) 2002-2005, Communications and remote sensing Laboratory, Universite catholique de Louvain, Belgium
\r
7 * All rights reserved.
\r
9 * Redistribution and use in source and binary forms, with or without
\r
10 * modification, are permitted provided that the following conditions
\r
12 * 1. Redistributions of source code must retain the above copyright
\r
13 * notice, this list of conditions and the following disclaimer.
\r
14 * 2. Redistributions in binary form must reproduce the above copyright
\r
15 * notice, this list of conditions and the following disclaimer in the
\r
16 * documentation and/or other materials provided with the distribution.
\r
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
\r
19 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\r
20 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\r
21 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
\r
22 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
\r
23 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
\r
24 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
\r
25 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
\r
26 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
\r
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\r
28 * POSSIBILITY OF SUCH DAMAGE.
\r
33 #define OPENJPEG_VERSION "1.0.0"
\r
36 ==========================================================
\r
38 ==========================================================
\r
41 #if defined(HAVE_STDBOOL_H)
\r
43 The C language implementation does correctly provide the standard header
\r
46 #include <stdbool.h>
\r
49 The C language implementation does not provide the standard header file
\r
50 "stdbool.h" as required by ISO/IEC 9899:1999. Try to compensate for this
\r
63 #endif /* __cplusplus */
\r
66 ==========================================================
\r
67 Useful constant definitions
\r
68 ==========================================================
\r
72 #define MAX_PATH 260 /**< Maximum allowed size for filenames */
\r
73 #endif /* MAX_PATH */
\r
75 #define J2K_MAXRLVLS 33 /**< Number of maximum resolution level authorized */
\r
76 #define J2K_MAXBANDS (3*J2K_MAXRLVLS-2) /**< Number of maximum sub-band linked to number of resolution level */
\r
79 ==========================================================
\r
81 ==========================================================
\r
84 /** Progression order */
\r
85 typedef enum PROG_ORDER {
\r
86 PROG_UNKNOWN = -1, /**< place-holder */
\r
87 LRCP = 0, /**< layer-resolution-component-precinct order */
\r
88 RLCP = 1, /**< resolution-layer-component-precinct order */
\r
89 RPCL = 2, /**< resolution-precinct-component-layer order */
\r
90 PCRL = 3, /**< precinct-component-resolution-layer order */
\r
91 CPRL = 4 /**< component-precinct-resolution-layer order */
\r
95 Supported image color spaces
\r
97 typedef enum COLOR_SPACE {
\r
98 CLRSPC_UNKNOWN = -1, /**< place-holder */
\r
99 CLRSPC_SRGB = 1, /**< sRGB */
\r
100 CLRSPC_GRAY = 2, /**< grayscale */
\r
101 CLRSPC_SYCC = 3 /**< YUV */
\r
107 typedef enum CODEC_FORMAT {
\r
108 CODEC_UNKNOWN = -1, /**< place-holder */
\r
109 CODEC_J2K = 0, /**< JPEG-2000 codestream : read/write */
\r
110 CODEC_JPT = 1, /**< JPT-stream (JPEG 2000, JPIP) : read only */
\r
111 CODEC_JP2 = 2 /**< JPEG-2000 file format : read/write */
\r
112 } OPJ_CODEC_FORMAT;
\r
115 ==========================================================
\r
116 event manager typedef definitions
\r
117 ==========================================================
\r
121 Callback function prototype for events
\r
122 @param msg Event message
\r
123 @param client_data
\r
125 typedef void (*opj_msg_callback) (const char *msg, void *client_data);
\r
128 Message handler object
\r
132 <li>Warning messages
\r
133 <li>Debugging messages
\r
136 typedef struct opj_event_mgr {
\r
137 /** Error message callback if available, NULL otherwise */
\r
138 opj_msg_callback error_handler;
\r
139 /** Warning message callback if available, NULL otherwise */
\r
140 opj_msg_callback warning_handler;
\r
141 /** Debug message callback if available, NULL otherwise */
\r
142 opj_msg_callback info_handler;
\r
147 ==========================================================
\r
148 codec typedef definitions
\r
149 ==========================================================
\r
153 Progression order changes
\r
155 typedef struct opj_poc {
\r
156 int resno0, compno0;
\r
157 int layno1, resno1, compno1;
\r
158 OPJ_PROG_ORDER prg;
\r
164 Compression parameters
\r
166 typedef struct opj_cparameters {
\r
167 /** size of tile: tile_size_on = false (not in argument) or = true (in argument) */
\r
177 /** allocation by rate/distortion */
\r
178 int cp_disto_alloc;
\r
179 /** allocation by fixed layer */
\r
180 int cp_fixed_alloc;
\r
181 /** add fixed_quality */
\r
182 int cp_fixed_quality;
\r
185 /** comment for coding */
\r
187 /** csty : coding style */
\r
189 /** progression order (default LRCP) */
\r
190 OPJ_PROG_ORDER prog_order;
\r
191 /** progression order changes */
\r
193 /** number of progression order changes (POC), default to 0 */
\r
195 /** number of layers */
\r
197 /** rates of layers */
\r
198 int tcp_rates[100];
\r
199 /** different psnr for successive layers */
\r
200 float tcp_distoratio[100];
\r
201 /** number of resolutions */
\r
203 /** initial code block width, default to 64 */
\r
205 /** initial code block height, default to 64 */
\r
207 /** mode switch (cblk_style) */
\r
209 /** 1 : use the irreversible DWT 9-7, 0 : use lossless compression (default) */
\r
211 /** region of interest: affected component in [0..3], -1 means no ROI */
\r
213 /** region of interest: upshift value */
\r
215 /* number of precinct size specifications */
\r
217 /** initial precinct width */
\r
218 int prcw_init[J2K_MAXRLVLS];
\r
219 /** initial precinct height */
\r
220 int prch_init[J2K_MAXRLVLS];
\r
222 /**@name command line encoder parameters (not used inside the library) */
\r
224 /** input file name */
\r
225 char infile[MAX_PATH];
\r
226 /** output file name */
\r
227 char outfile[MAX_PATH];
\r
228 /** creation of an index file, default to 0 (false) */
\r
230 /** index file name */
\r
231 char index[MAX_PATH];
\r
232 /** subimage encoding: origin image offset in x direction */
\r
233 int image_offset_x0;
\r
234 /** subimage encoding: origin image offset in y direction */
\r
235 int image_offset_y0;
\r
236 /** subsampling value for dx */
\r
237 int subsampling_dx;
\r
238 /** subsampling value for dy */
\r
239 int subsampling_dy;
\r
240 /** input file format 0: PGX, 1: PxM, 2: BMP */
\r
242 /** output file format 0: J2K, 1: JP2, 2: JPT */
\r
245 } opj_cparameters_t;
\r
248 Decompression parameters
\r
250 typedef struct opj_dparameters {
\r
252 Set the number of highest resolution levels to be discarded.
\r
253 The image resolution is effectively divided by 2 to the power of the number of discarded levels.
\r
254 The reduce factor is limited by the smallest total number of decomposition levels among tiles.
\r
255 if != 0, then original dimension divided by 2^(reduce);
\r
256 if == 0 or not used, image is decoded to the full resolution
\r
260 Set the maximum number of quality layers to decode.
\r
261 If there are less quality layers than the specified number, all the quality layers are decoded.
\r
262 if != 0, then only the first "layer" layers are decoded;
\r
263 if == 0 or not used, all the quality layers are decoded
\r
267 /**@name command line encoder parameters (not used inside the library) */
\r
269 /** input file name */
\r
270 char infile[MAX_PATH];
\r
271 /** output file name */
\r
272 char outfile[MAX_PATH];
\r
273 /** input file format 0: J2K, 1: JP2, 2: JPT */
\r
275 /** output file format 0: PGX, 1: PxM, 2: BMP */
\r
278 } opj_dparameters_t;
\r
280 /** Common fields between JPEG-2000 compression and decompression master structs. */
\r
282 #define opj_common_fields \
\r
283 opj_event_mgr_t *event_mgr; /**< pointer to the event manager */\
\r
284 void * client_data; /**< Available for use by application */\
\r
285 bool is_decompressor; /**< So common code can tell which is which */\
\r
286 OPJ_CODEC_FORMAT codec_format; /**< selected codec */\
\r
287 void *j2k_handle; /**< pointer to the J2K codec */\
\r
288 void *jp2_handle /**< pointer to the JP2 codec */
\r
290 /* Routines that are to be used by both halves of the library are declared
\r
291 * to receive a pointer to this structure. There are no actual instances of
\r
292 * opj_common_struct_t, only of opj_cinfo_t and opj_dinfo_t.
\r
294 typedef struct opj_common_struct {
\r
295 opj_common_fields; /* Fields common to both master struct types */
\r
296 /* Additional fields follow in an actual opj_cinfo_t or
\r
297 * opj_dinfo_t. All three structs must agree on these
\r
298 * initial fields! (This would be a lot cleaner in C++.)
\r
300 } opj_common_struct_t;
\r
302 typedef opj_common_struct_t * opj_common_ptr;
\r
305 Compression context info
\r
307 typedef struct opj_cinfo {
\r
308 /** Fields shared with opj_dinfo_t */
\r
309 opj_common_fields;
\r
310 /* other specific fields go here */
\r
314 Decompression context info
\r
316 typedef struct opj_dinfo {
\r
317 /** Fields shared with opj_cinfo_t */
\r
318 opj_common_fields;
\r
319 /* other specific fields go here */
\r
323 ==========================================================
\r
324 I/O stream typedef definitions
\r
325 ==========================================================
\r
329 * Stream open flags.
\r
331 /** The stream was opened for reading. */
\r
332 #define OPJ_STREAM_READ 0x0001
\r
333 /** The stream was opened for writing. */
\r
334 #define OPJ_STREAM_WRITE 0x0002
\r
337 Byte input-output stream (CIO)
\r
339 typedef struct opj_cio {
\r
340 /** codec context */
\r
341 opj_common_ptr cinfo;
\r
343 /** open mode (read/write) either OPJ_STREAM_READ or OPJ_STREAM_WRITE */
\r
345 /** pointer to the start of the buffer */
\r
346 unsigned char *buffer;
\r
347 /** buffer size in bytes */
\r
350 /** pointer to the start of the stream */
\r
351 unsigned char *start;
\r
352 /** pointer to the end of the stream */
\r
353 unsigned char *end;
\r
354 /** pointer to the current position */
\r
359 ==========================================================
\r
360 image typedef definitions
\r
361 ==========================================================
\r
365 Defines a single image component
\r
367 typedef struct opj_image_comp {
\r
368 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
\r
370 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
\r
376 /** x component offset compared to the whole image */
\r
378 /** y component offset compared to the whole image */
\r
382 /** image depth in bits */
\r
384 /** signed (1) / unsigned (0) */
\r
386 /** number of decoded resolution */
\r
388 /** number of division by 2 of the out image compared to the original size of image */
\r
390 /** image component data */
\r
392 } opj_image_comp_t;
\r
395 Defines image data and characteristics
\r
397 typedef struct opj_image {
\r
398 /** XOsiz: horizontal offset from the origin of the reference grid to the left side of the image area */
\r
400 /** YOsiz: vertical offset from the origin of the reference grid to the top side of the image area */
\r
402 /** Xsiz: width of the reference grid */
\r
404 /** Ysiz: height of the reference grid */
\r
406 /** number of components in the image */
\r
408 /** color space: sRGB, Greyscale or YUV */
\r
409 OPJ_COLOR_SPACE color_space;
\r
410 /** image components */
\r
411 opj_image_comp_t *comps;
\r
415 Component parameters structure used by the opj_image_create function
\r
417 typedef struct opj_image_comptparm {
\r
418 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
\r
420 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
\r
426 /** x component offset compared to the whole image */
\r
428 /** y component offset compared to the whole image */
\r
432 /** image depth in bits */
\r
434 /** signed (1) / unsigned (0) */
\r
436 } opj_image_cmptparm_t;
\r
444 ==========================================================
\r
446 ==========================================================
\r
449 const char * opj_version();
\r
452 ==========================================================
\r
453 image functions definitions
\r
454 ==========================================================
\r
459 @param numcmpts number of components
\r
460 @param cmptparms components parameters
\r
461 @param clrspc image color space
\r
462 @return returns a new image structure if successful, returns NULL otherwise
\r
464 opj_image_t *opj_image_create(int numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc);
\r
467 Deallocate any resources associated with an image
\r
468 @param image image to be destroyed
\r
470 void opj_image_destroy(opj_image_t *image);
\r
473 ==========================================================
\r
474 stream functions definitions
\r
475 ==========================================================
\r
479 Open and allocate a memory stream for read / write.
\r
480 On reading, the user must provide a buffer containing encoded data. The buffer will be
\r
481 wrapped by the returned CIO handle.
\r
482 On writing, buffer parameters must be set to 0: a buffer will be allocated by the library
\r
483 to contain encoded data.
\r
484 @param cinfo Codec context info
\r
485 @param buffer Reading: buffer address. Writing: NULL
\r
486 @param length Reading: buffer length. Writing: 0
\r
487 @return Returns a CIO handle if successful, returns NULL otherwise
\r
489 opj_cio_t* opj_cio_open(opj_common_ptr cinfo, unsigned char *buffer, int length);
\r
492 Close and free a CIO handle
\r
493 @param cio CIO handle to free
\r
495 void opj_cio_close(opj_cio_t *cio);
\r
498 Get position in byte stream
\r
499 @param cio CIO handle
\r
500 @return Returns the position in bytes
\r
502 int cio_tell(opj_cio_t *cio);
\r
504 Set position in byte stream
\r
505 @param cio CIO handle
\r
506 @param pos Position, in number of bytes, from the beginning of the stream
\r
508 void cio_seek(opj_cio_t *cio, int pos);
\r
511 ==========================================================
\r
512 event manager functions definitions
\r
513 ==========================================================
\r
516 opj_event_mgr_t* opj_set_event_mgr(opj_common_ptr cinfo, opj_event_mgr_t *event_mgr, void *context);
\r
519 ==========================================================
\r
520 codec functions definitions
\r
521 ==========================================================
\r
524 Creates a J2K/JPT/JP2 decompression structure
\r
525 @param format Decoder to select
\r
526 @return Returns a handle to a decompressor if successful, returns NULL otherwise
\r
528 opj_dinfo_t* opj_create_decompress(OPJ_CODEC_FORMAT format);
\r
530 Destroy a decompressor handle
\r
531 @param dinfo decompressor handle to destroy
\r
533 void opj_destroy_decompress(opj_dinfo_t *dinfo);
\r
535 Set decoding parameters to default values
\r
536 @param parameters Decompression parameters
\r
538 void opj_set_default_decoder_parameters(opj_dparameters_t *parameters);
\r
540 Setup the decoder decoding parameters using user parameters.
\r
541 Decoding parameters are returned in j2k->cp.
\r
542 @param dinfo decompressor handle
\r
543 @param parameters decompression parameters
\r
545 void opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters);
\r
547 Decode an image from a JPEG-2000 codestream
\r
548 @param dinfo decompressor handle
\r
549 @param cio Input buffer stream
\r
550 @return Returns a decoded image if successful, returns NULL otherwise
\r
552 opj_image_t* opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio);
\r
554 Creates a J2K/JP2 compression structure
\r
555 @param format Coder to select
\r
556 @return Returns a handle to a compressor if successful, returns NULL otherwise
\r
558 opj_cinfo_t* opj_create_compress(OPJ_CODEC_FORMAT format);
\r
560 Destroy a compressor handle
\r
561 @param cinfo compressor handle to destroy
\r
563 void opj_destroy_compress(opj_cinfo_t *cinfo);
\r
565 Set encoding parameters to default values, that means :
\r
569 <li>Size of precinct : 2^15 x 2^15 (means 1 precinct)
\r
570 <li>Size of code-block : 64 x 64
\r
571 <li>Number of resolutions: 6
\r
572 <li>No SOP marker in the codestream
\r
573 <li>No EPH marker in the codestream
\r
574 <li>No sub-sampling in x or y direction
\r
575 <li>No mode switch activated
\r
576 <li>Progression order: LRCP
\r
578 <li>No ROI upshifted
\r
579 <li>No offset of the origin of the image
\r
580 <li>No offset of the origin of the tiles
\r
581 <li>Reversible DWT 5-3
\r
583 @param parameters Compression parameters
\r
585 void opj_set_default_encoder_parameters(opj_cparameters_t *parameters);
\r
587 Setup the encoder parameters using the current image and using user parameters.
\r
588 @param cinfo compressor handle
\r
589 @param parameters compression parameters
\r
590 @param image input filled image
\r
592 void opj_setup_encoder(opj_cinfo_t *cinfo, opj_cparameters_t *parameters, opj_image_t *image);
\r
594 Encode an image into a JPEG-2000 codestream
\r
595 @param cinfo compressor handle
\r
596 @param cio Output buffer stream
\r
597 @param image Image to encode
\r
598 @param index Name of the index file if required, NULL otherwise
\r
599 @return Returns true if successful, returns false otherwise
\r
601 bool opj_encode(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, char *index);
\r
607 #endif /* OPENJPEG_H */
\r