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

   1 #ifndef DALI_TOOLKIT_TEXTURE_MANAGER_TYPE_H
   2 #define DALI_TOOLKIT_TEXTURE_MANAGER_TYPE_H
   3
   4 /*
   5  * Copyright (c) 2024 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/devel-api/adaptor-framework/animated-image-loading.h>
  22 #include <dali/public-api/common/dali-vector.h>
  23 #include <dali/public-api/math/vector4.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/devel-api/image-loader/image-atlas.h>
  27 #include <dali-toolkit/internal/texture-manager/texture-upload-observer.h>
  28 #include <dali-toolkit/internal/visuals/visual-url.h>
  29
  30 namespace Dali
  31 {
  32 namespace Toolkit
  33 {
  34 namespace Internal
  35 {
  36 /**
  37  * @brief Define common type, enum, and struct that both TextureManager and TextureCacheManager will use.
  38  */
  39 namespace TextureManagerType
  40 {
  41 // Enum!
  42
  43 enum TextureCacheIndexType
  44 {
  45   TEXTURE_CACHE_INDEX_FREE_LIST  = 0, ///< Only for FreeList. We should not use this for TextureCacheIndex.
  46   TEXTURE_CACHE_INDEX_TYPE_LOCAL = 1,
  47   TEXTURE_CACHE_INDEX_TYPE_TEXTURE,
  48   TEXTURE_CACHE_INDEX_TYPE_BUFFER,
  49   TEXTURE_CACHE_INDEX_TYPE_MASKING, ///< Not implemented yet.
  50   TEXTURE_CACHE_INDEX_TYPE_MAX = 7, ///< Maximum number of cache type we can use.
  51 };
  52
  53 // Union!
  54
  55 /**
  56  * @brief standard union type of texture index.
  57  * Due to the FreeList can only use for uint32_t and we need to seperate
  58  * each index per container type, we can only hold maximum 2^28 textures
  59  * at the same time.
  60  *      0 ~   2^28 - 1 : index of FreeList. TextureCacheManager will not use it.
  61  *   2^28 ~ 2*2^28 - 1 : index of mTextureInfoContainer, the main texture container.
  62  * 2*2^28 ~ 3*2^28 - 1 : index of mExternalTextures.
  63  * 3*2^28 ~ 4*2^28 - 1 : index of mEncodedBufferTextures.
  64  */
  65 union TextureCacheIndexData
  66 {
  67   TextureCacheIndexData() = default;
  68   constexpr TextureCacheIndexData(const uint32_t index)
  69   : indexValue(index)
  70   {
  71   }
  72   constexpr explicit TextureCacheIndexData(const int32_t index)
  73   : indexValue(static_cast<uint32_t>(index))
  74   {
  75   }
  76   constexpr TextureCacheIndexData(const TextureCacheIndexType& type, const uint32_t index)
  77   : detailValue{index, type}
  78   {
  79   }
  80   constexpr TextureCacheIndexData(const TextureCacheIndexData& indexData)
  81   : indexValue(indexData.indexValue)
  82   {
  83   }
  84   constexpr TextureCacheIndexData(TextureCacheIndexData&& indexData)
  85   : indexValue(indexData.indexValue)
  86   {
  87   }
  88
  89   TextureCacheIndexData& operator=(const uint32_t index)
  90   {
  91     indexValue = index;
  92     return *this;
  93   }
  94   TextureCacheIndexData& operator=(const TextureCacheIndexData& rhs)
  95   {
  96     indexValue = rhs.indexValue;
  97     return *this;
  98   }
  99   TextureCacheIndexData& operator=(TextureCacheIndexData&& rhs)
 100   {
 101     indexValue = rhs.indexValue;
 102     return *this;
 103   }
 104
 105   constexpr operator uint32_t() const
 106   {
 107     return indexValue;
 108   }
 109   constexpr operator uint32_t()
 110   {
 111     return indexValue;
 112   }
 113   constexpr explicit operator int32_t() const
 114   {
 115     return static_cast<int32_t>(indexValue);
 116   }
 117   constexpr explicit operator int32_t()
 118   {
 119     return static_cast<int32_t>(indexValue);
 120   }
 121
 122   // Return detailValue.index. - the real index of datailValue.type container
 123   constexpr inline uint32_t GetIndex() const
 124   {
 125     return detailValue.index;
 126   }
 127
 128   inline constexpr bool operator==(const TextureCacheIndexData& rhs)
 129   {
 130     return indexValue == rhs.indexValue;
 131   }
 132   inline constexpr bool operator<(const TextureCacheIndexData& rhs)
 133   {
 134     return indexValue < rhs.indexValue;
 135   }
 136
 137   // Data area
 138   uint32_t indexValue;
 139   struct
 140   {
 141     unsigned int          index : 28;
 142     TextureCacheIndexType type : 4;
 143   } detailValue;
 144 };
 145
 146 // Typedef:
 147
 148 typedef int32_t               TextureId;         ///< The TextureId type. This is used as a handle to refer to a particular Texture.
 149 typedef TextureCacheIndexData TextureCacheIndex; ///< The TextureCacheIndex type. This is used as a handles to refer to a particular Texture in TextureCacheManager.
 150                                                  ///  Note : For the same Texture, TextureId will not be changed. But TextureCacheIndex can be chaged when TextureCacheManager
 151                                                  ///  Internal container informations changed by Append or Remove.
 152 typedef size_t TextureHash;                      ///< The type used to store the hash used for Texture caching.
 153
 154 // Constant values:
 155
 156 static constexpr TextureId         INVALID_TEXTURE_ID  = -1; ///< Used to represent a null TextureId or error
 157 static constexpr TextureCacheIndex INVALID_CACHE_INDEX = 0;  ///< Used to represent a null TextureCacheIndex or error
 158
 159 // Enum classes:
 160
 161 /**
 162  * Whether the pixel data should be kept in TextureManager, returned with pixelBuffer or uploaded for rendering
 163  */
 164 enum class StorageType
 165 {
 166   KEEP_PIXEL_BUFFER,   ///< Keep loaded pixel buffer inside of texture manager without making texture. This could be used for inside pixel process like mask image.
 167   RETURN_PIXEL_BUFFER, ///< Return loaded pixel buffer without making texture.
 168                        ///  Because a pixel buffer cannot be used multiple texture, this pixel buffer only cached during loading, and is removed after loading is finished.
 169   KEEP_TEXTURE,        ///< Keep loaded texture inside of texture manager. This could be used for pixel processing like GPU masking.
 170   UPLOAD_TO_TEXTURE    ///< Loaded image will be uploaded to texture and the texture will be returned.
 171 };
 172
 173 /**
 174  * @brief The LoadState Enumeration represents the current state of a particular Texture's life-cycle.
 175  */
 176 enum class LoadState
 177 {
 178   NOT_STARTED,      ///< Default
 179   LOADING,          ///< Loading has been started, but not finished.
 180   LOAD_FINISHED,    ///< Loading has finished. (for CPU storage only)
 181   WAITING_FOR_MASK, ///< Loading has finished, but waiting for mask image
 182   MASK_APPLYING,    ///< Loading has finished, Mask is applying
 183   MASK_APPLIED,     ///< Loading has finished, Mask is applyied by GPU
 184   UPLOADED,         ///< Uploaded and ready. (For GPU upload only)
 185   CANCELLED,        ///< Removed before loading completed
 186   MASK_CANCELLED,   ///< Removed before mask applying completed
 187   LOAD_FAILED       ///< Async loading failed, e.g. connection problem
 188 };
 189
 190 /**
 191  * @brief Types of reloading policies
 192  */
 193 enum class ReloadPolicy
 194 {
 195   CACHED = 0, ///< Loads cached texture if it exists.
 196   FORCED      ///< Forces reloading of texture.
 197 };
 198
 199 /**
 200  * @brief Whether to multiply alpha into color channels on load
 201  */
 202 enum class MultiplyOnLoad
 203 {
 204   LOAD_WITHOUT_MULTIPLY = 0, ///< Don't modify the image
 205   MULTIPLY_ON_LOAD           ///< Multiply alpha into color channels on load
 206 };
 207
 208 // Structs:
 209
 210 /**
 211  * @brief This struct is used to manage the life-cycle of Texture loading and caching.
 212  */
 213 struct TextureInfo
 214 {
 215   TextureInfo(const TextureId                   textureId,
 216               const TextureId                   maskTextureId,
 217               const VisualUrl&                  url,
 218               const Dali::ImageDimensions&      desiredSize,
 219               const float                       scaleFactor,
 220               const Dali::FittingMode::Type     fittingMode,
 221               const Dali::SamplingMode::Type    samplingMode,
 222               const bool                        loadSynchronously,
 223               const bool                        cropToMask,
 224               const TextureHash                 hash,
 225               const bool                        orientationCorrection,
 226               const bool                        preMultiplyOnLoad,
 227               const Dali::AnimatedImageLoading& animatedImageLoading,
 228               const uint32_t                    frameIndex,
 229               const bool                        loadYuvPlanes)
 230   : url(url),
 231     desiredSize(desiredSize),
 232     useSize(desiredSize),
 233     textureId(textureId),
 234     maskTextureId(maskTextureId),
 235     hash(hash),
 236     scaleFactor(scaleFactor),
 237     referenceCount(1),
 238     loadState(LoadState::NOT_STARTED),
 239     fittingMode(fittingMode),
 240     samplingMode(samplingMode),
 241     storageType(StorageType::UPLOAD_TO_TEXTURE),
 242     animatedImageLoading(animatedImageLoading),
 243     frameIndex(frameIndex),
 244     frameCount(0u),
 245     frameInterval(0u),
 246     loadSynchronously(loadSynchronously),
 247     cropToMask(cropToMask),
 248     orientationCorrection(true),
 249     preMultiplyOnLoad(preMultiplyOnLoad),
 250     preMultiplied(preMultiplyOnLoad),
 251     loadYuvPlanes(loadYuvPlanes)
 252   {
 253     isAnimatedImageFormat = (animatedImageLoading) ? true : false;
 254   }
 255
 256   /**
 257    * Container type used to store all observer clients of this Texture
 258    */
 259   typedef Dali::Vector<TextureUploadObserver*> ObserverListType;
 260
 261   ObserverListType           observerList;         ///< Container used to store all observer clients of this Texture
 262   Dali::Devel::PixelBuffer   pixelBuffer;          ///< The PixelBuffer holding the image data (May be empty after upload)
 263   std::vector<Dali::Texture> textures;             ///< The Textures
 264   VisualUrl                  url;                  ///< The URL of the image
 265   Dali::ImageDimensions      desiredSize;          ///< The size requested
 266   Dali::ImageDimensions      useSize;              ///< The size used
 267   TextureId                  textureId;            ///< The TextureId associated with this Texture
 268   TextureId                  maskTextureId;        ///< The mask TextureId to be applied on load
 269   TextureHash                hash;                 ///< The hash used to cache this Texture
 270   float                      scaleFactor;          ///< The scale factor to apply to the Texture when masking
 271   int32_t                    referenceCount;       ///< The reference count of clients using this Texture
 272   LoadState                  loadState;            ///< The load state showing the load progress of the Texture
 273   Dali::FittingMode::Type    fittingMode : 3;      ///< The requested FittingMode
 274   Dali::SamplingMode::Type   samplingMode : 3;     ///< The requested SamplingMode
 275   StorageType                storageType;          ///< CPU storage / GPU upload;
 276   Dali::AnimatedImageLoading animatedImageLoading; ///< AnimatedImageLoading that contains animated image information.
 277   uint32_t                   frameIndex;           ///< Frame index that be loaded, in case of animated image
 278   uint32_t                   frameCount;           ///< Total frame count of input animated image. If this variable is not 0, this textureInfo is for animated image file format.
 279   uint32_t                   frameInterval;        ///< Time interval between this frame and next frame of animated image.
 280
 281   bool loadSynchronously : 1;     ///< True if synchronous loading was requested
 282   bool cropToMask : 1;            ///< True if the image should be cropped to the mask size.
 283   bool orientationCorrection : 1; ///< True if the image should be rotated to match exif orientation data
 284   bool preMultiplyOnLoad : 1;     ///< True if the image's color should be multiplied by it's alpha
 285   bool preMultiplied : 1;         ///< True if the image's color was multiplied by it's alpha
 286   bool isAnimatedImageFormat : 1; ///< true if the image is requested from animated image visual.
 287   bool loadYuvPlanes : 1;         ///< true if the image should be loaded as yuv planes
 288 };
 289
 290 /**
 291  * @brief This struct is used to manage the life-cycle of ExternalTexture url.
 292  */
 293 struct ExternalTextureInfo
 294 {
 295   ExternalTextureInfo(const TextureId   textureId,
 296                       const TextureSet& textureSet,
 297                       const bool        preMultiplied)
 298   : textureId(textureId),
 299     textureSet(textureSet),
 300     referenceCount(1),
 301     preMultiplied(preMultiplied)
 302   {
 303   }
 304
 305   TextureId  textureId;         ///< The TextureId associated with this ExternalTexture
 306   TextureSet textureSet;        ///< The external texture
 307   int32_t    referenceCount;    ///< The reference count of clients using this ExternalTexture
 308   bool       preMultiplied : 1; ///< True if the image's color was multiplied by it's alpha
 309 };
 310
 311 } // namespace TextureManagerType
 312
 313 } // namespace Internal
 314
 315 } // namespace Toolkit
 316
 317 } // namespace Dali
 318
 319 #endif // DALI_TOOLKIT_TEXTURE_MANAGER_TYPE_H