From ce297bfa9e97ffa0c35ffdf886be7b133c965d6a Mon Sep 17 00:00:00 2001 From: Mickael Savinaud Date: Thu, 15 Nov 2012 14:22:13 +0000 Subject: [PATCH] runk] fix the documentation of the API --- src/lib/openjp2/openjpeg.h | 97 ++++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 46 deletions(-) diff --git a/src/lib/openjp2/openjpeg.h b/src/lib/openjp2/openjpeg.h index 6ef5f430..e85e72fa 100644 --- a/src/lib/openjp2/openjpeg.h +++ b/src/lib/openjp2/openjpeg.h @@ -119,7 +119,7 @@ typedef uint64_t OPJ_UINT64; #define OPJ_J2K_MCC_DEFAULT_NB_RECORDS 10 #define OPJ_J2K_MCT_DEFAULT_NB_RECORDS 10 -/* UniPG>> */ +/* UniPG>> */ /* NOT YET USED IN THE V2 VERSION OF OPENJPEG */ #define JPWL_MAX_NO_TILESPECS 16 /**< Maximum number of tile parts expected by JPWL: increase at your will */ #define JPWL_MAX_NO_PACKSPECS 16 /**< Maximum number of packet parts expected by JPWL: increase at your will */ #define JPWL_MAX_NO_MARKERS 512 /**< Maximum number of JPWL markers: increase at your will */ @@ -131,8 +131,8 @@ typedef uint64_t OPJ_UINT64; /* <> */ +/* UniPG>> */ /* NOT YET USED IN THE V2 VERSION OF OPENJPEG */ /**@name JPWL encoding parameters */ /*@{*/ /** enables writing of EPC in MH, thus activating JPWL */ @@ -436,7 +436,7 @@ typedef struct opj_dparameters { /*@}*/ -/* UniPG>> */ +/* UniPG>> */ /* NOT YET USED IN THE V2 VERSION OF OPENJPEG */ /**@name JPWL decoding parameters */ /*@{*/ /** activates the JPWL correction capabilities */ @@ -466,9 +466,9 @@ typedef void * opj_codec_t; ========================================================== */ -/* +/** * Stream open flags. - */ + * */ /** The stream was opened for reading. */ #define OPJ_STREAM_READ OPJ_TRUE /** The stream was opened for writing. */ @@ -476,25 +476,21 @@ typedef void * opj_codec_t; /* * Callback function prototype for read function - * FIXME DOC */ typedef OPJ_SIZE_T (* opj_stream_read_fn) (void * p_buffer, OPJ_SIZE_T p_nb_bytes, void * p_user_data) ; /* * Callback function prototype for write function - * FIXME DOC */ typedef OPJ_SIZE_T (* opj_stream_write_fn) (void * p_buffer, OPJ_SIZE_T p_nb_bytes, void * p_user_data) ; /* * Callback function prototype for skip function - * FIXME DOC */ typedef OPJ_OFF_T (* opj_stream_skip_fn) (OPJ_OFF_T p_nb_bytes, void * p_user_data) ; /* * Callback function prototype for seek function - * FIXME DOC */ typedef OPJ_BOOL (* opj_stream_seek_fn) (OPJ_OFF_T p_nb_bytes, void * p_user_data) ; @@ -594,6 +590,7 @@ typedef struct opj_image_comptparm { Information on the JPEG 2000 codestream ========================================================== */ +/* QUITE EXPERIMENTAL FOR THE MOMENT */ /** * Index structure : Information concerning a packet inside tile @@ -851,7 +848,7 @@ typedef struct opj_tile_index { /** information concerning tile parts */ opj_tp_index_t *tp_index; - /* UniPG>> */ + /* UniPG>> */ /* NOT USED FOR THE MOMENT IN THE V2 VERSION */ /** number of markers */ OPJ_UINT32 marknum; /** list of markers */ @@ -879,7 +876,7 @@ typedef struct opj_codestream_index { /** codestream's size */ OPJ_UINT64 codestream_size; -/* UniPG>> */ +/* UniPG>> */ /* NOT USED FOR THE MOMENT IN THE V2 VERSION */ /** number of markers */ OPJ_UINT32 marknum; /** list of markers */ @@ -904,7 +901,7 @@ typedef struct opj_codestream_index { /** * Info structure of the JP2 file - * FIXME + * EXPERIMENTAL FOR THE MOMENT */ typedef struct opj_jp2_metadata { /** */ @@ -914,7 +911,7 @@ typedef struct opj_jp2_metadata { /** * Index structure of the JP2 file - * FIXME + * EXPERIMENTAL FOR THE MOMENT */ typedef struct opj_jp2_index { /** */ @@ -934,6 +931,7 @@ extern "C" { ========================================================== */ +/* Get the version of the openjpeg library*/ OPJ_API const char * OPJ_CALLCONV opj_version(void); /* @@ -944,32 +942,32 @@ OPJ_API const char * OPJ_CALLCONV opj_version(void); /** * Create an image - * @param numcmpts number of components - * @param cmptparms components parameters - * @param clrspc image color space - * @return returns a new image structure if successful, returns NULL otherwise + * + * @param numcmpts number of components + * @param cmptparms components parameters + * @param clrspc image color space + * @return returns a new image structure if successful, returns NULL otherwise * */ OPJ_API opj_image_t* OPJ_CALLCONV opj_image_create(OPJ_UINT32 numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc); /** * Deallocate any resources associated with an image - * @param image image to be destroyed + * + * @param image image to be destroyed */ OPJ_API void OPJ_CALLCONV opj_image_destroy(opj_image_t *image); - /** * Creates an image without allocating memory for the image (used in the new version of the library). * - * @param numcmpts the number of components - * @param cmptparms the components parameters - * @param clrspc the image color space + * @param numcmpts the number of components + * @param cmptparms the components parameters + * @param clrspc the image color space * * @return a new image structure if successful, NULL otherwise. */ OPJ_API opj_image_t* OPJ_CALLCONV opj_image_tile_create(OPJ_UINT32 numcmpts, opj_image_cmptparm_t *cmptparms, OPJ_COLOR_SPACE clrspc); - /* ========================================================== stream functions definitions @@ -1049,16 +1047,16 @@ OPJ_API void OPJ_CALLCONV opj_stream_set_user_data_length(opj_stream_t* p_stream /** * Helper function. * Sets the stream to be a file stream. The FILE must have been open previously. - * @param p_file the file stream to operate on - * @param p_is_read_stream whether the stream is a read stream (true) or not (false) + * @param p_file the file stream to operate on + * @param p_is_read_stream whether the stream is a read stream (true) or not (false) */ OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create_default_file_stream (FILE * p_file, OPJ_BOOL p_is_read_stream); /** * FIXME DOC - * @param p_file the file stream to operate on - * @param p_buffer_size FIXME DOC - * @param p_is_read_stream FIXME DOC + * @param p_file the file stream to operate on + * @param p_buffer_size size of the chunk used to stream + * @param p_is_read_stream whether the stream is a read stream (true) or not (false) */ OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create_file_stream (FILE * p_file, OPJ_SIZE_T p_buffer_size, OPJ_BOOL p_is_read_stream); @@ -1071,7 +1069,7 @@ OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create_file_stream (FILE * p_file, * Set the info handler use by openjpeg. * @param p_codec the codec previously initialise * @param p_callback the callback function which will be used - * @param p_user_data FIXME DOC + * @param p_user_data client object where will be returned the message */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_info_handler(opj_codec_t * p_codec, opj_msg_callback p_callback, @@ -1080,7 +1078,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_info_handler(opj_codec_t * p_codec, * Set the warning handler use by openjpeg. * @param p_codec the codec previously initialise * @param p_callback the callback function which will be used - * @param p_user_data FIXME DOC + * @param p_user_data client object where will be returned the message */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_warning_handler(opj_codec_t * p_codec, opj_msg_callback p_callback, @@ -1089,7 +1087,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_warning_handler(opj_codec_t * p_codec, * Set the error handler use by openjpeg. * @param p_codec the codec previously initialise * @param p_callback the callback function which will be used - * @param p_user_data FIXME DOC + * @param p_user_data client object where will be returned the message */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_error_handler(opj_codec_t * p_codec, opj_msg_callback p_callback, @@ -1160,7 +1158,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_read_header ( opj_stream_t *p_stream, * 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_image FIXME DOC + * @param p_image the decoded image previously setted by opj_read_header * @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). @@ -1175,6 +1173,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_decode_area( opj_codec_t *p_codec, /** * Decode an image from a JPEG-2000 codestream + * * @param p_decompressor decompressor handle * @param p_stream Input buffer stream * @param p_image the decoded image @@ -1186,6 +1185,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_decode( opj_codec_t *p_decompressor, /** * Get the decoded tile from the codec + * * @param p_codec the jpeg2000 codec. * @param p_stream input streamm * @param p_image output image @@ -1210,7 +1210,7 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_decoded_resolution_factor(opj_codec_t *p_c /** * Writes a tile with the given data. * - * @param p_codec the jpeg2000 codec. + * @param p_codec the jpeg2000 codec. * @param p_tile_index the index of the tile to write. At the moment, the tiles must be written from 0 to n-1 in sequence. * @param p_data pointer to the data to write. Data is arranged in sequence, data_comp0, then data_comp1, then ... NO INTERLEAVING should be set. * @param p_data_size this value os used to make sure the data being written is correct. The size must be equal to the sum for each component of tile_width * tile_height * component_size. component_size can be 1,2 or 4 bytes, depending on the precision of the given component. @@ -1315,12 +1315,19 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_setup_encoder(opj_codec_t *p_codec, opj_image_t *image); /** + * Start to compress the current image. + * @param p_codec Compressor handle + * @param image Input filled image + * @param p_stream Input stgream */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_start_compress ( opj_codec_t *p_codec, opj_image_t * p_image, - opj_stream_t *p_cio); + opj_stream_t *p_stream); /** + * End to compress the current image. + * @param p_codec Compressor handle + * @param p_stream Input stgream */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_end_compress (opj_codec_t *p_codec, opj_stream_t *p_stream); @@ -1334,7 +1341,12 @@ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_end_compress (opj_codec_t *p_codec, */ OPJ_API OPJ_BOOL OPJ_CALLCONV opj_encode(opj_codec_t *p_codec, opj_stream_t *p_stream); - +/* +========================================================== + codec output functions definitions +========================================================== +*/ +/* EXPERIMENTAL FUNCTIONS FOR NOW, USED ONLY IN J2K_DUMP*/ /** Destroy Codestream information after compression or decompression @@ -1343,13 +1355,6 @@ Destroy Codestream information after compression or decompression OPJ_API void OPJ_CALLCONV opj_destroy_cstr_info(opj_codestream_info_v2_t **cstr_info); - -/* -========================================================== - codec output functions definitions -========================================================== -*/ - /** * Dump the codec information into the output stream * @@ -1408,7 +1413,7 @@ OPJ_API opj_jp2_index_t* OPJ_CALLCONV opj_get_jp2_index(opj_codec_t *p_codec); /* ========================================================== - new functions + MCT functions ========================================================== */