diff options
author | Jeroen Bakker <jeroen@blender.org> | 2021-11-26 15:29:18 +0300 |
---|---|---|
committer | Jeroen Bakker <jeroen@blender.org> | 2021-11-26 15:29:18 +0300 |
commit | 6cda987f592409689a384226b03a49fc32648530 (patch) | |
tree | a32afd9353e1e53e8e42eef03a10126aaae167f9 /source/blender/blenkernel/BKE_image_partial_update.hh | |
parent | b30f101fc0865322bfc4451c54397075a8e02c16 (diff) |
Added API documentation.temp-gpu-texture-partial-updates
Diffstat (limited to 'source/blender/blenkernel/BKE_image_partial_update.hh')
-rw-r--r-- | source/blender/blenkernel/BKE_image_partial_update.hh | 200 |
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); } }; |