1 /* 2 * The copyright in this software is being made available under the 2-clauses 3 * BSD License, included below. This software may be subject to other third 4 * party and contributor rights, including patent rights, and no such rights 5 * are granted under this license. 6 * 7 * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium 8 * Copyright (c) 2002-2014, Professor Benoit Macq 9 * Copyright (c) 2002-2003, Yannick Verschueren 10 * Copyright (c) 2005, Herve Drolon, FreeImage Team 11 * Copyright (c) 2008, 2011-2012, Centre National d'Etudes Spatiales (CNES), FR 12 * Copyright (c) 2012, CS Systemes d'Information, France 13 * All rights reserved. 14 * 15 * Redistribution and use in source and binary forms, with or without 16 * modification, are permitted provided that the following conditions 17 * are met: 18 * 1. Redistributions of source code must retain the above copyright 19 * notice, this list of conditions and the following disclaimer. 20 * 2. Redistributions in binary form must reproduce the above copyright 21 * notice, this list of conditions and the following disclaimer in the 22 * documentation and/or other materials provided with the distribution. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS' 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 * POSSIBILITY OF SUCH DAMAGE. 35 */ 36 #ifndef OPJ_JP2_H 37 #define OPJ_JP2_H 38 /** 39 @file jp2.h 40 @brief The JPEG-2000 file format Reader/Writer (JP2) 41 42 */ 43 44 /** @defgroup JP2 JP2 - JPEG-2000 file format reader/writer */ 45 /*@{*/ 46 47 /*#define JPIP_JPIP 0x6a706970*/ 48 49 #define JP2_JP 0x6a502020 /**< JPEG 2000 signature box */ 50 #define JP2_FTYP 0x66747970 /**< File type box */ 51 #define JP2_JP2H 0x6a703268 /**< JP2 header box (super-box) */ 52 #define JP2_IHDR 0x69686472 /**< Image header box */ 53 #define JP2_COLR 0x636f6c72 /**< Colour specification box */ 54 #define JP2_JP2C 0x6a703263 /**< Contiguous codestream box */ 55 #define JP2_URL 0x75726c20 /**< Data entry URL box */ 56 #define JP2_PCLR 0x70636c72 /**< Palette box */ 57 #define JP2_CMAP 0x636d6170 /**< Component Mapping box */ 58 #define JP2_CDEF 0x63646566 /**< Channel Definition box */ 59 #define JP2_DTBL 0x6474626c /**< Data Reference box */ 60 #define JP2_BPCC 0x62706363 /**< Bits per component box */ 61 #define JP2_JP2 0x6a703220 /**< File type fields */ 62 63 /* For the future */ 64 /* #define JP2_RES 0x72657320 */ /**< Resolution box (super-box) */ 65 /* #define JP2_JP2I 0x6a703269 */ /**< Intellectual property box */ 66 /* #define JP2_XML 0x786d6c20 */ /**< XML box */ 67 /* #define JP2_UUID 0x75756994 */ /**< UUID box */ 68 /* #define JP2_UINF 0x75696e66 */ /**< UUID info box (super-box) */ 69 /* #define JP2_ULST 0x756c7374 */ /**< UUID list box */ 70 71 /* ----------------------------------------------------------------------- */ 72 73 typedef enum { 74 JP2_STATE_NONE = 0x0, 75 JP2_STATE_SIGNATURE = 0x1, 76 JP2_STATE_FILE_TYPE = 0x2, 77 JP2_STATE_HEADER = 0x4, 78 JP2_STATE_CODESTREAM = 0x8, 79 JP2_STATE_END_CODESTREAM = 0x10, 80 JP2_STATE_UNKNOWN = 0x7fffffff /* ISO C restricts enumerator values to range of 'int' */ 81 } 82 JP2_STATE; 83 84 typedef enum { 85 JP2_IMG_STATE_NONE = 0x0, 86 JP2_IMG_STATE_UNKNOWN = 0x7fffffff 87 } 88 JP2_IMG_STATE; 89 90 /** 91 Channel description: channel index, type, association 92 */ 93 typedef struct opj_jp2_cdef_info { 94 OPJ_UINT16 cn, typ, asoc; 95 } opj_jp2_cdef_info_t; 96 97 /** 98 Channel descriptions and number of descriptions 99 */ 100 typedef struct opj_jp2_cdef { 101 opj_jp2_cdef_info_t *info; 102 OPJ_UINT16 n; 103 } opj_jp2_cdef_t; 104 105 /** 106 Component mappings: channel index, mapping type, palette index 107 */ 108 typedef struct opj_jp2_cmap_comp { 109 OPJ_UINT16 cmp; 110 OPJ_BYTE mtyp, pcol; 111 } opj_jp2_cmap_comp_t; 112 113 /** 114 Palette data: table entries, palette columns 115 */ 116 typedef struct opj_jp2_pclr { 117 OPJ_UINT32 *entries; 118 OPJ_BYTE *channel_sign; 119 OPJ_BYTE *channel_size; 120 opj_jp2_cmap_comp_t *cmap; 121 OPJ_UINT16 nr_entries; 122 OPJ_BYTE nr_channels; 123 } opj_jp2_pclr_t; 124 125 /** 126 Collector for ICC profile, palette, component mapping, channel description 127 */ 128 typedef struct opj_jp2_color { 129 OPJ_BYTE *icc_profile_buf; 130 OPJ_UINT32 icc_profile_len; 131 132 opj_jp2_cdef_t *jp2_cdef; 133 opj_jp2_pclr_t *jp2_pclr; 134 OPJ_BYTE jp2_has_colr; 135 } opj_jp2_color_t; 136 137 /** 138 JP2 component 139 */ 140 typedef struct opj_jp2_comps { 141 OPJ_UINT32 depth; 142 OPJ_UINT32 sgnd; 143 OPJ_UINT32 bpcc; 144 } opj_jp2_comps_t; 145 146 /** 147 JPEG-2000 file format reader/writer 148 */ 149 typedef struct opj_jp2 { 150 /** handle to the J2K codec */ 151 opj_j2k_t *j2k; 152 /** list of validation procedures */ 153 struct opj_procedure_list * m_validation_list; 154 /** list of execution procedures */ 155 struct opj_procedure_list * m_procedure_list; 156 157 /* width of image */ 158 OPJ_UINT32 w; 159 /* height of image */ 160 OPJ_UINT32 h; 161 /* number of components in the image */ 162 OPJ_UINT32 numcomps; 163 OPJ_UINT32 bpc; 164 OPJ_UINT32 C; 165 OPJ_UINT32 UnkC; 166 OPJ_UINT32 IPR; 167 OPJ_UINT32 meth; 168 OPJ_UINT32 approx; 169 OPJ_UINT32 enumcs; 170 OPJ_UINT32 precedence; 171 OPJ_UINT32 brand; 172 OPJ_UINT32 minversion; 173 OPJ_UINT32 numcl; 174 OPJ_UINT32 *cl; 175 opj_jp2_comps_t *comps; 176 /* FIXME: The following two variables are used to save offset 177 as we write out a JP2 file to disk. This mechanism is not flexible 178 as codec writers will need to extand those fields as new part 179 of the standard are implemented. 180 */ 181 OPJ_OFF_T j2k_codestream_offset; 182 OPJ_OFF_T jpip_iptr_offset; 183 OPJ_BOOL jpip_on; 184 OPJ_UINT32 jp2_state; 185 OPJ_UINT32 jp2_img_state; 186 187 opj_jp2_color_t color; 188 189 OPJ_BOOL ignore_pclr_cmap_cdef; 190 OPJ_BYTE has_jp2h; 191 OPJ_BYTE has_ihdr; 192 } 193 opj_jp2_t; 194 195 /** 196 JP2 Box 197 */ 198 typedef struct opj_jp2_box { 199 OPJ_UINT32 length; 200 OPJ_UINT32 type; 201 OPJ_INT32 init_pos; 202 } opj_jp2_box_t; 203 204 typedef struct opj_jp2_header_handler { 205 /* marker value */ 206 OPJ_UINT32 id; 207 /* action linked to the marker */ 208 OPJ_BOOL(*handler)(opj_jp2_t *jp2, 209 OPJ_BYTE *p_header_data, 210 OPJ_UINT32 p_header_size, 211 opj_event_mgr_t * p_manager); 212 } 213 opj_jp2_header_handler_t; 214 215 216 typedef struct opj_jp2_img_header_writer_handler { 217 /* action to perform */ 218 OPJ_BYTE* (*handler)(opj_jp2_t *jp2, OPJ_UINT32 * p_data_size); 219 /* result of the action : data */ 220 OPJ_BYTE* m_data; 221 /* size of data */ 222 OPJ_UINT32 m_size; 223 } 224 opj_jp2_img_header_writer_handler_t; 225 226 /** @name Exported functions */ 227 /*@{*/ 228 /* ----------------------------------------------------------------------- */ 229 230 /** 231 Setup the decoder decoding parameters using user parameters. 232 Decoding parameters are returned in jp2->j2k->cp. 233 @param p_jp2 JP2 decompressor handle 234 @param parameters decompression parameters 235 */ 236 void opj_jp2_setup_decoder(void *p_jp2, opj_dparameters_t *parameters); 237 238 /** 239 Set the strict mode parameter. When strict mode is enabled, the entire 240 bitstream must be decoded or an error is returned. When it is disabled, 241 the decoder will decode partial bitstreams. 242 @param p_jp2 JP2 decompressor handle 243 @param strict OPJ_TRUE for strict mode 244 */ 245 void opj_jp2_decoder_set_strict_mode(void *p_jp2, OPJ_BOOL strict); 246 247 /** Allocates worker threads for the compressor/decompressor. 248 * 249 * @param p_jp2 JP2 decompressor handle 250 * @param num_threads Number of threads. 251 * @return OPJ_TRUE in case of success. 252 */ 253 OPJ_BOOL opj_jp2_set_threads(void *p_jp2, OPJ_UINT32 num_threads); 254 255 /** 256 * Decode an image from a JPEG-2000 file stream 257 * @param p_jp2 JP2 decompressor handle 258 * @param p_stream FIXME DOC 259 * @param p_image FIXME DOC 260 * @param p_manager FIXME DOC 261 * 262 * @return Returns a decoded image if successful, returns NULL otherwise 263 */ 264 OPJ_BOOL opj_jp2_decode(void *p_jp2, 265 opj_stream_private_t *p_stream, 266 opj_image_t* p_image, 267 opj_event_mgr_t * p_manager); 268 269 /** 270 * Setup the encoder parameters using the current image and using user parameters. 271 * Coding parameters are returned in jp2->j2k->cp. 272 * 273 * @param p_jp2 JP2 compressor handle 274 * @param parameters compression parameters 275 * @param image input filled image 276 * @param p_manager FIXME DOC 277 * @return OPJ_TRUE if successful, OPJ_FALSE otherwise 278 */ 279 OPJ_BOOL opj_jp2_setup_encoder(void *p_jp2, 280 opj_cparameters_t *parameters, 281 opj_image_t *image, 282 opj_event_mgr_t * p_manager); 283 284 /** 285 Encode an image into a JPEG-2000 file stream 286 @param p_jp2 JP2 compressor handle 287 @param stream Output buffer stream 288 @param p_manager event manager 289 @return Returns true if successful, returns false otherwise 290 */ 291 OPJ_BOOL opj_jp2_encode(void *p_jp2, 292 opj_stream_private_t *stream, 293 opj_event_mgr_t * p_manager); 294 295 296 /** 297 * Starts a compression scheme, i.e. validates the codec parameters, writes the header. 298 * 299 * @param p_jp2 the jpeg2000 file codec. 300 * @param stream the stream object. 301 * @param p_image FIXME DOC 302 * @param p_manager FIXME DOC 303 * 304 * @return true if the codec is valid. 305 */ 306 OPJ_BOOL opj_jp2_start_compress(void *p_jp2, 307 opj_stream_private_t *stream, 308 opj_image_t * p_image, 309 opj_event_mgr_t * p_manager); 310 311 312 /** 313 * Ends the compression procedures and possibiliy add data to be read after the 314 * codestream. 315 */ 316 OPJ_BOOL opj_jp2_end_compress(void *p_jp2, 317 opj_stream_private_t *cio, 318 opj_event_mgr_t * p_manager); 319 320 /* ----------------------------------------------------------------------- */ 321 322 /** 323 * Ends the decompression procedures and possibiliy add data to be read after the 324 * codestream. 325 */ 326 OPJ_BOOL opj_jp2_end_decompress(void *p_jp2, 327 opj_stream_private_t *cio, 328 opj_event_mgr_t * p_manager); 329 330 /** 331 * Reads a jpeg2000 file header structure. 332 * 333 * @param p_stream the stream to read data from. 334 * @param p_jp2 the jpeg2000 file header structure. 335 * @param p_image FIXME DOC 336 * @param p_manager the user event manager. 337 * 338 * @return true if the box is valid. 339 */ 340 OPJ_BOOL opj_jp2_read_header(opj_stream_private_t *p_stream, 341 void *p_jp2, 342 opj_image_t ** p_image, 343 opj_event_mgr_t * p_manager); 344 345 /** Sets the indices of the components to decode. 346 * 347 * @param p_jp2 JP2 decompressor handle 348 * @param numcomps Number of components to decode. 349 * @param comps_indices Array of num_compts indices (numbering starting at 0) 350 * corresponding to the components to decode. 351 * @param p_manager Event manager; 352 * 353 * @return OPJ_TRUE in case of success. 354 */ 355 OPJ_BOOL opj_jp2_set_decoded_components(void *p_jp2, 356 OPJ_UINT32 numcomps, 357 const OPJ_UINT32* comps_indices, 358 opj_event_mgr_t * p_manager); 359 360 /** 361 * Reads a tile header. 362 * @param p_jp2 the jpeg2000 codec. 363 * @param p_tile_index FIXME DOC 364 * @param p_data_size FIXME DOC 365 * @param p_tile_x0 FIXME DOC 366 * @param p_tile_y0 FIXME DOC 367 * @param p_tile_x1 FIXME DOC 368 * @param p_tile_y1 FIXME DOC 369 * @param p_nb_comps FIXME DOC 370 * @param p_go_on FIXME DOC 371 * @param p_stream the stream to write data to. 372 * @param p_manager the user event manager. 373 */ 374 OPJ_BOOL opj_jp2_read_tile_header(void * p_jp2, 375 OPJ_UINT32 * p_tile_index, 376 OPJ_UINT32 * p_data_size, 377 OPJ_INT32 * p_tile_x0, 378 OPJ_INT32 * p_tile_y0, 379 OPJ_INT32 * p_tile_x1, 380 OPJ_INT32 * p_tile_y1, 381 OPJ_UINT32 * p_nb_comps, 382 OPJ_BOOL * p_go_on, 383 opj_stream_private_t *p_stream, 384 opj_event_mgr_t * p_manager); 385 386 /** 387 * Writes a tile. 388 * 389 * @param p_jp2 the jpeg2000 codec. 390 * @param p_tile_index FIXME DOC 391 * @param p_data FIXME DOC 392 * @param p_data_size FIXME DOC 393 * @param p_stream the stream to write data to. 394 * @param p_manager the user event manager. 395 */ 396 OPJ_BOOL opj_jp2_write_tile(void *p_jp2, 397 OPJ_UINT32 p_tile_index, 398 OPJ_BYTE * p_data, 399 OPJ_UINT32 p_data_size, 400 opj_stream_private_t *p_stream, 401 opj_event_mgr_t * p_manager); 402 403 /** 404 * Decode tile data. 405 * @param p_jp2 the jpeg2000 codec. 406 * @param p_tile_index FIXME DOC 407 * @param p_data FIXME DOC 408 * @param p_data_size FIXME DOC 409 * @param p_stream the stream to write data to. 410 * @param p_manager the user event manager. 411 * 412 * @return FIXME DOC 413 */ 414 OPJ_BOOL opj_jp2_decode_tile(void * p_jp2, 415 OPJ_UINT32 p_tile_index, 416 OPJ_BYTE * p_data, 417 OPJ_UINT32 p_data_size, 418 opj_stream_private_t *p_stream, 419 opj_event_mgr_t * p_manager); 420 421 /** 422 * Creates a jpeg2000 file decompressor. 423 * 424 * @return an empty jpeg2000 file codec. 425 */ 426 opj_jp2_t* opj_jp2_create(OPJ_BOOL p_is_decoder); 427 428 /** 429 Destroy a JP2 decompressor handle 430 @param p_jp2 JP2 decompressor handle to destroy 431 */ 432 void opj_jp2_destroy(void *p_jp2); 433 434 435 /** 436 * Sets the given area to be decoded. This function should be called right after opj_read_header and before any tile header reading. 437 * 438 * @param p_jp2 the jpeg2000 codec. 439 * @param p_image FIXME DOC 440 * @param p_start_x the left position of the rectangle to decode (in image coordinates). 441 * @param p_start_y the up position of the rectangle to decode (in image coordinates). 442 * @param p_end_x the right position of the rectangle to decode (in image coordinates). 443 * @param p_end_y the bottom position of the rectangle to decode (in image coordinates). 444 * @param p_manager the user event manager 445 * 446 * @return true if the area could be set. 447 */ 448 OPJ_BOOL opj_jp2_set_decode_area(void *p_jp2, 449 opj_image_t* p_image, 450 OPJ_INT32 p_start_x, OPJ_INT32 p_start_y, 451 OPJ_INT32 p_end_x, OPJ_INT32 p_end_y, 452 opj_event_mgr_t * p_manager); 453 454 /** 455 * 456 */ 457 OPJ_BOOL opj_jp2_get_tile(void *jp2, 458 opj_stream_private_t *p_stream, 459 opj_image_t* p_image, 460 opj_event_mgr_t * p_manager, 461 OPJ_UINT32 tile_index); 462 463 464 /** 465 * 466 */ 467 OPJ_BOOL opj_jp2_set_decoded_resolution_factor(void *p_jp2, 468 OPJ_UINT32 res_factor, 469 opj_event_mgr_t * p_manager); 470 471 /** 472 * Specify extra options for the encoder. 473 * 474 * @param p_jp2 the jpeg2000 codec. 475 * @param p_options options 476 * @param p_manager the user event manager 477 * 478 * @see opj_encoder_set_extra_options() for more details. 479 */ 480 OPJ_BOOL opj_jp2_encoder_set_extra_options( 481 void *p_jp2, 482 const char* const* p_options, 483 opj_event_mgr_t * p_manager); 484 485 486 /* TODO MSD: clean these 3 functions */ 487 /** 488 * Dump some elements from the JP2 decompression structure . 489 * 490 *@param p_jp2 the jp2 codec. 491 *@param flag flag to describe what elements are dump. 492 *@param out_stream output stream where dump the elements. 493 * 494 */ 495 void jp2_dump(void* p_jp2, OPJ_INT32 flag, FILE* out_stream); 496 497 /** 498 * Get the codestream info from a JPEG2000 codec. 499 * 500 *@param p_jp2 jp2 codec. 501 * 502 *@return the codestream information extract from the jpg2000 codec 503 */ 504 opj_codestream_info_v2_t* jp2_get_cstr_info(void* p_jp2); 505 506 /** 507 * Get the codestream index from a JPEG2000 codec. 508 * 509 *@param p_jp2 jp2 codec. 510 * 511 *@return the codestream index extract from the jpg2000 codec 512 */ 513 opj_codestream_index_t* jp2_get_cstr_index(void* p_jp2); 514 515 516 /*@}*/ 517 518 /*@}*/ 519 520 #endif /* OPJ_JP2_H */ 521 522