[Bf-blender-cvs] [73ab5e5b636] temp-gpu-image-engine: Documented IMB transform.

[Jeroen Bakker]

Commit: 73ab5e5b636508c74c6b984a8bb790ed99d6b837
Author: Jeroen Bakker
Date:   Wed Dec 15 10:47:20 2021 +0100
Branches: temp-gpu-image-engine
https://developer.blender.org/rB73ab5e5b636508c74c6b984a8bb790ed99d6b837

Documented IMB transform.

===================================================================

M	source/blender/imbuf/IMB_imbuf.h
M	source/blender/imbuf/intern/transform.cc

===================================================================

diff --git a/source/blender/imbuf/IMB_imbuf.h b/source/blender/imbuf/IMB_imbuf.h
index daa3dbd1f1a..2a0f788416f 100644
--- a/source/blender/imbuf/IMB_imbuf.h
+++ b/source/blender/imbuf/IMB_imbuf.h
@@ -910,6 +910,25 @@ typedef enum eIMBTransformMode {
   IMB_TRANSFORM_MODE_WRAP_REPEAT = 2,
 } eIMBTransformMode;
 
+/**
+ * \brief Transform source image buffer onto destination image buffer using a transform matrix.
+ *
+ * \param src Image buffer to read from.
+ * \param dst Image buffer to write to. rect or rect_float must already be initialized.
+ * - dst buffer must be a 4 channel buffers.
+ * - Only one data type buffer will be used (rect_float has priority over rect)
+ * \param mode Cropping/Wrap repeat effect to apply during transformation.
+ * \param filter Interpolation to use during sampling.
+ * \param transform_matrix Transformation matrix to use.
+ * The given matrix should transform between dst texel space to src texel space.
+ * One unit is one texel.
+ * \param src_crop cropping region how to crop the source buffer. Should only be passed when mode
+ * is set to IMB_TRANSFORM_MODE_CROP_SRC. For any other mode this should be empty.
+ *
+ * During transformation no data/color conversion will happens.
+ * When transforming between float images the number of channels of the source buffer may be
+ * between 1 and 4. When source buffer has one channel the data will be read as a grey scale value.
+ */
 void IMB_transform(const struct ImBuf *src,
                    struct ImBuf *dst,
                    const eIMBTransformMode mode,
diff --git a/source/blender/imbuf/intern/transform.cc b/source/blender/imbuf/intern/transform.cc
index b3e2e95f396..dc28d85eeea 100644
--- a/source/blender/imbuf/intern/transform.cc
+++ b/source/blender/imbuf/intern/transform.cc
@@ -158,7 +158,7 @@ class NoDiscard : public BaseDiscard {
 };
 
 /**
- * \brief Pointer to a texel to write or read serial.
+ * \brief Pointer to a texel to write to in serial.
  */
 template<
     /**
@@ -213,8 +213,7 @@ class TexelPointer {
 /**
  * \brief Wrapping mode for the uv coordinates.
  *
- * Subclasses have the ability to change the UV coordinates before the source buffer will be
- * sampled.
+ * Subclasses have the ability to change the UV coordinates when sampling the source buffer.
  */
 class BaseUVWrapping {
  public:
@@ -272,14 +271,30 @@ class WrapRepeatUV : public BaseUVWrapping {
   }
 };
 
-template<eIMBInterpolationFilterMode Filter,
-         typename StorageType,
-         int NumChannels,
-         /**
-          * \brief Wrapping method to perform
-          * Should be a subclass of BaseUVWrapper
-          */
-         typename UVWrapping>
+/**
+ * \brief Read a sample from an image buffer.
+ *
+ * A sampler can read from an image buffer.
+ *
+ */
+template<
+    /** \brief Interpolation mode to use when sampling. */
+    eIMBInterpolationFilterMode Filter,
+
+    /** \brief storage type of a single texel channel (unsigned char or float). */
+    typename StorageType,
+    /**
+     * \brief number of channels if the image to read.
+     *
+     * Must match the actual channels of the image buffer that is sampled.
+     */
+    int NumChannels,
+    /**
+     * \brief Wrapping method to perform
+     *
+     * Should be a subclass of BaseUVWrapper
+     */
+    typename UVWrapping>
 class Sampler {
   UVWrapping uv_wrapper;
 
@@ -415,6 +430,9 @@ class ChannelConverter {
   }
 };
 
+/**
+ * \brief Processor for a scanline.
+ */
 template<
     /**
      * \brief Discard function to use.
@@ -437,12 +455,20 @@ class ScanlineProcessor {
   Discard discarder;
   OutputTexelPointer output;
   Sampler sampler;
+
+  /**
+   * \brief Channels sizzling logic to convert between the input image buffer and the output image
+   * buffer.
+   */
   ChannelConverter<typename Sampler::ChannelType,
                    Sampler::ChannelLen,
                    OutputTexelPointer::ChannelLen>
       channel_converter;
 
  public:
+  /**
+   * \brief Inner loop of the transformations, processing a full scanline.
+   */
   void process(const TransformUserData *user_data, int scanline)
   {
     const int width = user_data->dst->x;
@@ -464,6 +490,9 @@ class ScanlineProcessor {
   }
 };
 
+/**
+ * \brief callback function for threaded transformation.
+ */
 template<typename Processor> void transform_scanline_function(void *custom_data, int scanline)
 {
   const TransformUserData *user_data = static_cast<const TransformUserData *>(custom_data);
@@ -523,7 +552,7 @@ ScanlineThreadFunc get_scanline_function(const TransformUserData *user_data,
 }
 
 template<eIMBInterpolationFilterMode Filter>
-static void transform(TransformUserData *user_data, const eIMBTransformMode mode)
+static void transform_threaded(TransformUserData *user_data, const eIMBTransformMode mode)
 {
   ScanlineThreadFunc scanline_func = nullptr;
 
@@ -566,10 +595,10 @@ void IMB_transform(const struct ImBuf *src,
   user_data.init(transform_matrix);
 
   if (filter == IMB_FILTER_NEAREST) {
-    transform<IMB_FILTER_NEAREST>(&user_data, mode);
+    transform_threaded<IMB_FILTER_NEAREST>(&user_data, mode);
   }
   else {
-    transform<IMB_FILTER_BILINEAR>(&user_data, mode);
+    transform_threaded<IMB_FILTER_BILINEAR>(&user_data, mode);
   }
 }
 }