X-Git-Url: https://main.carlh.net/gitweb/?a=blobdiff_plain;f=src%2Flib%2Fopenjp2%2Fopenjpeg.h;h=9bf014b41ac512759dbb89f1c6c5a924ea26eb57;hb=d19a4ab6768c48b542c0add922eba0dcddae9ffe;hp=44fb84924f74f71151f283b7deea2255d1d7eb5f;hpb=a6a141d3262edfb741b564afadd5614089614858;p=openjpeg.git

diff --git a/src/lib/openjp2/openjpeg.h b/src/lib/openjp2/openjpeg.h
index 44fb8492..9bf014b4 100644
--- a/src/lib/openjp2/openjpeg.h
+++ b/src/lib/openjp2/openjpeg.h
@@ -1,14 +1,21 @@
  /*
- * Copyright (c) 2002-2007, Communications and Remote Sensing Laboratory, Universite catholique de Louvain (UCL), Belgium
- * Copyright (c) 2002-2007, Professor Benoit Macq
+ * The copyright in this software is being made available under the 2-clauses 
+ * BSD License, included below. This software may be subject to other third 
+ * party and contributor rights, including patent rights, and no such rights
+ * are granted under this license.
+ *
+ * Copyright (c) 2002-2014, Universite catholique de Louvain (UCL), Belgium
+ * Copyright (c) 2002-2014, Professor Benoit Macq
  * Copyright (c) 2001-2003, David Janssens
  * Copyright (c) 2002-2003, Yannick Verschueren
- * Copyright (c) 2003-2007, Francois-Olivier Devaux and Antonin Descampe
+ * Copyright (c) 2003-2007, Francois-Olivier Devaux 
+ * Copyright (c) 2003-2014, Antonin Descampe
  * Copyright (c) 2005, Herve Drolon, FreeImage Team
  * Copyright (c) 2006-2007, Parvatha Elangovan
  * Copyright (c) 2008, Jerome Fimes, Communications & Systemes <jerome.fimes@c-s.fr>
  * Copyright (c) 2010-2011, Kaori Hagihara
- * Copyright (c) 2011, Mickael Savinaud, Communications & Systemes <mickael.savinaud@c-s.fr>
+ * Copyright (c) 2011-2012, Centre National d'Etudes Spatiales (CNES), France 
+ * Copyright (c) 2012, CS Systemes d'Information, France
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -42,14 +49,31 @@
 ==========================================================
 */
 
+/*
+The inline keyword is supported by C99 but not by C90. 
+Most compilers implement their own version of this keyword ... 
+*/
+#ifndef INLINE
+	#if defined(_MSC_VER)
+		#define INLINE __forceinline
+	#elif defined(__GNUC__)
+		#define INLINE __inline__
+	#elif defined(__MWERKS__)
+		#define INLINE inline
+	#else 
+		/* add other compilers here ... */
+		#define INLINE 
+	#endif /* defined(<Compiler>) */
+#endif /* INLINE */
+
 /* deprecated attribute */
 #ifdef __GNUC__
-	#define DEPRECATED(func) func __attribute__ ((deprecated))
+	#define OPJ_DEPRECATED(func) func __attribute__ ((deprecated))
 #elif defined(_MSC_VER)
-	#define DEPRECATED(func) __declspec(deprecated) func
+	#define OPJ_DEPRECATED(func) __declspec(deprecated) func
 #else
 	#pragma message("WARNING: You need to implement DEPRECATED for this compiler")
-	#define DEPRECATED(func) func
+	#define OPJ_DEPRECATED(func) func
 #endif
 
 #if defined(OPJ_STATIC) || !defined(_WIN32)
@@ -79,7 +103,7 @@ defined with this macro as being exported.
 #endif /* OPJ_EXPORTS */
 #endif /* !OPJ_STATIC || !_WIN32 */
 
