Make opj_set_decode_area() and opj_decode() take into account opj_set_decoded_resolution_factor() (#1006, affect API use)

* Better document usage of opj_set_decode_area(), ie expecting coordinates
  in full resolution/reference grid even if requesting at a lower resolution
  factor
* Make sure that image->comps[].factor is set by opj_set_decode_area() and
  opj_decode() from the value specified in opj_set_decoded_resolution_factor()
* opj_decompress: add 2 environmenet variables to test alternate ways of
  using the API, namely USE_OPJ_SET_DECODED_RESOLUTION_FACTOR=YES to use
  opj_set_decoded_resolution_factor() instead of parameters.cp_reduce, and
  SKIP_OPJ_SET_DECODE_AREA=YES to not call opj_set_decode_area() if -d is
  not specified.

1 files changed, 4 insertions, 0 deletions

diff --git a/src/lib/openjp2/openjpeg.h b/src/lib/openjp2/openjpeg.h
index 9ae29a4f..21755b48 100644
--- a/src/lib/openjp2/openjpeg.h
+++ b/src/lib/openjp2/openjpeg.h
@@ -1336,6 +1336,10 @@ 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.
+ *
  * @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).