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