-typedef int opj_bool; /*FIXME it should be to follow the name of others OPJ_TYPE -> OPJ_BOOL*/
+typedef int OPJ_BOOL;
 #define OPJ_TRUE 1
 #define OPJ_FALSE 0
 
@@ -99,6 +123,11 @@ typedef uint32_t OPJ_UINT32;
 typedef int64_t  OPJ_INT64;
 typedef uint64_t OPJ_UINT64;
 
+typedef int64_t  OPJ_OFF_T; /* 64-bit file offset type */
+
+#include <stdio.h>
+typedef size_t   OPJ_SIZE_T;
+
 /* Avoid compile-time warning because parameter is not used */
 #define OPJ_ARG_NOT_USED(x) (void)(x)
 
@@ -110,16 +139,16 @@ typedef uint64_t OPJ_UINT64;
 
 #define OPJ_PATH_LEN 4096 /**< Maximum allowed size for filenames */
 
-#define J2K_MAXRLVLS 33					/**< Number of maximum resolution level authorized */
-#define J2K_MAXBANDS (3*J2K_MAXRLVLS-2)	/**< Number of maximum sub-band linked to number of resolution level */
+#define OPJ_J2K_MAXRLVLS 33					/**< Number of maximum resolution level authorized */
+#define OPJ_J2K_MAXBANDS (3*OPJ_J2K_MAXRLVLS-2)	/**< Number of maximum sub-band linked to number of resolution level */
 
-#define J2K_DEFAULT_NB_SEGS				10
-#define J2K_STREAM_CHUNK_SIZE			0x100000 /** 1 mega by default */
-#define J2K_DEFAULT_HEADER_SIZE			1000
-#define J2K_MCC_DEFAULT_NB_RECORDS		10
-#define J2K_MCT_DEFAULT_NB_RECORDS		10
+#define OPJ_J2K_DEFAULT_NB_SEGS				10
+#define OPJ_J2K_STREAM_CHUNK_SIZE			0x100000 /** 1 mega by default */
+#define OPJ_J2K_DEFAULT_HEADER_SIZE			1000
+#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,13 +160,13 @@ typedef uint64_t OPJ_UINT64;
 /* <<UniPG */
 
 /**
- * FIXME EXPERIMENTAL FOR THE MOMENT
- * Supported options about file information
+ * EXPERIMENTAL FOR THE MOMENT
+ * Supported options about file information used only in j2k_dump
 */
 #define OPJ_IMG_INFO		1	/**< Basic image information provided to the user */
 #define OPJ_J2K_MH_INFO		2	/**< Codestream information based only on the main header */
 #define OPJ_J2K_TH_INFO		4	/**< Tile information based on the current tile header */
-/*FIXME #define OPJ_J2K_CSTR_INFO	6*/	/**<  */
+#define OPJ_J2K_TCH_INFO	8	/**< Tile/Component information of all tiles */
 #define OPJ_J2K_MH_IND		16	/**< Codestream index based only on the main header */
 #define OPJ_J2K_TH_IND		32	/**< Tile index based on the current tile */
 /*FIXME #define OPJ_J2K_CSTR_IND	48*/	/**<  */
