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