Allow several repeated calls to opj_set_decode_area() and opj_decode() for single...

[openjpeg.git] / src / lib / openjp2 / openjpeg.h

diff --git a/src/lib/openjp2/openjpeg.h b/src/lib/openjp2/openjpeg.h
index 5fbf7ac36ce62b1abf506452fad4f6f26a047d34..7020d37d28e483ab565b4753cdf9575bc2b43163 100644 (file)
--- a/src/lib/openjp2/openjpeg.h
+++ b/src/lib/openjp2/openjpeg.h
@@ -501,6 +501,7 @@ typedef struct opj_cparameters {
 } opj_cparameters_t;
 
 #define OPJ_DPARAMETERS_IGNORE_PCLR_CMAP_CDEF_FLAG  0x0001
+#define OPJ_DPARAMETERS_DUMP_FLAG 0x0002
 
 /**
  * Decompression parameters
@@ -866,13 +867,13 @@ typedef struct opj_tccp_info {
     OPJ_UINT32 csty;
     /** number of resolutions */
     OPJ_UINT32 numresolutions;
-    /** code-blocks width */
+    /** log2 of code-blocks width */
     OPJ_UINT32 cblkw;
-    /** code-blocks height */
+    /** log2 of code-blocks height */
     OPJ_UINT32 cblkh;
     /** code-block coding style */
     OPJ_UINT32 cblksty;
-    /** discrete wavelet transform identifier */
+    /** discrete wavelet transform identifier: 0 = 9-7 irreversible, 1 = 5-3 reversible */
     OPJ_UINT32 qmfbid;
     /** quantisation style */
     OPJ_UINT32 qntsty;
@@ -1335,6 +1336,16 @@ 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.
  *
+ * The coordinates passed to this function should be expressed in the reference grid,
+ * that is to say at the highest resolution level, even if requesting the image at lower
+ * resolution levels.
+ *
+ * Generally opj_set_decode_area() should be followed by opj_decode(), and the
+ * codec cannot be re-used.
+ * In the particular case of an image made of a single tile, several sequences of
+ * calls to opoj_set_decode_area() and opj_decode() are allowed, and will bring
+ * performance improvements when reading an image by chunks.
+ *
  * @param   p_codec         the jpeg2000 codec.
  * @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).