dali-toolkit/internal/texture-manager/texture-cache-manager.h

   1 #ifndef DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H
   2 #define DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H
   3
   4 /*
   5  * Copyright (c) 2022 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 // EXTERNAL INCLUDES
  21 #include <dali/public-api/adaptor-framework/encoded-image-buffer.h>
  22
  23 // INTERNAL INCLUDES
  24 #include <dali-toolkit/internal/texture-manager/texture-manager-type.h>
  25 #include <dali-toolkit/internal/texture-manager/texture-upload-observer.h>
  26 #include <dali-toolkit/internal/visuals/visual-url.h>
  27
  28 namespace Dali
  29 {
  30 namespace Toolkit
  31 {
  32 namespace Internal
  33 {
  34 /**
  35  * @brief The contain and managing cached textures.
  36  * Each Texture hold there TextureId. These TextureId can be used outside of TextureManager.
  37  * Internally, each cached texture can be accessed by TextureCacheIndex.
  38  * You can Convert TextureId into TextureCacheIndex by this class.
  39  *
  40  * Also, You can store external TextureSet or EncodedImageBuffer here.
  41  */
  42 class TextureCacheManager
  43 {
  44 public:
  45   // Copy enum and types and const values that TextureCacheManager will use.
  46   using TextureId         = TextureManagerType::TextureId;
  47   using TextureCacheIndex = TextureManagerType::TextureCacheIndex;
  48   using TextureHash       = TextureManagerType::TextureHash;
  49
  50   static constexpr TextureId         INVALID_TEXTURE_ID  = TextureManagerType::INVALID_TEXTURE_ID;
  51   static constexpr TextureCacheIndex INVALID_CACHE_INDEX = TextureManagerType::INVALID_CACHE_INDEX;
  52
  53   using UseAtlas       = TextureManagerType::UseAtlas;
  54   using StorageType    = TextureManagerType::StorageType;
  55   using LoadType       = TextureManagerType::LoadType;
  56   using LoadState      = TextureManagerType::LoadState;
  57   using ReloadPolicy   = TextureManagerType::ReloadPolicy;
  58   using MultiplyOnLoad = TextureManagerType::MultiplyOnLoad;
  59   using TextureInfo    = TextureManagerType::TextureInfo;
  60
  61 public:
  62   /**
  63    * Constructor.
  64    */
  65   TextureCacheManager();
  66
  67   /**
  68    * Destructor.
  69    */
  70   ~TextureCacheManager();
  71
  72 public:
  73   // TextureCacheManager Main API:
  74
  75   /**
  76    * @brief Get the visualUrl associated with the texture id.
  77    * @param[in] textureId The texture Id to get
  78    * @return The visual Url associated with the texture id.
  79    */
  80   VisualUrl GetVisualUrl(const TextureCacheManager::TextureId& textureId);
  81
  82   /**
  83    * @brief Get the current state of a texture
  84    * @param[in] textureId The texture id to query
  85    * @return The loading state if the texture is valid, or NOT_STARTED if the textureId
  86    * is not valid.
  87    */
  88   TextureCacheManager::LoadState GetTextureState(const TextureCacheManager::TextureId& textureId);
  89
  90   /**
  91    * @brief Get the current state of a texture
  92    * @param[in] textureId The texture id to query
  93    * @return The loading state if the texture is valid, or NOT_STARTED if the textureId
  94    * is not valid.
  95    */
  96   TextureCacheManager::LoadState GetTextureStateInternal(const TextureCacheManager::TextureId& textureId);
  97
  98   /**
  99    * @brief Get the associated texture set if the texture id is valid
 100    * @param[in] textureId The texture Id to look up
 101    * @return the associated texture set, or an empty handle if textureId is not valid
 102    */
 103   TextureSet GetTextureSet(const TextureCacheManager::TextureId& textureId);
 104
 105   /**
 106    * @brief Get the external texture set if the texture id is valid
 107    * @param[in] textureId The texture Id to look up
 108    * @return the external texture set, or an empty handle if textureId is not valid
 109    */
 110   TextureSet GetExternalTextureSet(const TextureCacheManager::TextureId& textureId);
 111
 112   /**
 113    * @brief Get the encoded image buffer
 114    * @param[in] textureId The textureId to look up
 115    * @return the encoded image buffer, or an empty handle if textureId is not valid
 116    */
 117   EncodedImageBuffer GetEncodedImageBuffer(const TextureCacheManager::TextureId& textureId);
 118
 119   /**
 120    * @brief Get the encoded image buffer by VisualUrl
 121    * @param[in] url The url to look up
 122    * @return the encoded image buffer, or an empty handle if url is not buffer resource or buffer is not valid
 123    */
 124   EncodedImageBuffer GetEncodedImageBuffer(const std::string& url);
 125
 126   /**
 127    * Adds an external texture to the texture manager
 128    * @param[in] texture The texture to add
 129    * @return string containing the URL for the texture
 130    */
 131   std::string AddExternalTexture(const TextureSet& texture);
 132
 133   /**
 134    * Adds an external encoded image buffer to the texture manager
 135    * @param[in] encodedImageBuffer The image buffer to add
 136    * @return string containing the URL for the texture
 137    */
 138   std::string AddExternalEncodedImageBuffer(const EncodedImageBuffer& encodedImageBuffer);
 139
 140   /**
 141    * Removes an external texture from texture manager
 142    * @param[in] url The string containing the texture to remove
 143    * @return handle to the texture
 144    */
 145   TextureSet RemoveExternalTexture(const std::string& url);
 146
 147   /**
 148    * Removes an external encoded image buffer from texture manager
 149    * @param[in] url The string containing the encoded image buffer to remove
 150    * @return handle to the encoded image buffer
 151    */
 152   EncodedImageBuffer RemoveExternalEncodedImageBuffer(const std::string& url);
 153
 154   /**
 155    * @brief Notify that external textures or external encoded image buffers are used.
 156    * @param[in] url The URL of the texture to use.
 157    */
 158   void UseExternalResource(const VisualUrl& url);
 159
 160 public:
 161   // To Generate / Get / Remove TextureId.
 162
 163   /**
 164    * @brief Generates a new, unique TextureId
 165    * @return A unique TextureId
 166    */
 167   TextureCacheManager::TextureId GenerateUniqueTextureId();
 168
 169   /**
 170    * @brief Used to lookup an index into the TextureInfoContainer from a TextureId
 171    * @param[in] textureId The TextureId to look up
 172    * @return              The cache index
 173    */
 174   TextureCacheManager::TextureCacheIndex GetCacheIndexFromId(const TextureCacheManager::TextureId& textureId);
 175
 176   /**
 177    * @brief Generates a hash for caching based on the input parameters.
 178    * Only applies size, fitting mode andsampling mode if the size is specified.
 179    * Only applies maskTextureId if it isn't INVALID_TEXTURE_ID
 180    * Always applies useAtlas.
 181    * @param[in] url              The URL of the image to load
 182    * @param[in] size             The image size
 183    * @param[in] fittingMode      The FittingMode to use
 184    * @param[in] samplingMode     The SamplingMode to use
 185    * @param[in] useAtlas         True if atlased
 186    * @param[in] maskTextureId    The masking texture id (or INVALID_TEXTURE_ID)
 187    * @return                     A hash of the provided data for caching.
 188    */
 189   TextureCacheManager::TextureHash GenerateHash(
 190     const std::string&                    url,
 191     const Dali::ImageDimensions&          size,
 192     const Dali::FittingMode::Type&        fittingMode,
 193     const Dali::SamplingMode::Type&       samplingMode,
 194     const TextureCacheManager::UseAtlas&  useAtlas,
 195     const TextureCacheManager::TextureId& maskTextureId);
 196
 197   /**
 198    * @brief Looks up a cached texture by its hash.
 199    * If found, the given parameters are used to check there is no hash-collision.
 200    * @param[in] hash              The hash to look up
 201    * @param[in] url               The URL of the image to load
 202    * @param[in] size              The image size
 203    * @param[in] fittingMode       The FittingMode to use
 204    * @param[in] samplingMode      The SamplingMode to use
 205    * @param[in] useAtlas          True if atlased
 206    * @param[in] maskTextureId     Optional texture ID to use to mask this image
 207    * @param[in] preMultiplyOnLoad If the image's color should be multiplied by it's alpha. Set to OFF if there is no alpha.
 208    * @param[in] isAnimatedImage   True if the texture is from animated image.
 209    * @return                      A TextureCacheId of a cached Texture if found. Or INVALID_CACHE_INDEX if not found.
 210    */
 211   TextureCacheManager::TextureCacheIndex FindCachedTexture(
 212     const TextureCacheManager::TextureHash&    hash,
 213     const std::string&                         url,
 214     const Dali::ImageDimensions&               size,
 215     const Dali::FittingMode::Type&             fittingMode,
 216     const Dali::SamplingMode::Type&            samplingMode,
 217     const TextureCacheManager::UseAtlas&       useAtlas,
 218     const TextureCacheManager::TextureId&      maskTextureId,
 219     const TextureCacheManager::MultiplyOnLoad& preMultiplyOnLoad,
 220     bool                                       isAnimatedImage);
 221
 222   /**
 223    * @brief Append a Texture to the TextureCacheManager.
 224    * @note This API doesn't check duplication of TextureId.
 225    *
 226    * @param[in] textureInfo TextureInfo that want to cache in container.
 227    * @return Index of newly appended texture info.
 228    */
 229   TextureCacheManager::TextureCacheIndex AppendCache(const TextureCacheManager::TextureInfo& textureInfo);
 230
 231   /**
 232    * @brief Remove a Texture from the TextureCacheManager.
 233    *
 234    * Textures are cached and therefore only the removal of the last
 235    * occurrence of a Texture will cause its removal internally.
 236    *
 237    * @param[in] textureId The Id of the Texture to remove at Cache.
 238    */
 239   void RemoveCache(const TextureCacheManager::TextureId& textureId);
 240
 241 public:
 242   /**
 243    * @brief Get TextureInfo as TextureCacheIndex.
 244    * @note This API doesn't consider external & encodedimagebuffer.
 245    * @param[in] textureCacheIndex Index of cahced texture.
 246    * @return TextureInfo as textureCacheIndex
 247    */
 248   inline TextureCacheManager::TextureInfo& operator[](const TextureCacheManager::TextureCacheIndex& textureCacheIndex) noexcept
 249   {
 250     return mTextureInfoContainer[textureCacheIndex];
 251   }
 252
 253   /**
 254    * @brief The number of associated cached image
 255    * @note This API doesn't consider external & encodedimagebuffer.
 256    * @return The number of associated cached image
 257    */
 258   inline std::size_t size() noexcept
 259   {
 260     return mTextureInfoContainer.size();
 261   }
 262
 263 private:
 264   // Private defined structs.
 265
 266   struct ExternalTextureInfo
 267   {
 268     ExternalTextureInfo(const TextureCacheManager::TextureId& textureId,
 269                         const TextureSet&                     textureSet)
 270     : textureId(textureId),
 271       textureSet(textureSet),
 272       referenceCount(1u)
 273     {
 274     }
 275     TextureCacheManager::TextureId textureId;
 276     TextureSet                     textureSet;
 277     std::int16_t                   referenceCount;
 278   };
 279
 280   struct EncodedBufferTextureInfo
 281   {
 282     EncodedBufferTextureInfo(const TextureCacheManager::TextureId& textureId,
 283                              const EncodedImageBuffer&             encodedImageBuffer)
 284     : textureId(textureId),
 285       encodedImageBuffer(encodedImageBuffer),
 286       referenceCount(1u)
 287     {
 288     }
 289     TextureCacheManager::TextureId textureId;
 290     EncodedImageBuffer             encodedImageBuffer;
 291     std::int16_t                   referenceCount;
 292   };
 293
 294   typedef std::vector<TextureCacheManager::TextureInfo>              TextureInfoContainerType;              ///< The container type used to manage the life-cycle and caching of Textures
 295   typedef std::vector<TextureCacheManager::ExternalTextureInfo>      ExternalTextureInfoContainerType;      ///< The container type used to manage the life-cycle and caching of Textures
 296   typedef std::vector<TextureCacheManager::EncodedBufferTextureInfo> EncodedBufferTextureInfoContainerType; ///< The container type used to manage the life-cycle and caching of Textures
 297
 298 private:
 299   /**
 300    * Deleted copy constructor.
 301    */
 302   TextureCacheManager(const TextureCacheManager&) = delete;
 303
 304   /**
 305    * Deleted assignment operator.
 306    */
 307   TextureCacheManager& operator=(const TextureCacheManager& rhs) = delete;
 308
 309 private:                                                          // Member Variables:
 310   TextureInfoContainerType              mTextureInfoContainer{};  ///< Used to manage the life-cycle and caching of Textures
 311   ExternalTextureInfoContainerType      mExternalTextures{};      ///< Externally provided textures
 312   EncodedBufferTextureInfoContainerType mEncodedBufferTextures{}; ///< Externally encoded buffer textures
 313   TextureCacheManager::TextureId        mCurrentTextureId;        ///< The current value used for the unique Texture Id generation
 314 };
 315
 316 } // namespace Internal
 317
 318 } // namespace Toolkit
 319
 320 } // namespace Dali
 321
 322 #endif // DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H