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    * @return                      A TextureCacheId of a cached Texture if found. Or INVALID_CACHE_INDEX if not found.
 209    */
 210   TextureCacheManager::TextureCacheIndex FindCachedTexture(
 211     const TextureCacheManager::TextureHash&    hash,
 212     const std::string&                         url,
 213     const Dali::ImageDimensions&               size,
 214     const Dali::FittingMode::Type&             fittingMode,
 215     const Dali::SamplingMode::Type&            samplingMode,
 216     const TextureCacheManager::UseAtlas&       useAtlas,
 217     const TextureCacheManager::TextureId&      maskTextureId,
 218     const TextureCacheManager::MultiplyOnLoad& preMultiplyOnLoad);
 219
 220   /**
 221    * @brief Append a Texture to the TextureCacheManager.
 222    * @note This API doesn't check duplication of TextureId.
 223    *
 224    * @param[in] textureInfo TextureInfo that want to cache in container.
 225    * @return Index of newly appended texture info.
 226    */
 227   TextureCacheManager::TextureCacheIndex AppendCache(const TextureCacheManager::TextureInfo& textureInfo);
 228
 229   /**
 230    * @brief Remove a Texture from the TextureCacheManager.
 231    *
 232    * Textures are cached and therefore only the removal of the last
 233    * occurrence of a Texture will cause its removal internally.
 234    *
 235    * @param[in] textureId The Id of the Texture to remove at Cache.
 236    */
 237   void RemoveCache(const TextureCacheManager::TextureId& textureId);
 238
 239 public:
 240   /**
 241    * @brief Get TextureInfo as TextureCacheIndex.
 242    * @note This API doesn't consider external & encodedimagebuffer.
 243    * @param[in] textureCacheIndex Index of cahced texture.
 244    * @return TextureInfo as textureCacheIndex
 245    */
 246   inline TextureCacheManager::TextureInfo& operator[](const TextureCacheManager::TextureCacheIndex& textureCacheIndex) noexcept
 247   {
 248     return mTextureInfoContainer[textureCacheIndex];
 249   }
 250
 251   /**
 252    * @brief The number of associated cached image
 253    * @note This API doesn't consider external & encodedimagebuffer.
 254    * @return The number of associated cached image
 255    */
 256   inline std::size_t size() noexcept
 257   {
 258     return mTextureInfoContainer.size();
 259   }
 260
 261 private:
 262   // Private defined structs.
 263
 264   struct ExternalTextureInfo
 265   {
 266     ExternalTextureInfo(const TextureCacheManager::TextureId& textureId,
 267                         const TextureSet&                     textureSet)
 268     : textureId(textureId),
 269       textureSet(textureSet),
 270       referenceCount(1u)
 271     {
 272     }
 273     TextureCacheManager::TextureId textureId;
 274     TextureSet                     textureSet;
 275     std::int16_t                   referenceCount;
 276   };
 277
 278   struct EncodedBufferTextureInfo
 279   {
 280     EncodedBufferTextureInfo(const TextureCacheManager::TextureId& textureId,
 281                              const EncodedImageBuffer&             encodedImageBuffer)
 282     : textureId(textureId),
 283       encodedImageBuffer(encodedImageBuffer),
 284       referenceCount(1u)
 285     {
 286     }
 287     TextureCacheManager::TextureId textureId;
 288     EncodedImageBuffer             encodedImageBuffer;
 289     std::int16_t                   referenceCount;
 290   };
 291
 292   typedef std::vector<TextureCacheManager::TextureInfo>              TextureInfoContainerType;              ///< The container type used to manage the life-cycle and caching of Textures
 293   typedef std::vector<TextureCacheManager::ExternalTextureInfo>      ExternalTextureInfoContainerType;      ///< The container type used to manage the life-cycle and caching of Textures
 294   typedef std::vector<TextureCacheManager::EncodedBufferTextureInfo> EncodedBufferTextureInfoContainerType; ///< The container type used to manage the life-cycle and caching of Textures
 295
 296 private:
 297   /**
 298    * Deleted copy constructor.
 299    */
 300   TextureCacheManager(const TextureCacheManager&) = delete;
 301
 302   /**
 303    * Deleted assignment operator.
 304    */
 305   TextureCacheManager& operator=(const TextureCacheManager& rhs) = delete;
 306
 307 private:                                                          // Member Variables:
 308   TextureInfoContainerType              mTextureInfoContainer{};  ///< Used to manage the life-cycle and caching of Textures
 309   ExternalTextureInfoContainerType      mExternalTextures{};      ///< Externally provided textures
 310   EncodedBufferTextureInfoContainerType mEncodedBufferTextures{}; ///< Externally encoded buffer textures
 311   TextureCacheManager::TextureId        mCurrentTextureId;        ///< The current value used for the unique Texture Id generation
 312 };
 313
 314 } // namespace Internal
 315
 316 } // namespace Toolkit
 317
 318 } // namespace Dali
 319
 320 #endif // DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H