@@ -154,64 +183,56 @@ typedef uint64_t OPJ_UINT64;
  * Rsiz Capabilities
  * */
 typedef enum RSIZ_CAPABILITIES {
-	STD_RSIZ = 0,		/** Standard JPEG2000 profile*/
-	CINEMA2K = 3,		/** Profile name for a 2K image*/
-	CINEMA4K = 4,		/** Profile name for a 4K image*/
-	MCT = 0x8100
+	OPJ_STD_RSIZ = 0,		/** Standard JPEG2000 profile*/
+	OPJ_CINEMA2K = 3,		/** Profile name for a 2K image*/
+	OPJ_CINEMA4K = 4,		/** Profile name for a 4K image*/
+	OPJ_MCT = 0x8100
 } OPJ_RSIZ_CAPABILITIES;
 
 /** 
  * Digital cinema operation mode
  * */
 typedef enum CINEMA_MODE {
-	OFF = 0,			/** Not Digital Cinema*/
-	CINEMA2K_24 = 1,	/** 2K Digital Cinema at 24 fps*/
-	CINEMA2K_48 = 2,	/** 2K Digital Cinema at 48 fps*/
-	CINEMA4K_24 = 3		/** 4K Digital Cinema at 24 fps*/
+	OPJ_OFF = 0,			/** Not Digital Cinema*/
+	OPJ_CINEMA2K_24 = 1,	/** 2K Digital Cinema at 24 fps*/
+	OPJ_CINEMA2K_48 = 2,	/** 2K Digital Cinema at 48 fps*/
+	OPJ_CINEMA4K_24 = 3		/** 4K Digital Cinema at 24 fps*/
 }OPJ_CINEMA_MODE;
 
 /** 
  * Progression order
  * */
 typedef enum PROG_ORDER {
-	PROG_UNKNOWN = -1,	/**< place-holder */
-	LRCP = 0,			/**< layer-resolution-component-precinct order */
-	RLCP = 1,			/**< resolution-layer-component-precinct order */
-	RPCL = 2,			/**< resolution-precinct-component-layer order */
-	PCRL = 3,			/**< precinct-component-resolution-layer order */
-	CPRL = 4			/**< component-precinct-resolution-layer order */
+	OPJ_PROG_UNKNOWN = -1,	/**< place-holder */
+	OPJ_LRCP = 0,			/**< layer-resolution-component-precinct order */
+	OPJ_RLCP = 1,			/**< resolution-layer-component-precinct order */
+	OPJ_RPCL = 2,			/**< resolution-precinct-component-layer order */
+	OPJ_PCRL = 3,			/**< precinct-component-resolution-layer order */
+	OPJ_CPRL = 4			/**< component-precinct-resolution-layer order */
 } OPJ_PROG_ORDER;
 
 /**
  * Supported image color spaces
 */
 typedef enum COLOR_SPACE {
-	CLRSPC_UNKNOWN = -1,	/**< not supported by the library */
-	CLRSPC_UNSPECIFIED = 0, /**< not specified in the codestream */ 
-	CLRSPC_SRGB = 1,		/**< sRGB */
-	CLRSPC_GRAY = 2,		/**< grayscale */
-	CLRSPC_SYCC = 3			/**< YUV */
+	OPJ_CLRSPC_UNKNOWN = -1,	/**< not supported by the library */
+	OPJ_CLRSPC_UNSPECIFIED = 0,	/**< not specified in the codestream */ 
+	OPJ_CLRSPC_SRGB = 1,		/**< sRGB */
+	OPJ_CLRSPC_GRAY = 2,		/**< grayscale */
+	OPJ_CLRSPC_SYCC = 3,		/**< YUV */
+  OPJ_CLRSPC_EYCC = 4		/**< e-YCC */
 } OPJ_COLOR_SPACE;
 
 /**
  * Supported codec
 */
 typedef enum CODEC_FORMAT {
-	CODEC_UNKNOWN = -1,	/**< place-holder */
-	CODEC_J2K  = 0,		/**< JPEG-2000 codestream : read/write */
-	CODEC_JPT  = 1,		/**< JPT-stream (JPEG 2000, JPIP) : read only */
-	CODEC_JP2  = 2 		/**< JPEG-2000 file format : read/write */
+	OPJ_CODEC_UNKNOWN = -1,	/**< place-holder */
+	OPJ_CODEC_J2K  = 0,		/**< JPEG-2000 codestream : read/write */
+	OPJ_CODEC_JPT  = 1,		/**< JPT-stream (JPEG 2000, JPIP) : read only */
+	OPJ_CODEC_JP2  = 2 		/**< JPEG-2000 file format : read/write */
 } OPJ_CODEC_FORMAT;
 
