Added API documentation.temp-gpu-texture-partial-updates

1 files changed, 132 insertions, 68 deletions

diff --git a/source/blender/blenkernel/BKE_image_partial_update.hh b/source/blender/blenkernel/BKE_image_partial_update.hh
index 107e54c9351..dfc02fea742 100644
--- a/source/blender/blenkernel/BKE_image_partial_update.hh
+++ b/source/blender/blenkernel/BKE_image_partial_update.hh
@@ -18,6 +18,13 @@
 
 /** \file
  * \ingroup bke
+ *
+ * To reduce the overhead of image processing this file contains a mechanism to detect areas of the
+ * image that are changed. These areas are organized in chunks. Changes that happen over time are
+ * organized in changesets.
+ *
+ * A common usecase is to update GPUTexture for drawing where only that part is uploaded that only
+ * changed.
  */
 
 #pragma once
@@ -104,23 +111,76 @@ ePartialUpdateCollectResult BKE_image_partial_update_collect_changes(
 ePartialUpdateIterResult BKE_image_partial_update_get_next_change(
     struct PartialUpdateUser *user, struct PartialUpdateRegion *r_region);
 
+/** \brief Abstract class to load tile data when using the PartialUpdateChecker. */
 class AbstractTileData {
  protected:
   virtual ~AbstractTileData() = default;
 
  public:
+  /**
+   * \brief Load the data for the given tile_number.
+   *
+   * Invoked when changes are on a different tile compared to the previous tile..
+   */
   virtual void init_data(TileNumber tile_number) = 0;
+  /**
+   * \brief Unload the data that has been loaded.
+   *
+   * Invoked when changes are on a different tile compared to the previous tile or when finished
+   * iterating over the changes.
+   */
   virtual void free_data() = 0;
 };
 
-class ImageTileData : AbstractTileData {
+/**
+ * \brief Class to not load any tile specific data when iterating over changes.
+ */
+class NoTileData : AbstractTileData {
  public:
-  ImageTile *tile = nullptr;
-  ImBuf *tile_buffer = nullptr;
+  NoTileData(Image *UNUSED(image), ImageUser &UNUSED(image_user))
+  {
+  }
+
+  void init_data(TileNumber UNUSED(new_tile_number)) override
+  {
+  }
 
+  void free_data() override
+  {
+  }
+};
+
+/**
+ * \brief Load the ImageTile and ImBuf associated with the partial change.
+ */
+class ImageTileData : AbstractTileData {
+ public:
+  /**
+   * \brief Not owned Image that is being iterated over.
+   */
   Image *image;
+
+  /**
+   * \brief Local copy of the image user.
+   *
+   * The local copy is required so we don't change the image user of the caller.
+   * We need to change it in order to request data for a specific tile.
+   */
   ImageUser image_user;
 
+  /**
+   * \brief ImageTile associated with the loaded tile.
+   * Data is not owned by this instance but by the `image`.
+   */
+  ImageTile *tile = nullptr;
+
+  /**
+   * \brief ImBuf of the loaded tile.
+   *
+   * Can be nullptr when the file doesn't exist or when the tile hasn't been initialized.
+   */
+  ImBuf *tile_buffer = nullptr;
+
   ImageTileData(Image *image, ImageUser image_user) : image(image), image_user(image_user)
   {
   }
@@ -128,7 +188,6 @@ class ImageTileData : AbstractTileData {
   void init_data(TileNumber new_tile_number) override
   {
     image_user.tile = new_tile_number;
-
     tile = BKE_image_get_tile(image, new_tile_number);
     tile_buffer = BKE_image_acquire_ibuf(image, &image_user, NULL);
   }
@@ -141,77 +200,79 @@ class ImageTileData : AbstractTileData {
   }
 };
 
-class NoTileData : AbstractTileData {
- public:
-  NoTileData(Image *UNUSED(image), ImageUser &UNUSED(image_user))
-  {
-  }
+template<typename TileData = NoTileData> struct PartialUpdateChecker {
 
-  void init_data(TileNumber UNUSED(new_tile_number)) override
-  {
-  }
-
-  void free_data() override
-  {
-  }
-};
-
-template<typename TileData = NoTileData> struct PartialUpdateCollectResult {
+  /**
+   * \brief Not owned Image that is being iterated over.
+   */
   Image *image;
-  PartialUpdateUser *user;
-  TileData tile_data;
-  TileNumber last_tile_number;
-  PartialUpdateRegion changed_region;
+  ImageUser *image_user;
 
- private:
-  ePartialUpdateCollectResult collect_result;
+  /**
+   * \brief the collected changes are stored inside the PartialUpdateUser.
+   */
+  PartialUpdateUser *user;
 
- public:
-  PartialUpdateCollectResult(Image *image,
-                             ImageUser image_user,
-                             PartialUpdateUser *user,
-                             ePartialUpdateCollectResult collect_result)
-      : image(image), user(user), tile_data(image, image_user), collect_result(collect_result)
-  {
-  }
+  struct CollectResult {
+    PartialUpdateChecker<TileData> *checker;
+
+    /**
+     * \brief Tile specific data.
+     */
+    TileData tile_data;
+    PartialUpdateRegion changed_region;
+    ePartialUpdateCollectResult result_code;
+
+   private:
+    TileNumber last_tile_number;
+
+   public:
+    CollectResult(PartialUpdateChecker<TileData> *checker, ePartialUpdateCollectResult result_code)
+        : checker(checker),
+          tile_data(checker->image, *checker->image_user),
+          result_code(result_code)
+    {
+    }
 
-  const ePartialUpdateCollectResult get_collect_result() const
-  {
-    return collect_result;
-  }
+    const ePartialUpdateCollectResult get_result_code() const
+    {
+      return result_code;
+    }
 
-  ePartialUpdateIterResult get_next_change()
-  {
-    BLI_assert(collect_result == ePartialUpdateCollectResult::PartialChangesDetected);
-    ePartialUpdateIterResult result = BKE_image_partial_update_get_next_change(user,
-                                                                               &changed_region);
-    switch (result) {
-      case ePartialUpdateIterResult::Finished:
-        tile_data.free_data();
-        return result;
-
-      case ePartialUpdateIterResult::ChangeAvailable:
-        if (last_tile_number == changed_region.tile_number) {
+    /**
+     * \brief Load the next changed region.
+     *
+     * This member function can only be called when partial changes are detected.
+     * (`get_result_code()` returns `ePartialUpdateCollectResult::PartialChangesDetected`).
+     *
+     * When changes for another tile than the previous tile is loaded the #tile_data will be
+     * updated.
+     */
+    ePartialUpdateIterResult get_next_change()
+    {
+      BLI_assert(result_code == ePartialUpdateCollectResult::PartialChangesDetected);
+      ePartialUpdateIterResult result = BKE_image_partial_update_get_next_change(checker->user,
+                                                                                 &changed_region);
+      switch (result) {
+        case ePartialUpdateIterResult::Finished:
+          tile_data.free_data();
           return result;
-        }
-        tile_data.free_data();
-        tile_data.init_data(changed_region.tile_number);
-        last_tile_number = changed_region.tile_number;
-        return result;
-
-        ;
-      default:
-        BLI_assert_unreachable();
-        return result;
-    }
-  }
-};
 
-template<typename TileData = NoTileData> class PartialUpdateChecker {
+        case ePartialUpdateIterResult::ChangeAvailable:
+          if (last_tile_number == changed_region.tile_number) {
+            return result;
+          }
+          tile_data.free_data();
+          tile_data.init_data(changed_region.tile_number);
+          last_tile_number = changed_region.tile_number;
+          return result;
 
-  Image *image;
-  ImageUser *image_user;
-  PartialUpdateUser *user;
+        default:
+          BLI_assert_unreachable();
+          return result;
+      }
+    }
+  };
 
  public:
   PartialUpdateChecker(Image *image, ImageUser *image_user, PartialUpdateUser *user)
@@ -219,11 +280,14 @@ template<typename TileData = NoTileData> class PartialUpdateChecker {
   {
   }
 
-  PartialUpdateCollectResult<TileData> collect_changes()
+  /**
+   * \brief Check for new changes since the last time this method was invoked for this #user.
+   */
+  CollectResult collect_changes()
   {
     ePartialUpdateCollectResult collect_result = BKE_image_partial_update_collect_changes(image,
                                                                                           user);
-    return PartialUpdateCollectResult<TileData>(image, *image_user, user, collect_result);
+    return CollectResult(this, collect_result);
   }
 };