Merge #309

309: Made mapping between `ResampleAlg` and `GDALRIOResampleAlg` more direct. r=lnicola a=metasim

Before the private function `map_resample_alg` was the only way to get the expected GDAL enumeration value.

- [x] I agree to follow the project's [code of conduct](https://github.com/georust/gdal/blob/master/CODE_OF_CONDUCT.md).
- [x] I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.
---

Before this change, you had to copy `map_resample_alg` (because it was private) when calling into `gdal-sys` functions needing the resampling algorithm (e.g. `GDALAutoCreateWarpedVRT`). Instead of making `pub fn map_resample_alg ...`, took the approach that more tightly binds the C-side types to the Rust enum. Makes the association more clear, and less error prone in the future.

Co-authored-by: Simeon H.K. Fitch <[email protected]>

CHANGES.md

@@ -10,12 +10,15 @@
 
   - <https://github.com/georust/gdal/pull/303>
 
+- Provided access to `gdal-sys` discriminant values in `ResampleAlg` enum.
+
+  - <https://github.com/georust/gdal/pull/309>
+
 - **Breaking** `RasterBand::set_no_data_value` takes `Option<f64>` instead of `f64` so that no _no-data_ can be set.
   Also makes it symmetric with `RasterBand::no_data_value` which returns `Option<f64>`.
 
   - <https://github.com/georust/gdal/pull/308>
 
-
 ## 0.13
 
 - Add prebuild bindings for GDAL 3.5

src/raster/rasterband.rs

@@ -5,8 +5,8 @@ use crate::raster::{GDALDataType, GdalType};
 use crate::utils::{_last_cpl_err, _last_null_pointer_err, _string};
 use gdal_sys::{
     self, CPLErr, GDALColorEntry, GDALColorInterp, GDALColorTableH, GDALComputeRasterMinMax,
-    GDALGetRasterStatistics, GDALMajorObjectH, GDALPaletteInterp, GDALRWFlag, GDALRasterBandH,
-    GDALRasterIOExtraArg,
+    GDALGetRasterStatistics, GDALMajorObjectH, GDALPaletteInterp, GDALRIOResampleAlg, GDALRWFlag,
+    GDALRasterBandH, GDALRasterIOExtraArg,
 };
 use libc::c_int;
 use std::ffi::CString;
@@ -17,37 +17,49 @@ use ndarray::Array2;
 
 use crate::errors::*;
 
-/// Resampling algorithms, map GDAL defines
+/// Resampling algorithms used throughout various GDAL raster I/O operations.
+///
+/// # Example
+///
+/// ```rust
+/// use gdal::Dataset;
+/// # fn main() -> gdal::errors::Result<()> {
+/// use gdal::raster::ResampleAlg;
+/// let ds = Dataset::open("fixtures/tinymarble.tif")?;
+/// let band1 = ds.rasterband(1)?;
+/// let stats = band1.get_statistics(true, false)?.unwrap();
+/// // Down-sample a image using cubic-spline interpolation
+/// let buf = band1.read_as::<f64>((0, 0), ds.raster_size(), (2, 2), Some(ResampleAlg::CubicSpline))?;
+/// // In this particular image, resulting data should be close to the overall average.
+/// assert!(buf.data.iter().all(|c| (c - stats.mean).abs() < stats.std_dev / 2.0));
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug, Copy, Clone)]
+#[repr(u32)]
 pub enum ResampleAlg {
     /// Nearest neighbour
-    NearestNeighbour,
+    NearestNeighbour = GDALRIOResampleAlg::GRIORA_NearestNeighbour,
     /// Bilinear (2x2 kernel)
-    Bilinear,
+    Bilinear = GDALRIOResampleAlg::GRIORA_Bilinear,
     /// Cubic Convolution Approximation (4x4 kernel)
-    Cubic,
+    Cubic = GDALRIOResampleAlg::GRIORA_Cubic,
     /// Cubic B-Spline Approximation (4x4 kernel)
-    CubicSpline,
+    CubicSpline = GDALRIOResampleAlg::GRIORA_CubicSpline,
     /// Lanczos windowed sinc interpolation (6x6 kernel)
-    Lanczos,
+    Lanczos = GDALRIOResampleAlg::GRIORA_Lanczos,
     /// Average
-    Average,
+    Average = GDALRIOResampleAlg::GRIORA_Average,
     /// Mode (selects the value which appears most often of all the sampled points)
-    Mode,
+    Mode = GDALRIOResampleAlg::GRIORA_Mode,
     /// Gauss blurring
-    Gauss,
+    Gauss = GDALRIOResampleAlg::GRIORA_Gauss,
 }
 
-fn map_resample_alg(alg: &ResampleAlg) -> u32 {
-    match alg {
-        ResampleAlg::NearestNeighbour => 0,
-        ResampleAlg::Bilinear => 1,
-        ResampleAlg::Cubic => 2,
-        ResampleAlg::CubicSpline => 3,
-        ResampleAlg::Lanczos => 4,
-        ResampleAlg::Average => 5,
-        ResampleAlg::Mode => 6,
-        ResampleAlg::Gauss => 7,
+impl ResampleAlg {
+    /// Convert Rust enum discriminant to value expected by [`GDALRasterIOExtraArg`].
+    pub fn to_gdal(&self) -> GDALRIOResampleAlg::Type {
+        *self as GDALRIOResampleAlg::Type
     }
 }
 
@@ -131,7 +143,7 @@ impl From<RasterIOExtraArg> for GDALRasterIOExtraArg {
 
         GDALRasterIOExtraArg {
             nVersion: n_version as c_int,
-            eResampleAlg: map_resample_alg(&e_resample_alg),
+            eResampleAlg: e_resample_alg.to_gdal(),
             pfnProgress: pfn_progress,
             pProgressData: p_progress_data,
             bFloatingPointWindowValidity: b_floating_point_window_validity as c_int,