dali-toolkit/internal/text/rendering/atlas/atlas-manager.h

   1 #ifndef DALI_TOOLKIT_ATLAS_MANAGER_H
   2 #define DALI_TOOLKIT_ATLAS_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/common/dali-vector.h>
  22 #include <dali/public-api/rendering/texture-set.h>
  23 #include <stdint.h>
  24
  25 namespace Dali
  26 {
  27 namespace Toolkit
  28 {
  29 namespace Internal DALI_INTERNAL
  30 {
  31 class AtlasManager;
  32
  33 } // namespace DALI_INTERNAL
  34
  35 class AtlasManager : public BaseHandle
  36 {
  37 public:
  38   typedef uint32_t SizeType;
  39   typedef SizeType AtlasId;
  40   typedef SizeType ImageId;
  41
  42   struct AtlasSize
  43   {
  44     SizeType mWidth;       ///< width of the atlas in pixels
  45     SizeType mHeight;      ///< height of the atlas in pixels
  46     SizeType mBlockWidth;  ///< width of a block in pixels
  47     SizeType mBlockHeight; ///< height of a block in pixels
  48   };
  49
  50   /**
  51    * Metrics structures to describe Atlas Manager state
  52    *
  53    */
  54   struct AtlasMetricsEntry
  55   {
  56     AtlasSize     mSize;        ///< size of atlas and blocks
  57     SizeType      mBlocksUsed;  ///< number of blocks used in the atlas
  58     SizeType      mTotalBlocks; ///< total blocks used by atlas
  59     Pixel::Format mPixelFormat; ///< pixel format of the atlas
  60   };
  61
  62   struct Metrics
  63   {
  64     Metrics()
  65     : mAtlasCount(0u),
  66       mTextureMemoryUsed(0u)
  67     {
  68     }
  69
  70     ~Metrics()
  71     {
  72     }
  73
  74     SizeType                        mAtlasCount;        ///< number of atlases
  75     SizeType                        mTextureMemoryUsed; ///< texture memory used by atlases
  76     Dali::Vector<AtlasMetricsEntry> mAtlasMetrics;      ///< container of atlas information
  77   };
  78
  79   struct Vertex2D
  80   {
  81     Vector2 mPosition;  ///< Vertex posiiton
  82     Vector2 mTexCoords; ///< Vertex texture co-ordinates
  83     Vector4 mColor;     ///< Vertex color
  84   };
  85
  86   struct Mesh2D
  87   {
  88     Vector<Vertex2D>       mVertices; ///< container of vertices
  89     Vector<unsigned short> mIndices;  ///< container of indices
  90   };
  91
  92   /**
  93    * Create an AtlasManager handle; this can be initialised with AtlasManager::New()
  94    * Calling member functions with an uninitialised handle is not allowed.
  95    */
  96   AtlasManager();
  97
  98   /**
  99    * @brief Get new instance of AtlasManager object.
 100    *
 101    * @return A handle to the AtlasManager control.
 102    */
 103   static AtlasManager New();
 104
 105   /**
 106    * @brief Destructor
 107    *
 108    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 109    */
 110   ~AtlasManager();
 111
 112   /**
 113    * Policy on failing to add an image
 114    */
 115   enum AddFailPolicy
 116   {
 117     FAIL_ON_ADD_FAILS,
 118     FAIL_ON_ADD_CREATES
 119   };
 120
 121   /**
 122    * @brief Container to hold result of placing texture into atlas
 123    */
 124   struct AtlasSlot
 125   {
 126     ImageId mImageId; ///< Id of stored Image
 127     AtlasId mAtlasId; ///< Id of Atlas containing this slot
 128   };
 129
 130   typedef Dali::Vector<AtlasManager::AtlasSlot> slotContainer;
 131
 132   /**
 133    * @brief Create a blank atlas of specific dimensions and pixel format with a certain block size
 134    *
 135    * @param[in] size desired atlas dimensions
 136    * @param[in] pixelformat format of a pixel in atlas
 137    *
 138    * @return atlas Id
 139    */
 140   AtlasId CreateAtlas(const AtlasSize& size, Pixel::Format pixelformat = Pixel::RGBA8888);
 141
 142   /**
 143    * @brief Set the policy on failure to add an image to an atlas
 144    *
 145    * @param policy policy to carry out if add fails
 146    */
 147   void SetAddPolicy(AddFailPolicy policy);
 148
 149   /**
 150    * @brief Attempts to add an image to the most suitable atlas
 151    *
 152    * @details Add Policy may dictate that a new atlas is created if it can't presently be placed.
 153    *          If an add is made before an atlas is created under this policy,
 154    *          then a default size atlas will be created
 155    *
 156    * @param[in] image PixelData object containing the image data
 157    * @param[out] slot result of add operation
 158    * @param[in] atlas optional preferred atlas
 159    *
 160    * @return true if a new atlas was created
 161    */
 162   bool Add(const PixelData& image,
 163            AtlasSlot&       slot,
 164            AtlasId          atlas = 0);
 165
 166   /**
 167    * @brief Remove previously added bitmapimage from atlas
 168    *
 169    * @param[in] id ImageId returned in the AtlasSlot from the add operation
 170    *
 171    * @return if true then image has been removed from the atlas
 172    */
 173   bool Remove(ImageId id);
 174
 175   /**
 176    * @brief Generate mesh data for a previously added image
 177    *
 178    * @param[in] id Image Id returned in the AtlasSlot from the add operation
 179    * @param[in] position position of the resulting mesh in model space
 180    * @param[out] mesh Mesh Data Object to populate with mesh data
 181    * @param[in] addReference Whether to increase the internal reference count for image or not
 182    */
 183   void GenerateMeshData(ImageId        id,
 184                         const Vector2& position,
 185                         Mesh2D&        mesh,
 186                         bool           addReference = true);
 187
 188   /**
 189    * @brief Get the Texture containing an atlas
 190    *
 191    * @param[in] atlas AtlasId returned when atlas was created
 192    *
 193    * @return Atlas Handle
 194    */
 195   Dali::Texture GetAtlasContainer(AtlasId atlas) const;
 196
 197   /**
 198    * @brief Get the Id of the atlas containing an image
 199    *
 200    * @param[in] id ImageId
 201    *
 202    * @return Atlas Id
 203    */
 204   AtlasId GetAtlas(ImageId id);
 205   /**
 206    * @brief Get the current size of an atlas
 207    *
 208    * @param[in] atlas AtlasId
 209    *
 210    * @return AtlasSize structure for the atlas
 211    */
 212   const AtlasSize& GetAtlasSize(AtlasId atlas);
 213
 214   /**
 215    * @brief Get the number of blocks available in an atlas
 216    *
 217    * @param[in] atlas AtlasId
 218    *
 219    * @return Number of blocks free in this atlas
 220    */
 221   SizeType GetFreeBlocks(AtlasId atlas);
 222
 223   /**
 224    * @brief Sets the pixel area of any new atlas and also the individual block size
 225    *
 226    * @param[in] size Atlas size structure
 227    *
 228    * @param blockSize pixel area in atlas for a block
 229    */
 230   void SetNewAtlasSize(const AtlasSize& size);
 231
 232   /**
 233    * @brief Get the number of atlases created
 234    *
 235    * @return number of atlases
 236    */
 237   SizeType GetAtlasCount() const;
 238
 239   /**
 240    * @brief Get the pixel format used by an atlas
 241    *
 242    * @param[in] atlas AtlasId
 243    *
 244    * @return Pixel format used by this atlas
 245    */
 246   Pixel::Format GetPixelFormat(AtlasId atlas) const;
 247
 248   /**
 249    * @brief Fill in a metrics structure showing current status of this Atlas Manager
 250    *
 251    * @param[in] metrics metrics structure to be filled
 252    */
 253   void GetMetrics(Metrics& metrics);
 254
 255   /**
 256    * @brief Get TextureSet used by atlas
 257    *
 258    * @param[in] atlas AtlasId
 259    *
 260    * @return TextureSet used by atlas
 261    */
 262   TextureSet GetTextures(AtlasId atlas) const;
 263
 264   /**
 265    * @brief Set the texture set used by an atlas
 266    *
 267    * @param[in] atlas AtlasId
 268    * @param[in] textureSet The texture set to assign
 269    */
 270   void SetTextures(AtlasId atlas, TextureSet& textureSet);
 271
 272 public:
 273   // Default copy and move operator
 274   AtlasManager(const AtlasManager& rhs) = default;
 275   AtlasManager(AtlasManager&& rhs)      = default;
 276   AtlasManager& operator=(const AtlasManager& rhs) = default;
 277   AtlasManager& operator=(AtlasManager&& rhs) = default;
 278
 279 private:
 280   explicit DALI_INTERNAL AtlasManager(Internal::AtlasManager* impl);
 281 };
 282
 283 } // namespace Toolkit
 284
 285 } // namespace Dali
 286
 287 #endif // DALI_TOOLKIT_ATLAS_MANAGER_H