1 #ifndef DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H
2 #define DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
21 #include <dali/public-api/adaptor-framework/encoded-image-buffer.h>
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>
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.
40 * Also, You can store external TextureSet or EncodedImageBuffer here.
42 class TextureCacheManager
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;
50 static constexpr TextureId INVALID_TEXTURE_ID = TextureManagerType::INVALID_TEXTURE_ID;
51 static constexpr TextureCacheIndex INVALID_CACHE_INDEX = TextureManagerType::INVALID_CACHE_INDEX;
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;
65 TextureCacheManager();
70 ~TextureCacheManager();
73 // TextureCacheManager Main API:
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.
80 VisualUrl GetVisualUrl(const TextureCacheManager::TextureId& textureId);
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
88 TextureCacheManager::LoadState GetTextureState(const TextureCacheManager::TextureId& textureId);
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
96 TextureCacheManager::LoadState GetTextureStateInternal(const TextureCacheManager::TextureId& textureId);
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
103 TextureSet GetTextureSet(const TextureCacheManager::TextureId& textureId);
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
110 TextureSet GetExternalTextureSet(const TextureCacheManager::TextureId& textureId);
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
117 EncodedImageBuffer GetEncodedImageBuffer(const TextureCacheManager::TextureId& textureId);
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
124 EncodedImageBuffer GetEncodedImageBuffer(const std::string& url);
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
131 std::string AddExternalTexture(const TextureSet& texture);
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
138 std::string AddExternalEncodedImageBuffer(const EncodedImageBuffer& encodedImageBuffer);
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
145 TextureSet RemoveExternalTexture(const std::string& url);
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
152 EncodedImageBuffer RemoveExternalEncodedImageBuffer(const std::string& url);
155 * @brief Notify that external textures or external encoded image buffers are used.
156 * @param[in] url The URL of the texture to use.
158 void UseExternalResource(const VisualUrl& url);
161 // To Generate / Get / Remove TextureId.
164 * @brief Generates a new, unique TextureId
165 * @return A unique TextureId
167 TextureCacheManager::TextureId GenerateUniqueTextureId();
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
174 TextureCacheManager::TextureCacheIndex GetCacheIndexFromId(const TextureCacheManager::TextureId& textureId);
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 * @param[in] cropToMask True if crop to mask
188 * @return A hash of the provided data for caching.
190 TextureCacheManager::TextureHash GenerateHash(
191 const std::string& url,
192 const Dali::ImageDimensions& size,
193 const Dali::FittingMode::Type& fittingMode,
194 const Dali::SamplingMode::Type& samplingMode,
195 const TextureCacheManager::UseAtlas& useAtlas,
196 const TextureCacheManager::TextureId& maskTextureId,
197 const bool& cropToMask);
200 * @brief Looks up a cached texture by its hash.
201 * If found, the given parameters are used to check there is no hash-collision.
202 * @param[in] hash The hash to look up
203 * @param[in] url The URL of the image to load
204 * @param[in] size The image size
205 * @param[in] fittingMode The FittingMode to use
206 * @param[in] samplingMode The SamplingMode to use
207 * @param[in] useAtlas True if atlased
208 * @param[in] maskTextureId Optional texture ID to use to mask this image
209 * @param[in] preMultiplyOnLoad If the image's color should be multiplied by it's alpha. Set to OFF if there is no alpha.
210 * @param[in] isAnimatedImage True if the texture is from animated image.
211 * @param[in] cropToMask True if crop to mask
212 * @return A TextureCacheId of a cached Texture if found. Or INVALID_CACHE_INDEX if not found.
214 TextureCacheManager::TextureCacheIndex FindCachedTexture(
215 const TextureCacheManager::TextureHash& hash,
216 const std::string& url,
217 const Dali::ImageDimensions& size,
218 const Dali::FittingMode::Type& fittingMode,
219 const Dali::SamplingMode::Type& samplingMode,
220 const TextureCacheManager::UseAtlas& useAtlas,
221 const TextureCacheManager::TextureId& maskTextureId,
222 const TextureCacheManager::MultiplyOnLoad& preMultiplyOnLoad,
223 bool isAnimatedImage,
224 const bool& cropToMask);
227 * @brief Append a Texture to the TextureCacheManager.
228 * @note This API doesn't check duplication of TextureId.
230 * @param[in] textureInfo TextureInfo that want to cache in container.
231 * @return Index of newly appended texture info.
233 TextureCacheManager::TextureCacheIndex AppendCache(const TextureCacheManager::TextureInfo& textureInfo);
236 * @brief Remove a Texture from the TextureCacheManager.
238 * Textures are cached and therefore only the removal of the last
239 * occurrence of a Texture will cause its removal internally.
241 * @param[in] textureId The Id of the Texture to remove at Cache.
243 void RemoveCache(const TextureCacheManager::TextureId& textureId);
247 * @brief Get TextureInfo as TextureCacheIndex.
248 * @note This API doesn't consider external & encodedimagebuffer.
249 * @param[in] textureCacheIndex Index of cahced texture.
250 * @return TextureInfo as textureCacheIndex
252 inline TextureCacheManager::TextureInfo& operator[](const TextureCacheManager::TextureCacheIndex& textureCacheIndex) noexcept
254 return mTextureInfoContainer[textureCacheIndex];
258 * @brief The number of associated cached image
259 * @note This API doesn't consider external & encodedimagebuffer.
260 * @return The number of associated cached image
262 inline std::size_t size() noexcept
264 return mTextureInfoContainer.size();
268 // Private defined structs.
270 struct ExternalTextureInfo
272 ExternalTextureInfo(const TextureCacheManager::TextureId& textureId,
273 const TextureSet& textureSet)
274 : textureId(textureId),
275 textureSet(textureSet),
279 TextureCacheManager::TextureId textureId;
280 TextureSet textureSet;
281 std::int16_t referenceCount;
284 struct EncodedBufferTextureInfo
286 EncodedBufferTextureInfo(const TextureCacheManager::TextureId& textureId,
287 const EncodedImageBuffer& encodedImageBuffer)
288 : textureId(textureId),
289 encodedImageBuffer(encodedImageBuffer),
293 TextureCacheManager::TextureId textureId;
294 EncodedImageBuffer encodedImageBuffer;
295 std::int16_t referenceCount;
298 typedef std::vector<TextureCacheManager::TextureInfo> TextureInfoContainerType; ///< The container type used to manage the life-cycle and caching of Textures
299 typedef std::vector<TextureCacheManager::ExternalTextureInfo> ExternalTextureInfoContainerType; ///< The container type used to manage the life-cycle and caching of Textures
300 typedef std::vector<TextureCacheManager::EncodedBufferTextureInfo> EncodedBufferTextureInfoContainerType; ///< The container type used to manage the life-cycle and caching of Textures
304 * Deleted copy constructor.
306 TextureCacheManager(const TextureCacheManager&) = delete;
309 * Deleted assignment operator.
311 TextureCacheManager& operator=(const TextureCacheManager& rhs) = delete;
313 private: // Member Variables:
314 TextureInfoContainerType mTextureInfoContainer{}; ///< Used to manage the life-cycle and caching of Textures
315 ExternalTextureInfoContainerType mExternalTextures{}; ///< Externally provided textures
316 EncodedBufferTextureInfoContainerType mEncodedBufferTextures{}; ///< Externally encoded buffer textures
317 TextureCacheManager::TextureId mCurrentTextureId; ///< The current value used for the unique Texture Id generation
320 } // namespace Internal
322 } // namespace Toolkit
326 #endif // DALI_TOOLKIT_TEXTURE_CACHE_MANAGER_H