-/** 
- * Limit decoding to certain portions of the codestream.
-*/
-typedef enum LIMIT_DECODING {
-	NO_LIMITATION = 0,				/**< No limitation for the decoding. The entire codestream will de decoded */
-	LIMIT_TO_MAIN_HEADER = 1,		/**< The decoding is limited to the Main Header */
-	DECODE_ALL_BUT_PACKETS = 2		/**< Decode everything except the JPEG 2000 packets */
-} OPJ_LIMIT_DECODING;
-
 
 /* 
 ==========================================================
@@ -221,8 +242,8 @@ typedef enum LIMIT_DECODING {
 
 /**
  * Callback function prototype for events
- * @param msg Event message
- * @param client_data
+ * @param msg               Event message
+ * @param client_data       Client object where will be return the event message 
  * */
 typedef void (*opj_msg_callback) (const char *msg, void *client_data);
 
@@ -266,7 +287,7 @@ typedef struct opj_poc {
  * */
 typedef struct opj_cparameters {
 	/** size of tile: tile_size_on = false (not in argument) or = true (in argument) */
-	opj_bool tile_size_on;
+	OPJ_BOOL tile_size_on;
 	/** XTOsiz */
 	int cp_tx0;
 	/** YTOsiz */
@@ -287,12 +308,12 @@ typedef struct opj_cparameters {
 	char *cp_comment;
 	/** csty : coding style */
 	int csty;
-	/** progression order (default LRCP) */
+	/** progression order (default OPJ_LRCP) */
 	OPJ_PROG_ORDER prog_order;
 	/** progression order changes */
 	opj_poc_t POC[32];
 	/** number of progression order changes (POC), default to 0 */
-	int numpocs;
+	OPJ_UINT32 numpocs;
 	/** number of layers */
 	int tcp_numlayers;
 	/** rates of layers */
@@ -316,9 +337,9 @@ typedef struct opj_cparameters {
 	/* number of precinct size specifications */
 	int res_spec;
 	/** initial precinct width */
-	int prcw_init[J2K_MAXRLVLS];
+	int prcw_init[OPJ_J2K_MAXRLVLS];
 	/** initial precinct height */
-	int prch_init[J2K_MAXRLVLS];
+	int prch_init[OPJ_J2K_MAXRLVLS];
 
 	/**@name command line encoder parameters (not used inside the library) */
 	/*@{*/
@@ -344,11 +365,11 @@ typedef struct opj_cparameters {
 	int cod_format;
 	/*@}*/
 
-/* UniPG>> */
+/* UniPG>> */ /* NOT YET USED IN THE V2 VERSION OF OPENJPEG */
 	/**@name JPWL encoding parameters */
 	/*@{*/
 	/** enables writing of EPC in MH, thus activating JPWL */
-	opj_bool jpwl_epc_on;
+	OPJ_BOOL jpwl_epc_on;
 	/** error protection method for MH (0,1,16,32,37-128) */
 	int jpwl_hprot_MH;
 	/** tile number of header protection specification (>=0) */
@@ -389,10 +410,11 @@ typedef struct opj_cparameters {
 	/** MCT (multiple component transform) */
 	char tcp_mct;
 	/** Enable JPIP indexing*/
-	opj_bool jpip_on;
-	/** Naive implementation of MCT restricted to a single reversible array based encoding without offset concerning all the components. */
+	OPJ_BOOL jpip_on;
+	/** Naive implementation of MCT restricted to a single reversible array based 
+        encoding without offset concerning all the components. */
 	void * mct_data;
-} opj_cparameters_t;
+} opj_cparameters_t;  
 
 #define OPJ_DPARAMETERS_IGNORE_PCLR_CMAP_CDEF_FLAG	0x0001
 
@@ -407,14 +429,14 @@ typedef struct opj_dparameters {
 	if != 0, then original dimension divided by 2^(reduce); 
 	if == 0 or not used, image is decoded to the full resolution 
 	*/
-	int cp_reduce;
+	OPJ_UINT32 cp_reduce;
 	/** 
 	Set the maximum number of quality layers to decode. 
 	If there are less quality layers than the specified number, all the quality layers are decoded.
 	if != 0, then only the first "layer" layers are decoded; 
 	if == 0 or not used, all the quality layers are decoded 
 	*/
-	int cp_layer;
+	OPJ_UINT32 cp_layer;
 
 	/**@name command line decoder parameters (not used inside the library) */
 	/*@{*/
@@ -436,7 +458,7 @@ typedef struct opj_dparameters {
 	/** Decoding area bottom boundary */
 	OPJ_UINT32 DA_y1;
 	/** Verbose mode */
-	opj_bool m_verbose;
+	OPJ_BOOL m_verbose;
 
 	/** tile number ot the decoded tile*/
 	OPJ_UINT32 tile_index;
@@ -445,11 +467,11 @@ typedef struct opj_dparameters {
 
 	/*@}*/
 
-/* UniPG>> */
+/* UniPG>> */ /* NOT YET USED IN THE V2 VERSION OF OPENJPEG */
 	/**@name JPWL decoding parameters */
 	/*@{*/
 	/** activates the JPWL correction capabilities */
-	opj_bool jpwl_correct;
+	OPJ_BOOL jpwl_correct;
 	/** expected number of components */
 	int jpwl_exp_comps;
 	/** maximum number of tiles */
@@ -457,18 +479,9 @@ typedef struct opj_dparameters {
 	/*@}*/
 /* <<UniPG */
 
-	/** 
-	Specify whether the decoding should be done on the entire codestream, or be limited to the main header
-	Limiting the decoding to the main header makes it possible to extract the characteristics of the codestream
-	if == NO_LIMITATION, the entire codestream is decoded; 
-	if == LIMIT_TO_MAIN_HEADER, only the main header is decoded; 
-	*/
-	OPJ_LIMIT_DECODING cp_limit_decoding;
-
 	unsigned int flags;
-} opj_dparameters_t;
-
 
+} opj_dparameters_t;
 
 
 /**
@@ -482,24 +495,38 @@ typedef void * opj_codec_t;
 ==========================================================
 */
 
-/*
+/**
  * Stream open flags.
- */
+ * */
 /** The stream was opened for reading. */
-#define OPJ_STREAM_READ	0x0001
+#define OPJ_STREAM_READ	OPJ_TRUE
 /** The stream was opened for writing. */
-#define OPJ_STREAM_WRITE 0x0002
-
-
-
+#define OPJ_STREAM_WRITE OPJ_FALSE
 
 /*
- * FIXME DOC
+ * Callback function prototype for read function
  */
 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
+ */
 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
+ */
 typedef OPJ_OFF_T (* opj_stream_skip_fn) (OPJ_OFF_T p_nb_bytes, void * p_user_data) ;
-typedef opj_bool (* opj_stream_seek_fn) (OPJ_OFF_T p_nb_bytes, void * p_user_data) ;
+
+/*
+ * Callback function prototype for seek function
+ */
+typedef OPJ_BOOL (* opj_stream_seek_fn) (OPJ_OFF_T p_nb_bytes, void * p_user_data) ;
+
+/*
+ * Callback function prototype for free user data function
+ */
+typedef void (* opj_stream_free_user_data_fn) (void * p_user_data) ;
 
 /*
  * JPEG2000 Stream.
@@ -540,6 +567,8 @@ typedef struct opj_image_comp {
 	OPJ_UINT32 factor;
 	/** image component data */
 	OPJ_INT32 *data;
+  /** alpha channel */
+  OPJ_UINT16 alpha;
 } opj_image_comp_t;
 
 /** 
@@ -597,6 +626,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
@@ -760,17 +790,17 @@ typedef struct opj_tccp_info
 	/** quantisation style */
 	OPJ_UINT32 qntsty;
 	/** stepsizes used for quantization */
-	OPJ_UINT32 stepsizes_mant[J2K_MAXBANDS];
+	OPJ_UINT32 stepsizes_mant[OPJ_J2K_MAXBANDS];
 	/** stepsizes used for quantization */
-	OPJ_UINT32 stepsizes_expn[J2K_MAXBANDS];
+	OPJ_UINT32 stepsizes_expn[OPJ_J2K_MAXBANDS];
 	/** number of guard bits */
 	OPJ_UINT32 numgbits;
 	/** Region Of Interest shift */
 	OPJ_INT32 roishift;
 	/** precinct width */
-	OPJ_UINT32 prcw[J2K_MAXRLVLS];
+	OPJ_UINT32 prcw[OPJ_J2K_MAXRLVLS];
 	/** precinct height */
-	OPJ_UINT32 prch[J2K_MAXRLVLS];
+	OPJ_UINT32 prch[OPJ_J2K_MAXRLVLS];
 }
 opj_tccp_info_t;
 
@@ -854,7 +884,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 */
@@ -882,7 +912,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 */
@@ -907,7 +937,7 @@ typedef struct opj_codestream_index {
 
 /**
  * Info structure of the JP2 file
- * FIXME
+ * EXPERIMENTAL FOR THE MOMENT
  */
 typedef struct opj_jp2_metadata {
 	/** */
@@ -917,7 +947,7 @@ typedef struct opj_jp2_metadata {
 
 /**
  * Index structure of the JP2 file
- * FIXME
+ * EXPERIMENTAL FOR THE MOMENT
  */
 typedef struct opj_jp2_index {
 	/** */
@@ -937,6 +967,7 @@ extern "C" {
 ==========================================================
 */
 
+/* Get the version of the openjpeg library*/
 OPJ_API const char * OPJ_CALLCONV opj_version(void);
 
 /* 
@@ -947,32 +978,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
@@ -986,7 +1017,7 @@ OPJ_API opj_image_t* OPJ_CALLCONV opj_image_tile_create(OPJ_UINT32 numcmpts, opj
  *
  * @return	a stream object.
 */
-OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_default_create(opj_bool p_is_input);
+OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_default_create(OPJ_BOOL p_is_input);
 
 /**
  * Creates an abstract stream. This function does nothing except allocating memory and initializing the abstract stream.
@@ -996,7 +1027,7 @@ OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_default_create(opj_bool p_is_input
  *
  * @return	a stream object.
 */
-OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create(OPJ_SIZE_T p_buffer_size, opj_bool p_is_input);
+OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create(OPJ_SIZE_T p_buffer_size, OPJ_BOOL p_is_input);
 
 /**
  * Destroys a stream created by opj_create_stream. This function does NOT close the abstract stream. If needed the user must
@@ -1006,6 +1037,14 @@ OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create(OPJ_SIZE_T p_buffer_size, o
  */
 OPJ_API void OPJ_CALLCONV opj_stream_destroy(opj_stream_t* p_stream);
 
+/**
+ * Destroys a stream created by opj_create_stream. This function does NOT close the abstract stream. 
+ * If needed the user must close its own implementation of the stream.
+ *
+ * @param	p_stream	the stream to destroy.
+ */
+OPJ_API void OPJ_CALLCONV opj_stream_destroy_v3(opj_stream_t* p_stream);
+ 
 /**
  * Sets the given function to be used as a read function.
  * @param		p_stream	the stream to modify
@@ -1038,8 +1077,17 @@ OPJ_API void OPJ_CALLCONV opj_stream_set_seek_function(opj_stream_t* p_stream, o
  * Sets the given data to be used as a user data for the stream.
  * @param		p_stream	the stream to modify
  * @param		p_data		the data to set.
+ * @warning depending on your source object p_stream this function may leak, use opj_stream_set_user_data_v3
 */
-OPJ_API void OPJ_CALLCONV opj_stream_set_user_data (opj_stream_t* p_stream, void * p_data);
+OPJ_DEPRECATED(OPJ_API void OPJ_CALLCONV opj_stream_set_user_data (opj_stream_t* p_stream, void * p_data));
+
+/**
+ * Sets the given data to be used as a user data for the stream.
+ * @param		p_stream	the stream to modify
+ * @param		p_data		the data to set.
+ * @param		p_function	the function to free p_data when opj_stream_destroy() is called.
+*/
+OPJ_API void OPJ_CALLCONV opj_stream_set_user_data_v3 (opj_stream_t* p_stream, void * p_data, opj_stream_free_user_data_fn p_function);
 
 /**
  * Sets the length of the user data for the stream.
@@ -1050,23 +1098,21 @@ OPJ_API void OPJ_CALLCONV opj_stream_set_user_data (opj_stream_t* p_stream, void
 OPJ_API void OPJ_CALLCONV opj_stream_set_user_data_length(opj_stream_t* p_stream, OPJ_UINT64 data_length);
 
 /**
- * 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)
+ * Create a stream from a file identified with its filename with default parameters (helper function)
+ * @param fname             the filename of the file 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_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
+OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create_default_file_stream_v3 (const char *fname, OPJ_BOOL p_is_read_stream);
+ 
+/** Create a stream from a file identified with its filename with a specific buffer size
+ * @param fname             the filename of the file to stream
+ * @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);
-
-/* -----------> */
-
+OPJ_API opj_stream_t* OPJ_CALLCONV opj_stream_create_file_stream_v3 (const char *fname, 
+                                                                     OPJ_SIZE_T p_buffer_size,
+                                                                     OPJ_BOOL p_is_read_stream);
+ 
 /* 
 ==========================================================
    event manager functions definitions
@@ -1076,27 +1122,27 @@ 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_API OPJ_BOOL OPJ_CALLCONV opj_set_info_handler(opj_codec_t * p_codec, 
                                                    opj_msg_callback p_callback,
                                                    void * p_user_data);
 /**
  * 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_API OPJ_BOOL OPJ_CALLCONV opj_set_warning_handler(opj_codec_t * p_codec,
                                                       opj_msg_callback p_callback,
                                                       void * p_user_data);
 /**
  * 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_API OPJ_BOOL OPJ_CALLCONV opj_set_error_handler(opj_codec_t * p_codec, 
                                                     opj_msg_callback p_callback,
                                                     void * p_user_data);
 
@@ -1126,7 +1172,7 @@ OPJ_API void OPJ_CALLCONV opj_destroy_codec(opj_codec_t * p_codec);
  * @param	p_codec			the JPEG2000 codec to read.
  * @param	p_stream		the JPEG2000 stream.
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_end_decompress (	opj_codec_t *p_codec,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_end_decompress (	opj_codec_t *p_codec,
 													opj_stream_t *p_stream);
 
 
@@ -1145,7 +1191,7 @@ OPJ_API void OPJ_CALLCONV opj_set_default_decoder_parameters(opj_dparameters_t *
  *
  * @return true			if the decoder is correctly set
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_setup_decoder(opj_codec_t *p_codec,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_setup_decoder(opj_codec_t *p_codec,
 												opj_dparameters_t *parameters );
 
 /**
@@ -1157,7 +1203,7 @@ OPJ_API opj_bool OPJ_CALLCONV opj_setup_decoder(opj_codec_t *p_codec,
  *
  * @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_stream,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_read_header (	opj_stream_t *p_stream,
 												opj_codec_t *p_codec,
 												opj_image_t **p_image);
 
@@ -1165,7 +1211,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).
@@ -1173,24 +1219,26 @@ OPJ_API opj_bool OPJ_CALLCONV opj_read_header (	opj_stream_t *p_stream,
  *
  * @return	true			if the area could be set.
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_set_decode_area(	opj_codec_t *p_codec,
+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 p_decompressor 	decompressor handle
  * @param p_stream			Input buffer stream
  * @param p_image 			the decoded image
  * @return 					true if success, otherwise false
  * */
-OPJ_API opj_bool OPJ_CALLCONV opj_decode(   opj_codec_t *p_decompressor,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_decode(   opj_codec_t *p_decompressor,
                                             opj_stream_t *p_stream,
                                             opj_image_t *p_image);
 
 /**
  * Get the decoded tile from the codec
+ *
  * @param	p_codec			the jpeg2000 codec.
  * @param	p_stream		input streamm
  * @param	p_image			output image
@@ -1198,7 +1246,7 @@ OPJ_API opj_bool OPJ_CALLCONV opj_decode(   opj_codec_t *p_decompressor,
  *
  * @return					true if success, otherwise false
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_get_decoded_tile(	opj_codec_t *p_codec,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_get_decoded_tile(	opj_codec_t *p_codec,
 													opj_stream_t *p_stream,
 													opj_image_t *p_image,
 													OPJ_UINT32 tile_index);
@@ -1210,20 +1258,21 @@ OPJ_API opj_bool OPJ_CALLCONV opj_get_decoded_tile(	opj_codec_t *p_codec,
  *
  * @return					true if success, otherwise false
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_set_decoded_resolution_factor(opj_codec_t *p_codec, OPJ_UINT32 res_factor);
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_decoded_resolution_factor(opj_codec_t *p_codec, OPJ_UINT32 res_factor);
 
 /**
  * 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.
+ * @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.
  * @param	p_stream			the stream to write data to.
  *
  * @return	true if the data could be written.
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_write_tile (	opj_codec_t *p_codec,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_write_tile (	opj_codec_t *p_codec,
 												OPJ_UINT32 p_tile_index,
 												OPJ_BYTE * p_data,
 												OPJ_UINT32 p_data_size,
@@ -1250,14 +1299,14 @@ OPJ_API opj_bool OPJ_CALLCONV opj_write_tile (	opj_codec_t *p_codec,
  * @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_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 );
+												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.
@@ -1271,7 +1320,7 @@ OPJ_API opj_bool OPJ_CALLCONV opj_read_tile_header(	opj_codec_t *p_codec,
  *
  * @return	true			if the data could be decoded.
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_decode_tile_data(	opj_codec_t *p_codec,
+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,
@@ -1315,19 +1364,26 @@ OPJ_API void OPJ_CALLCONV opj_set_default_encoder_parameters(opj_cparameters_t *
  * @param parameters 	Compression parameters
  * @param image 		Input filled image
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_setup_encoder(opj_codec_t *p_codec, 
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_setup_encoder(opj_codec_t *p_codec, 
 												opj_cparameters_t *parameters, 
 												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_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_API OPJ_BOOL OPJ_CALLCONV opj_end_compress (opj_codec_t *p_codec,
 												opj_stream_t *p_stream);
 
 /**
@@ -1337,9 +1393,14 @@ OPJ_API opj_bool OPJ_CALLCONV opj_end_compress (opj_codec_t *p_codec,
  *
  * @return 				Returns true if successful, returns false otherwise
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_encode(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
@@ -1348,13 +1409,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
  *
@@ -1413,7 +1467,7 @@ OPJ_API opj_jp2_index_t* OPJ_CALLCONV opj_get_jp2_index(opj_codec_t *p_codec);
 
 /*
 ==========================================================
-   new functions
+   MCT functions
 ==========================================================
 */
 
@@ -1427,7 +1481,7 @@ OPJ_API opj_jp2_index_t* OPJ_CALLCONV opj_get_jp2_index(opj_codec_t *p_codec);
  *
  * @return	true if the parameters could be set.
  */
-OPJ_API opj_bool OPJ_CALLCONV opj_set_MCT( opj_cparameters_t *parameters,
+OPJ_API OPJ_BOOL OPJ_CALLCONV opj_set_MCT( opj_cparameters_t *parameters,
 		                               	   OPJ_FLOAT32 * pEncodingMatrix,
 		                               	   OPJ_INT32 * p_dc_shift,
 		                               	   OPJ_UINT32 pNbComp);