From: Bborie Park <bkpark at ucdavis.edu>
Date: Tue, 25 Sep 2012 22:22:40 +0000 (+0000)
Subject: Added docs regarding the callback function for rt_raster_iterator()
X-Git-Tag: 2.1.0beta2~618
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3e208afb126bd619d3d3dcca406028b3fa56b952;p=postgis

Added docs regarding the callback function for rt_raster_iterator()

git-svn-id: http://svn.osgeo.org/postgis/trunk@10332 b70326c6-7e19-0410-871a-916f4a2858ee
---

diff --git a/raster/rt_core/rt_api.c b/raster/rt_core/rt_api.c
index 245b6ef3f..ea436992f 100644
--- a/raster/rt_core/rt_api.c
+++ b/raster/rt_core/rt_api.c
@@ -13156,6 +13156,19 @@ _rti_param_arg_clean(_rti_param _param) {
  * @param callback: callback function for actual processing of pixel values.
  * @param noerr: if 0, error occurred
  *
+ * The callback function _must_ have the following signature.
+ *
+ *    int FNAME(rt_iterator_arg arg, void *userarg, double *value, int *nodata)
+ *
+ * The callback function _must_ return zero (error) or non-zero (success)
+ * indicating whether the function ran successfully.
+ * The parameters passed to the callback function are as follows.
+ *
+ * - rt_iterator_arg arg: struct containing pixel values, NODATA flags and metadata
+ * - void *userarg: NULL or calling function provides to rt_raster_iterator() for use by callback function
+ * - double *value: value of pixel to be burned by rt_raster_iterator()
+ * - int *nodata: flag (0 or 1) indicating that pixel to be burned is NODATA
+ *
  * @return raster object if success, NULL otherwise
  */
 rt_raster
diff --git a/raster/rt_core/rt_api.h b/raster/rt_core/rt_api.h
index 17d2be4d1..f134d117a 100644
--- a/raster/rt_core/rt_api.h
+++ b/raster/rt_core/rt_api.h
@@ -1752,6 +1752,19 @@ rt_raster_from_two_rasters(
  * @param callback: callback function for actual processing of pixel values.
  * @param noerr: if 0, error occurred
  *
+ * The callback function _must_ have the following signature.
+ *
+ *    int FNAME(rt_iterator_arg arg, void *userarg, double *value, int *nodata)
+ *
+ * The callback function _must_ return zero (error) or non-zero (success)
+ * indicating whether the function ran successfully.
+ * The parameters passed to the callback function are as follows.
+ *
+ * - rt_iterator_arg arg: struct containing pixel values, NODATA flags and metadata
+ * - void *userarg: NULL or calling function provides to rt_raster_iterator() for use by callback function
+ * - double *value: value of pixel to be burned by rt_raster_iterator()
+ * - int *nodata: flag (0 or 1) indicating that pixel to be burned is NODATA
+ *
  * @return raster object if success, NULL otherwise
  */
 rt_raster