From c7489af844d0ffd81ad704df03c81a0d8bffbf8e Mon Sep 17 00:00:00 2001 From: Mickael Savinaud Date: Tue, 8 Nov 2011 13:09:53 +0000 Subject: [PATCH] [trunk] WIP: clean and enhance openjpeg.h and add deprecated macro --- CHANGES | 3 + libopenjpeg/openjpeg.h | 365 ++++++++++++++++++++++------------------- 2 files changed, 200 insertions(+), 168 deletions(-) diff --git a/CHANGES b/CHANGES index 1a120234..24212cee 100644 --- a/CHANGES +++ b/CHANGES @@ -5,6 +5,9 @@ What's New for OpenJPEG ! : changed + : added +November 8, 2011 ++ [mickael] WIP: clean and enhance openjpeg.h and add deprecated macro + October 25, 2011 + [mickael] WIP: add a file to exclude some valgrind errors (detected with ctest_memcheck) related to png lib found with ubuntu10.04 platform * [mickael] WIP: solve problems with reading of elements outside the tilec->data buffer in dwt diff --git a/libopenjpeg/openjpeg.h b/libopenjpeg/openjpeg.h index 095ab249..0ac208f1 100644 --- a/libopenjpeg/openjpeg.h +++ b/libopenjpeg/openjpeg.h @@ -6,6 +6,7 @@ * Copyright (c) 2003-2007, Francois-Olivier Devaux and Antonin Descampe * Copyright (c) 2005, Herve Drolon, FreeImage Team * Copyright (c) 2006-2007, Parvatha Elangovan + * Copyright (c) 2008, Jerome Fimes, Communications & Systemes * Copyright (c) 2010-2011, Kaori Hagihara * Copyright (c) 2011, Mickael Savinaud, Communications & Systemes * All rights reserved. @@ -41,6 +42,16 @@ ========================================================== */ +/* deprecated attribute */ +#ifdef __GNUC__ + #define DEPRECATED(func) func __attribute__ ((deprecated)) +#elif defined(_MSC_VER) + #define DEPRECATED(func) __declspec(deprecated) func +#else + #pragma message("WARNING: You need to implement DEPRECATED for this compiler") + #define DEPRECATED(func) func +#endif + #if defined(OPJ_STATIC) || !defined(_WIN32) #define OPJ_API #define OPJ_CALLCONV @@ -61,7 +72,7 @@ defined with this macro as being exported. #endif /* OPJ_EXPORTS */ #endif /* !OPJ_STATIC || !_WIN32 */ -typedef int opj_bool; /*FIXME -> OPJ_BOOL*/ +typedef int opj_bool; /*FIXME it should be to follow the name of others OPJ_TYPE -> OPJ_BOOL*/ #define OPJ_TRUE 1 #define OPJ_FALSE 0 @@ -107,7 +118,8 @@ typedef float OPJ_FLOAT32; /* < -
  • Error messages -
  • Warning messages -
  • Debugging messages - -*/ + * Message handler object used for + *
      + *
    • Error messages + *
    • Warning messages + *
    • Debugging messages + *
    + * */ typedef struct opj_event_mgr { /** FIXME DOC */ void* client_data; @@ -230,8 +239,8 @@ typedef struct opj_event_mgr { */ /** -Progression order changes -*/ + * Progression order changes + * */ typedef struct opj_poc { /** Resolution num start, Component num start, given by POC */ OPJ_UINT32 resno0, compno0; @@ -258,8 +267,8 @@ typedef struct opj_poc { } opj_poc_t; /** -Compression parameters -*/ + * Compression parameters + * */ typedef struct opj_cparameters { /** size of tile: tile_size_on = false (not in argument) or = true (in argument) */ opj_bool tile_size_on; @@ -389,8 +398,8 @@ typedef struct opj_cparameters { } opj_cparameters_t; /** -Decompression parameters -*/ + * Decompression parameters + * */ typedef struct opj_dparameters { /** Set the number of highest resolution levels to be discarded. @@ -454,6 +463,8 @@ typedef struct opj_dparameters { } opj_dparameters_t; + +/* ---> FIXME V1 style */ /** Common fields between JPEG-2000 compression and decompression master structs. */ #define opj_common_fields \ @@ -480,8 +491,8 @@ typedef struct opj_common_struct { typedef opj_common_struct_t * opj_common_ptr; /** -Compression context info -*/ + * Compression context info + * */ typedef struct opj_cinfo { /** Fields shared with opj_dinfo_t */ opj_common_fields; @@ -489,17 +500,19 @@ typedef struct opj_cinfo { } opj_cinfo_t; /** -Decompression context info -*/ + * Decompression context info + * */ typedef struct opj_dinfo { /** Fields shared with opj_cinfo_t */ opj_common_fields; /* other specific fields go here */ } opj_dinfo_t; +/* <--- V1 style */ + /** - * JPEG2000 codec. - */ + * JPEG2000 codec V2. + * */ typedef void * opj_codec_t; /* @@ -559,8 +572,8 @@ typedef void * opj_stream_t; */ /** -Defines a single image component -*/ + * Defines a single image component + * */ typedef struct opj_image_comp { /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */ OPJ_UINT32 dx; @@ -589,8 +602,8 @@ typedef struct opj_image_comp { } opj_image_comp_t; /** -Defines image data and characteristics -*/ + * Defines image data and characteristics + * */ typedef struct opj_image { /** XOsiz: horizontal offset from the origin of the reference grid to the left side of the image area */ OPJ_UINT32 x0; @@ -614,8 +627,8 @@ typedef struct opj_image { /** -Component parameters structure used by the opj_image_create function -*/ + * Component parameters structure used by the opj_image_create function + * */ typedef struct opj_image_comptparm { /** XRsiz: horizontal separation of a sample of ith component with respect to the reference grid */ int dx; @@ -638,9 +651,6 @@ typedef struct opj_image_comptparm { } opj_image_cmptparm_t; - - - /* ========================================================== Information on the JPEG 2000 codestream @@ -648,8 +658,8 @@ typedef struct opj_image_comptparm { */ /** -Index structure : Information concerning a packet inside tile -*/ + * Index structure : Information concerning a packet inside tile + * */ typedef struct opj_packet_info { /** packet start position (including SOP marker if it exists) */ int start_pos; @@ -664,8 +674,8 @@ typedef struct opj_packet_info { /* UniPG>> */ /** -Marker structure -*/ + * Marker structure + * */ typedef struct opj_marker_info_t { /** marker type */ unsigned short int type; @@ -677,7 +687,7 @@ typedef struct opj_marker_info_t { /* <cp. @param dinfo decompressor handle @param parameters decompression parameters */ -OPJ_API void OPJ_CALLCONV opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters); +DEPRECATED( OPJ_API void OPJ_CALLCONV opj_setup_decoder(opj_dinfo_t *dinfo, opj_dparameters_t *parameters) ); /** @@ -1205,13 +1222,104 @@ OPJ_API opj_bool OPJ_CALLCONV opj_setup_decoder_v2( opj_codec_t *p_info, opj_dparameters_t *parameters, opj_event_mgr_t* event_mgr); +/** + * Decodes an image header. + * + * @param p_cio the jpeg2000 stream. + * @param p_codec the jpeg2000 codec to read. + * @param p_image the image structure initialized with the characteristics of encoded image. + * + * @return true if the main header of the codestream and the JP2 header is correctly read. + */ +OPJ_API opj_bool OPJ_CALLCONV opj_read_header ( opj_stream_t *p_cio, + opj_codec_t *p_codec, + opj_image_t **p_image); + +/** + * Sets the given area to be decoded. This function should be called right after opj_read_header and before any tile header reading. + * + * @param p_codec the jpeg2000 codec. + * @param p_start_x the left position of the rectangle to decode (in image coordinates). + * @param p_end_x the right position of the rectangle to decode (in image coordinates). + * @param p_start_y the up position of the rectangle to decode (in image coordinates). + * @param p_end_y the bottom position of the rectangle to decode (in image coordinates). + * + * @return true if the area could be set. + */ +OPJ_API opj_bool OPJ_CALLCONV opj_set_decode_area( opj_codec_t *p_codec, + opj_image_t* p_image, + OPJ_INT32 p_start_x, OPJ_INT32 p_start_y, + OPJ_INT32 p_end_x, OPJ_INT32 p_end_y ); + /** Decode an image from a JPEG-2000 codestream @param dinfo decompressor handle @param cio Input buffer stream @return Returns a decoded image if successful, returns NULL otherwise */ -OPJ_API opj_image_t* OPJ_CALLCONV opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio); +DEPRECATED( OPJ_API opj_image_t* OPJ_CALLCONV opj_decode(opj_dinfo_t *dinfo, opj_cio_t *cio) ); + +/** + * Decode an image from a JPEG-2000 codestream + * @param dinfo decompressor handle + * @param cio Input buffer stream + * @return Returns a decoded image if successful, returns NULL otherwise + * */ +OPJ_API opj_bool OPJ_CALLCONV opj_decode_v2(opj_codec_t *p_decompressor, + opj_stream_t * cio, + opj_image_t *p_image); + + + +/** + * Reads a tile header. This function is compulsory and allows one to know the size of the tile thta will be decoded. + * The user may need to refer to the image got by opj_read_header to understand the size being taken by the tile. + * + * @param p_codec the jpeg2000 codec. + * @param p_tile_index pointer to a value that will hold the index of the tile being decoded, in case of success. + * @param p_data_size pointer to a value that will hold the maximum size of the decoded data, in case of success. In case + * of truncated codestreams, the actual number of bytes decoded may be lower. The computation of the size is the same + * as depicted in opj_write_tile. + * @param p_tile_x0 pointer to a value that will hold the x0 pos of the tile (in the image). + * @param p_tile_y0 pointer to a value that will hold the y0 pos of the tile (in the image). + * @param p_tile_x1 pointer to a value that will hold the x1 pos of the tile (in the image). + * @param p_tile_y1 pointer to a value that will hold the y1 pos of the tile (in the image). + * @param p_nb_comps pointer to a value that will hold the number of components in the tile. + * @param p_should_go_on pointer to a boolean that will hold the fact that the decoding should go on. In case the + * codestream is over at the time of the call, the value will be set to false. The user should then stop + * the decoding. + * @param p_stream the stream to decode. + * @return true if the tile header could be decoded. In case the decoding should end, the returned value is still true. + * returning false may be the result of a shortage of memory or an internal error. + */ +OPJ_API opj_bool OPJ_CALLCONV opj_read_tile_header( opj_codec_t *p_codec, + opj_stream_t * p_stream, + OPJ_UINT32 * p_tile_index, + OPJ_UINT32 * p_data_size, + OPJ_INT32 * p_tile_x0, OPJ_INT32 * p_tile_y0, + OPJ_INT32 * p_tile_x1, OPJ_INT32 * p_tile_y1, + OPJ_UINT32 * p_nb_comps, + opj_bool * p_should_go_on ); + + +/** + * Reads a tile data. This function is compulsory and allows one to decode tile data. opj_read_tile_header should be called before. + * The user may need to refer to the image got by opj_read_header to understand the size being taken by the tile. + * + * @param p_codec the jpeg2000 codec. + * @param p_tile_index the index of the tile being decoded, this should be the value set by opj_read_tile_header. + * @param p_data pointer to a memory block that will hold the decoded data. + * @param p_data_size size of p_data. p_data_size should be bigger or equal to the value set by opj_read_tile_header. + * @param p_stream the stream to decode. + * + * @return true if the data could be decoded. + */ +OPJ_API opj_bool OPJ_CALLCONV opj_decode_tile_data( opj_codec_t *p_codec, + OPJ_UINT32 p_tile_index, + OPJ_BYTE * p_data, + OPJ_UINT32 p_data_size, + opj_stream_t *p_stream ); + /** Decode an image from a JPEG-2000 codestream and extract the codestream information @@ -1220,7 +1328,10 @@ Decode an image from a JPEG-2000 codestream and extract the codestream informati @param cstr_info Codestream information structure if needed afterwards, NULL otherwise @return Returns a decoded image if successful, returns NULL otherwise */ -OPJ_API opj_image_t* OPJ_CALLCONV opj_decode_with_info(opj_dinfo_t *dinfo, opj_cio_t *cio, opj_codestream_info_t *cstr_info); +DEPRECATED( OPJ_API opj_image_t* OPJ_CALLCONV opj_decode_with_info(opj_dinfo_t *dinfo, opj_cio_t *cio, opj_codestream_info_t *cstr_info) ); + +/* COMPRESSION FUNCTIONS*/ + /** Creates a J2K/JP2 compression structure @param format Coder to select @@ -1279,6 +1390,10 @@ Encode an image into a JPEG-2000 codestream and extract the codestream informati @return Returns true if successful, returns false otherwise */ OPJ_API opj_bool OPJ_CALLCONV opj_encode_with_info(opj_cinfo_t *cinfo, opj_cio_t *cio, opj_image_t *image, opj_codestream_info_t *cstr_info); + + + + /** Destroy Codestream information after compression or decompression @param cstr_info Codestream information structure @@ -1287,18 +1402,7 @@ OPJ_API void OPJ_CALLCONV opj_destroy_cstr_info(opj_codestream_info_t *cstr_info OPJ_API void OPJ_CALLCONV opj_destroy_cstr_info_v2(opj_codestream_info_v2_t **cstr_info); -/** - * Decodes an image header. - * - * @param p_cio the jpeg2000 stream. - * @param p_codec the jpeg2000 codec to read. - * @param p_image the image structure initialized with the characteristics of encoded image. - * - * @return true if the main header of the codestream and the JP2 header is correctly read. - */ -OPJ_API opj_bool OPJ_CALLCONV opj_read_header ( opj_stream_t *p_cio, - opj_codec_t *p_codec, - opj_image_t **p_image); + /** * Destroy a decompressor handle @@ -1307,70 +1411,7 @@ OPJ_API opj_bool OPJ_CALLCONV opj_read_header ( opj_stream_t *p_cio, */ OPJ_API void OPJ_CALLCONV opj_destroy_codec(opj_codec_t * p_codec); -/** - * Sets the given area to be decoded. This function should be called right after opj_read_header and before any tile header reading. - * - * @param p_codec the jpeg2000 codec. - * @param p_start_x the left position of the rectangle to decode (in image coordinates). - * @param p_end_x the right position of the rectangle to decode (in image coordinates). - * @param p_start_y the up position of the rectangle to decode (in image coordinates). - * @param p_end_y the bottom position of the rectangle to decode (in image coordinates). - * - * @return true if the area could be set. - */ -OPJ_API opj_bool OPJ_CALLCONV opj_set_decode_area( opj_codec_t *p_codec, - opj_image_t* p_image, - OPJ_INT32 p_start_x, OPJ_INT32 p_start_y, - OPJ_INT32 p_end_x, OPJ_INT32 p_end_y ); -/** - * Reads a tile header. This function is compulsory and allows one to know the size of the tile thta will be decoded. - * The user may need to refer to the image got by opj_read_header to understand the size being taken by the tile. - * - * @param p_codec the jpeg2000 codec. - * @param p_tile_index pointer to a value that will hold the index of the tile being decoded, in case of success. - * @param p_data_size pointer to a value that will hold the maximum size of the decoded data, in case of success. In case - * of truncated codestreams, the actual number of bytes decoded may be lower. The computation of the size is the same - * as depicted in opj_write_tile. - * @param p_tile_x0 pointer to a value that will hold the x0 pos of the tile (in the image). - * @param p_tile_y0 pointer to a value that will hold the y0 pos of the tile (in the image). - * @param p_tile_x1 pointer to a value that will hold the x1 pos of the tile (in the image). - * @param p_tile_y1 pointer to a value that will hold the y1 pos of the tile (in the image). - * @param p_nb_comps pointer to a value that will hold the number of components in the tile. - * @param p_should_go_on pointer to a boolean that will hold the fact that the decoding should go on. In case the - * codestream is over at the time of the call, the value will be set to false. The user should then stop - * the decoding. - * @param p_stream the stream to decode. - * @return true if the tile header could be decoded. In case the decoding should end, the returned value is still true. - * returning false may be the result of a shortage of memory or an internal error. - */ -OPJ_API opj_bool OPJ_CALLCONV opj_read_tile_header( opj_codec_t *p_codec, - opj_stream_t * p_stream, - OPJ_UINT32 * p_tile_index, - OPJ_UINT32 * p_data_size, - OPJ_INT32 * p_tile_x0, OPJ_INT32 * p_tile_y0, - OPJ_INT32 * p_tile_x1, OPJ_INT32 * p_tile_y1, - OPJ_UINT32 * p_nb_comps, - opj_bool * p_should_go_on ); - - -/** - * Reads a tile data. This function is compulsory and allows one to decode tile data. opj_read_tile_header should be called before. - * The user may need to refer to the image got by opj_read_header to understand the size being taken by the tile. - * - * @param p_codec the jpeg2000 codec. - * @param p_tile_index the index of the tile being decoded, this should be the value set by opj_read_tile_header. - * @param p_data pointer to a memory block that will hold the decoded data. - * @param p_data_size size of p_data. p_data_size should be bigger or equal to the value set by opj_read_tile_header. - * @param p_stream the stream to decode. - * - * @return true if the data could be decoded. - */ -OPJ_API opj_bool OPJ_CALLCONV opj_decode_tile_data( opj_codec_t *p_codec, - OPJ_UINT32 p_tile_index, - OPJ_BYTE * p_data, - OPJ_UINT32 p_data_size, - opj_stream_t *p_stream ); /* @@ -1434,18 +1475,6 @@ OPJ_API opj_jp2_metadata_t* OPJ_CALLCONV opj_get_jp2_metadata(opj_codec_t *p_cod */ OPJ_API opj_jp2_index_t* OPJ_CALLCONV opj_get_jp2_index(opj_codec_t *p_codec); -/** -Decode an image from a JPEG-2000 codestream -@param dinfo decompressor handle -@param cio Input buffer stream -@return Returns a decoded image if successful, returns NULL otherwise -*/ -OPJ_API opj_bool OPJ_CALLCONV opj_decode_v2(opj_codec_t *p_decompressor, - opj_stream_t * cio, - opj_image_t *p_image); - -OPJ_API opj_bool OPJ_CALLCONV opj_end_decompress ( opj_codec_t *p_codec, - opj_stream_t *p_cio); #ifdef __cplusplus