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) 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/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 std::uint32_t& index)
  69   : indexValue(index)
  70   {
  71   }
  72   constexpr explicit TextureCacheIndexData(const std::int32_t& index)
  73   : indexValue(static_cast<std::uint32_t>(index))
  74   {
  75   }
  76   constexpr TextureCacheIndexData(const TextureCacheIndexType& type, const std::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 std::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 std::uint32_t() const
 106   {
 107     return indexValue;
 108   }
 109   constexpr operator std::uint32_t()
 110   {
 111     return indexValue;
 112   }
 113   constexpr explicit operator std::int32_t() const
 114   {
 115     return static_cast<std::int32_t>(indexValue);
 116   }
 117   constexpr explicit operator std::int32_t()
 118   {
 119     return static_cast<std::int32_t>(indexValue);
 120   }
 121
 122   // Return detailValue.index. - the real index of datailValue.type container
 123   constexpr inline std::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   std::uint32_t indexValue;
 139   struct
 140   {
 141     unsigned int          index : 28;
 142     TextureCacheIndexType type : 4;
 143   } detailValue;
 144 };
 145
 146 // Typedef:
 147
 148 typedef std::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 std::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 texture should be atlased or uploaded into it's own GPU texture
 163  */
 164 enum class UseAtlas
 165 {
 166   NO_ATLAS,
 167   USE_ATLAS
 168 };
 169
 170 /**
 171  * Whether the pixel data should be kept in TextureManager, returned with pixelBuffer or uploaded for rendering
 172  */
 173 enum class StorageType
 174 {
 175   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.
 176   RETURN_PIXEL_BUFFER, ///< Return loaded pixel buffer without making texture.
 177                        ///  Because a pixel buffer cannot be used multiple texture, this pixel buffer only cached during loading, and is removed after loading is finished.
 178   UPLOAD_TO_TEXTURE    ///< Loaded image will be uploaded to texture and the texture will be returned.
 179 };
 180
 181 /**
 182  * Whether the texture should be loaded synchronously or asynchronously.
 183  */
 184 enum class LoadType
 185 {
 186   LOAD_ASYNCHRONOUSLY,
 187   LOAD_SYNCHRONOUSLY
 188 };
 189
 190 /**
 191  * @brief The LoadState Enumeration represents the current state of a particular Texture's life-cycle.
 192  */
 193 enum class LoadState
 194 {
 195   NOT_STARTED,      ///< Default
 196   LOADING,          ///< Loading has been started, but not finished.
 197   LOAD_FINISHED,    ///< Loading has finished. (for CPU storage only)
 198   WAITING_FOR_MASK, ///< Loading has finished, but waiting for mask image
 199   MASK_APPLYING,    ///< Loading has finished, Mask is applying
 200   MASK_APPLIED,     ///< Loading has finished, Mask is applyied by GPU
 201   UPLOADED,         ///< Uploaded and ready. (For GPU upload only)
 202   CANCELLED,        ///< Removed before loading completed
 203   LOAD_FAILED       ///< Async loading failed, e.g. connection problem
 204 };
 205
 206 /**
 207  * @brief Types of reloading policies
 208  */
 209 enum class ReloadPolicy
 210 {
 211   CACHED = 0, ///< Loads cached texture if it exists.
 212   FORCED      ///< Forces reloading of texture.
 213 };
 214
 215 /**
 216  * @brief Whether to multiply alpha into color channels on load
 217  */
 218 enum class MultiplyOnLoad
 219 {
 220   LOAD_WITHOUT_MULTIPLY = 0, ///< Don't modify the image
 221   MULTIPLY_ON_LOAD           ///< Multiply alpha into color channels on load
 222 };
 223
 224 // Structs:
 225
 226 /**
 227  * @brief This struct is used to manage the life-cycle of Texture loading and caching.
 228  */
 229 struct TextureInfo
 230 {
 231   TextureInfo(const TextureId&                  textureId,
 232               const TextureId&                  maskTextureId,
 233               const VisualUrl&                  url,
 234               const Dali::ImageDimensions&      desiredSize,
 235               const float&                      scaleFactor,
 236               const Dali::FittingMode::Type&    fittingMode,
 237               const Dali::SamplingMode::Type&   samplingMode,
 238               const bool&                       loadSynchronously,
 239               const bool&                       cropToMask,
 240               const UseAtlas&                   useAtlas,
 241               const TextureHash&                hash,
 242               const bool&                       orientationCorrection,
 243               const bool&                       preMultiplyOnLoad,
 244               const Dali::AnimatedImageLoading& animatedImageLoading,
 245               const std::uint32_t&              frameIndex)
 246   : url(url),
 247     desiredSize(desiredSize),
 248     useSize(desiredSize),
 249     atlasRect(0.0f, 0.0f, 1.0f, 1.0f), // Full atlas rectangle
 250     textureId(textureId),
 251     maskTextureId(maskTextureId),
 252     hash(hash),
 253     scaleFactor(scaleFactor),
 254     referenceCount(1u),
 255     loadState(LoadState::NOT_STARTED),
 256     fittingMode(fittingMode),
 257     samplingMode(samplingMode),
 258     storageType(StorageType::UPLOAD_TO_TEXTURE),
 259     animatedImageLoading(animatedImageLoading),
 260     frameIndex(frameIndex),
 261     frameCount(0u),
 262     frameInterval(0u),
 263     useAtlas(useAtlas),
 264     loadSynchronously(loadSynchronously),
 265     cropToMask(cropToMask),
 266     orientationCorrection(true),
 267     preMultiplyOnLoad(preMultiplyOnLoad),
 268     preMultiplied(false)
 269   {
 270     isAnimatedImageFormat = (animatedImageLoading) ? true : false;
 271   }
 272
 273   /**
 274    * Container type used to store all observer clients of this Texture
 275    */
 276   typedef Dali::Vector<TextureUploadObserver*> ObserverListType;
 277
 278   ObserverListType           observerList;         ///< Container used to store all observer clients of this Texture
 279   Dali::Toolkit::ImageAtlas  atlas;                ///< The atlas this Texture lays within (if any)
 280   Dali::Devel::PixelBuffer   pixelBuffer;          ///< The PixelBuffer holding the image data (May be empty after upload)
 281   Dali::TextureSet           textureSet;           ///< The TextureSet holding the Texture
 282   VisualUrl                  url;                  ///< The URL of the image
 283   Dali::ImageDimensions      desiredSize;          ///< The size requested
 284   Dali::ImageDimensions      useSize;              ///< The size used
 285   Dali::Vector4              atlasRect;            ///< The atlas rect used if atlased
 286   TextureId                  textureId;            ///< The TextureId associated with this Texture
 287   TextureId                  maskTextureId;        ///< The mask TextureId to be applied on load
 288   TextureHash                hash;                 ///< The hash used to cache this Texture
 289   float                      scaleFactor;          ///< The scale factor to apply to the Texture when masking
 290   std::int16_t               referenceCount;       ///< The reference count of clients using this Texture
 291   LoadState                  loadState;            ///< The load state showing the load progress of the Texture
 292   Dali::FittingMode::Type    fittingMode : 3;      ///< The requested FittingMode
 293   Dali::SamplingMode::Type   samplingMode : 3;     ///< The requested SamplingMode
 294   StorageType                storageType;          ///< CPU storage / GPU upload;
 295   Dali::AnimatedImageLoading animatedImageLoading; ///< AnimatedImageLoading that contains animated image information.
 296   uint32_t                   frameIndex;           ///< Frame index that be loaded, in case of animated image
 297   uint32_t                   frameCount;           ///< Total frame count of input animated image. If this variable is not 0, this textureInfo is for animated image file format.
 298   uint32_t                   frameInterval;        ///< Time interval between this frame and next frame of animated image.
 299   UseAtlas                   useAtlas;             ///< USE_ATLAS if an atlas was requested.
 300
 301   bool loadSynchronously : 1;     ///< True if synchronous loading was requested
 302   bool cropToMask : 1;            ///< True if the image should be cropped to the mask size.
 303   bool orientationCorrection : 1; ///< True if the image should be rotated to match exif orientation data
 304   bool preMultiplyOnLoad : 1;     ///< True if the image's color should be multiplied by it's alpha
 305   bool preMultiplied : 1;         ///< True if the image's color was multiplied by it's alpha
 306   bool isAnimatedImageFormat : 1; ///< true if the image is requested from animated image visual.
 307 };
 308
 309 } // namespace TextureManagerType
 310
 311 } // namespace Internal
 312
 313 } // namespace Toolkit
 314
 315 } // namespace Dali
 316
 317 #endif // DALI_TOOLKIT_TEXTURE_MANAGER_TYPE_H