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(OPJ_STATIC) || !(defined(WIN32) || defined(__WIN32__))
45 #define OPJ_CALLCONV __stdcall
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.
55 #define OPJ_API __declspec(dllexport)
57 #define OPJ_API __declspec(dllimport)
58 #endif /* OPJ_EXPORTS */
59 #endif /* !OPJ_STATIC || !WIN32 */
62 #if defined(HAVE_STDBOOL_H)
64 The C language implementation does correctly provide the standard header
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
84 #endif /* __cplusplus */
87 ==========================================================
88 Useful constant definitions
89 ==========================================================
93 #define MAX_PATH 260 /**< Maximum allowed size for filenames */
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 */
100 ==========================================================
102 ==========================================================
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 */
116 Supported image color spaces
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 */
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 */
136 ==========================================================
137 event manager typedef definitions
138 ==========================================================
142 Callback function prototype for events
143 @param msg Event message
146 typedef void (*opj_msg_callback) (const char *msg, void *client_data);
149 Message handler object
154 <li>Debugging messages
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;
168 ==========================================================
169 codec typedef definitions
170 ==========================================================
174 Progression order changes
176 typedef struct opj_poc {
178 int layno1, resno1, compno1;
185 Compression parameters
187 typedef struct opj_cparameters {
188 /** size of tile: tile_size_on = false (not in argument) or = true (in argument) */
198 /** allocation by rate/distortion */
200 /** allocation by fixed layer */
202 /** add fixed_quality */
203 int cp_fixed_quality;
206 /** comment for coding */
208 /** csty : coding style */
210 /** progression order (default LRCP) */
211 OPJ_PROG_ORDER prog_order;
212 /** progression order changes */
214 /** number of progression order changes (POC), default to 0 */
216 /** number of layers */
218 /** rates of layers */
220 /** different psnr for successive layers */
221 float tcp_distoratio[100];
222 /** number of resolutions */
224 /** initial code block width, default to 64 */
226 /** initial code block height, default to 64 */
228 /** mode switch (cblk_style) */
230 /** 1 : use the irreversible DWT 9-7, 0 : use lossless compression (default) */
232 /** region of interest: affected component in [0..3], -1 means no ROI */
234 /** region of interest: upshift value */
236 /* number of precinct size specifications */
238 /** initial precinct width */
239 int prcw_init[J2K_MAXRLVLS];
240 /** initial precinct height */
241 int prch_init[J2K_MAXRLVLS];
243 /**@name command line encoder parameters (not used inside the library) */
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) */
251 /** index file name */
252 char index[MAX_PATH];
253 /** subimage encoding: origin image offset in x direction */
255 /** subimage encoding: origin image offset in y direction */
257 /** subsampling value for dx */
259 /** subsampling value for dy */
261 /** input file format 0: PGX, 1: PxM, 2: BMP */
263 /** output file format 0: J2K, 1: JP2, 2: JPT */
269 Decompression parameters
271 typedef struct opj_dparameters {
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
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
288 /**@name command line encoder parameters (not used inside the library) */
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 */
296 /** output file format 0: PGX, 1: PxM, 2: BMP */
301 /** Common fields between JPEG-2000 compression and decompression master structs. */
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 */
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.
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++.)
321 } opj_common_struct_t;
323 typedef opj_common_struct_t * opj_common_ptr;
326 Compression context info
328 typedef struct opj_cinfo {
329 /** Fields shared with opj_dinfo_t */
331 /* other specific fields go here */
335 Decompression context info
337 typedef struct opj_dinfo {
338 /** Fields shared with opj_cinfo_t */
340 /* other specific fields go here */
344 ==========================================================
345 I/O stream typedef definitions
346 ==========================================================
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
358 Byte input-output stream (CIO)
360 typedef struct opj_cio {
362 opj_common_ptr cinfo;
364 /** open mode (read/write) either OPJ_STREAM_READ or OPJ_STREAM_WRITE */
366 /** pointer to the start of the buffer */
367 unsigned char *buffer;
368 /** buffer size in bytes */
371 /** pointer to the start of the stream */
372 unsigned char *start;
373 /** pointer to the end of the stream */
375 /** pointer to the current position */
380 ==========================================================
381 image typedef definitions
382 ==========================================================
386 Defines a single image component
388 typedef struct opj_image_comp {
389 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
391 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
397 /** x component offset compared to the whole image */
399 /** y component offset compared to the whole image */
403 /** image depth in bits */
405 /** signed (1) / unsigned (0) */
407 /** number of decoded resolution */
409 /** number of division by 2 of the out image compared to the original size of image */
411 /** image component data */
416 Defines image data and characteristics
418 typedef struct opj_image {
419 /** XOsiz: horizontal offset from the origin of the reference grid to the left side of the image area */
421 /** YOsiz: vertical offset from the origin of the reference grid to the top side of the image area */
423 /** Xsiz: width of the reference grid */
425 /** Ysiz: height of the reference grid */
427 /** number of components in the image */
429 /** color space: sRGB, Greyscale or YUV */
430 OPJ_COLOR_SPACE color_space;
431 /** image components */
432 opj_image_comp_t *comps;
436 Component parameters structure used by the opj_image_create function
438 typedef struct opj_image_comptparm {
439 /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */
441 /** YRsiz: vertical separation of a sample of ith component with respect to the reference grid */
447 /** x component offset compared to the whole image */
449 /** y component offset compared to the whole image */
453 /** image depth in bits */
455 /** signed (1) / unsigned (0) */
457 } opj_image_cmptparm_t;
465 ==========================================================
467 ==========================================================
470 OPJ_API const char * OPJ_CALLCONV opj_version();
473 ==========================================================
474 image functions definitions
475 ==========================================================
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
485 OPJ_API opj_image_t* OPJ_CALLCONV opj_image_create(int numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc);
488 Deallocate any resources associated with an image
489 @param image image to be destroyed
491 OPJ_API void OPJ_CALLCONV opj_image_destroy(opj_image_t *image);
494 ==========================================================
495 stream functions definitions
496 ==========================================================
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
510 OPJ_API opj_cio_t* OPJ_CALLCONV opj_cio_open(opj_common_ptr cinfo, unsigned char *buffer, int length);
513 Close and free a CIO handle
514 @param cio CIO handle to free
516 OPJ_API void OPJ_CALLCONV opj_cio_close(opj_cio_t *cio);
519 Get position in byte stream
520 @param cio CIO handle
521 @return Returns the position in bytes
523 OPJ_API int OPJ_CALLCONV cio_tell(opj_cio_t *cio);
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
529 OPJ_API void OPJ_CALLCONV cio_seek(opj_cio_t *cio, int pos);
532 ==========================================================
533 event manager functions definitions
534 ==========================================================
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);
540 ==========================================================
541 codec functions definitions
542 ==========================================================
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
549 OPJ_API opj_dinfo_t* OPJ_CALLCONV opj_create_decompress(OPJ_CODEC_FORMAT format);
551 Destroy a decompressor handle
552 @param dinfo decompressor handle to destroy
554 OPJ_API void OPJ_CALLCONV opj_destroy_decompress(opj_dinfo_t *dinfo);
556 Set decoding parameters to default values
557 @param parameters Decompression parameters
559 OPJ_API void OPJ_CALLCONV opj_set_default_decoder_parameters(opj_dparameters_t *parameters);
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
566 OPJ_API void OPJ_CALLCONV opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters);
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
573 OPJ_API opj_image_t* OPJ_CALLCONV opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio);
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
579 OPJ_API opj_cinfo_t* OPJ_CALLCONV opj_create_compress(OPJ_CODEC_FORMAT format);
581 Destroy a compressor handle
582 @param cinfo compressor handle to destroy
584 OPJ_API void OPJ_CALLCONV opj_destroy_compress(opj_cinfo_t *cinfo);
586 Set encoding parameters to default values, that means :
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
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
604 @param parameters Compression parameters
606 OPJ_API void OPJ_CALLCONV opj_set_default_encoder_parameters(opj_cparameters_t *parameters);
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
613 OPJ_API void OPJ_CALLCONV opj_setup_encoder(opj_cinfo_t *cinfo, opj_cparameters_t *parameters, opj_image_t *image);
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
622 OPJ_API bool OPJ_CALLCONV opj_encode(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, char *index);
628 #endif /* OPENJPEG_H */