dali/internal/event/text/atlas/glyph-atlas.h

   1 #ifndef __DALI_INTERNAL_GLYPH_ATLAS_H__
   2 #define __DALI_INTERNAL_GLYPH_ATLAS_H__
   3
   4 /*
   5  * Copyright (c) 2014 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
  21 // INTERNAL INCLUDES
  22 #include <dali/internal/event/text/atlas/atlas.h>
  23 #include <dali/internal/event/text/atlas/atlas-ranking.h>
  24 #include <dali/internal/common/text-array.h>
  25 #include <dali/internal/event/text/glyph-status/glyph-status.h>
  26 #include <dali/internal/event/text/glyph-status/glyph-status-container.h>
  27 #include <dali/internal/event/text/resource/glyph-resource-observer.h>
  28 #include <dali/internal/event/text/resource/glyph-resource-request.h>
  29 #include <dali/internal/event/text/font-metrics-interface.h>
  30
  31 namespace Dali
  32 {
  33
  34 namespace Internal
  35 {
  36
  37 struct TextVertexBuffer;
  38 struct TextFormat;
  39
  40 /**
  41  *
  42  * Glyph Atlas class.
  43  *
  44  * Internally does the following:
  45  * - Uses an Atlas object to manage where glyphs are allocated / positioned in the texture
  46  * - Uses a Glyph Status Container, to reference count glyphs
  47  *
  48  * When text is added to the atlas, it returns a TextVertexBuffer which holds everything
  49  * required to display the text.
  50  *
  51  * Provides a GlyphResourceObserver interface, so it can be notified by the glyph-resource-manager
  52  * when glyphs are loaded from disk.
  53  *
  54  * It operates as follows:
  55  * - Event Cycle Start
  56  * --
  57  * -- Text Actors have text assigned to them
  58  * -- Atlas->AssignText() is called, which returns a vertex buffer to display the text.
  59  * -- Any text that is not loaded, is added to mRequestList
  60  * --
  61  * - Event Cycle Finish
  62  * --  mRequestList is processed by Glyph Resource Manager, and sends request to resource-loader
  63  *
  64  * While waiting for text to load, text-actors use the TextObserver interface, which is triggered
  65  * whenever text is loaded.
  66  */
  67 class GlyphAtlas : public GlyphResourceObserver
  68 {
  69
  70 public:
  71
  72   /**
  73    * Create a FontAtlas
  74    * @param[in] atlas size in pixels (e.g. 256, for a 256x256 atlas)
  75    */
  76   static GlyphAtlas* New( unsigned int size );
  77
  78   /**
  79     * Destructor
  80     */
  81   virtual ~GlyphAtlas();
  82
  83   /**
  84    * Assign text to the atlas.
  85    * @param[in] text the text to assign to the atlas
  86    * @param[in] format the text format
  87    * @param[in] fontId the font id
  88    * @param[in] metrics font metrics interface
  89    */
  90   TextVertexBuffer* AssignText( const TextArray& text, const TextFormat &format, FontId fontId, FontMetricsInterface& metrics );
  91
  92   /**
  93    * Inform the atlas that text is no longer used
  94    * @param[in] text the text to assign to the atlas
  95    * @param[in] format the text format
  96    * @param[in] fontId the font id
  97    */
  98   void TextNoLongerUsed( const TextArray& text, const TextFormat &format, FontId fontId );
  99
 100   /**
 101    * Given a text string, returns an atlas ranking.
 102    * An atlas ranking describes how suitable it is to store the text
 103    * @param[in] text the text
 104    * @param[in] fontId the font id
 105    * @return atlas ranking
 106    */
 107   AtlasRanking GetRanking( const TextArray& text , FontId fontId ) const;
 108
 109   /**
 110    * Get the atlas size
 111    * @return the atlas size
 112    */
 113   unsigned int GetSize() const;
 114
 115   /**
 116    * Set the texture id
 117    * @param[in] textureId texture id (resource id)
 118    */
 119   void SetTextureId( unsigned int textureId );
 120
 121   /**
 122    * @return true if the atlas has any glyph load requests it wants passing to the resource-loader
 123    */
 124   bool HasPendingRequests() const;
 125
 126   /**
 127    * Get the glyph request list.
 128    * The request list is an array of characters/font pairs that need loading.
 129    * @return glyph load requests
 130    */
 131   const GlyphRequestList& GetRequestList() const;
 132
 133   /**
 134    * Clear the glyph request list.
 135    */
 136   void ClearRequestLists();
 137
 138   /**
 139    * Find out if all the characters in the text string are loaded
 140    * @param[in] text the text to check for
 141    * @param[in] format the text format
 142    * @param[in] fontId the font id
 143    * @return true if the text is loaded
 144    */
 145   bool IsTextLoaded( const TextArray& text, const TextFormat &format, FontId fontId) const;
 146
 147   /**
 148    * Clone the contents of the atlas into this atlas
 149    * @param clone the atlas to clone
 150    */
 151   void CloneContents( GlyphAtlas* clone);
 152
 153   /**
 154    * Remove characters with a ref count of zero from the atlas
 155    */
 156   void ClearDeadCharacters();
 157
 158   /**
 159    * Clear the contents of the atlas
 160    */
 161   void Clear();
 162
 163   /**
 164    * Checks if this atlas has replaced a previous atlas with
 165    * a certain texture id.
 166    * @param[in] textureId texture id
 167    * @return true if it has replaced an atlas using the texture id specified
 168    */
 169   bool HasReplacedTexture( unsigned int textureId );
 170
 171 public: // for glyph resource observer
 172
 173   /**
 174    * @copydoc GlyphResourceObserver::GlyphUpLoadedToTexture()
 175    */
 176   virtual void GlyphUpLoadedToTexture( uint32_t charCode, FontId fontId);
 177
 178   /**
 179    * @copydoc GlyphResourceObserver::GlyphLoadedFromFile()
 180    */
 181   virtual void GlyphLoadedFromFile( uint32_t charCode, FontId fontId, Quality status );
 182
 183   /**
 184    * @copydoc GlyphResourceObserver::GetGlyphTexturePosition()
 185    */
 186   virtual bool GetGlyphTexturePosition( uint32_t charCode, FontId fontId, unsigned int &xPos, unsigned int &yPos) const;
 187
 188   /**
 189    * @copydoc GlyphResourceObserver::GetTextureId()
 190    */
 191   virtual unsigned int GetTextureId() const;
 192
 193   /**
 194    * @copydoc GlyphResourceObserver::GetTextureState()
 195    */
 196   virtual TextureState GetTextureState();
 197
 198   /**
 199    * @copydoc GlyphResourceObserver::GetTextureState()
 200    */
 201   virtual void GetNewTextureId( TextureIdList& oldTextureIds, unsigned int& newTextureId );
 202
 203 private:
 204
 205   /**
 206    * Increase the reference count of every character help in the text array
 207    * @param[in] text the text to reference
 208    * @param[in] format the text format
 209    * @param[in] fontId font id
 210    */
 211   void ReferenceText( const TextArray& text,
 212                  const TextFormat &format,
 213                  FontId fontId);
 214
 215   /**
 216    * Increase glyph reference count.
 217    * If the character doesn't exist, then add it, and mark it to be loaded
 218    * @param[in] charCode  character code
 219    * @param[in] fontId the font id
 220    */
 221   void IncreaseGlyphRefCount( uint32_t charCode, FontId fontId);
 222
 223   /**
 224    * Insert a new character in to the atlas
 225    * @param[in] charCode  character code
 226    * @param[in] fontId the font id
 227    */
 228   void InsertNewCharacter( uint32_t charCode, FontId fontId );
 229
 230   /**
 231    * Add a character to a resource request.
 232    * At the end of an event cycle, glyph-atlas-manager calls GetRequestList()
 233    * to retrieve the request list.
 234    * @param[in] charCode  character code
 235    * @param[in] xPos The X coordinate in the texture
 236    * @param[in] yPos The Y coordinate in the texture
 237    * @param[in] fontId the font id
 238    * @param[in] quality glyph
 239    */
 240   void RequestToLoadCharacter(uint32_t charCode, unsigned int xPos, unsigned int yPos, FontId  fontId, GlyphResourceRequest::GlyphQuality quality );
 241
 242   /**
 243    * Get a resource request.
 244    * Each resource request is a list of characters + font id and a quality setting.
 245    * @param[in] fontId the font id
 246    * @param[in] quality glyph
 247    * @return glyph resource request object
 248    */
 249   GlyphResourceRequest& GetResourceRequest( FontId fontId, GlyphResourceRequest::GlyphQuality quality );
 250
 251   /**
 252    * @return true if the atlas is resizable
 253    */
 254   bool Resizable() const;
 255
 256   /**
 257    * Get a list of texture id's of Atlases this Atlas has replaced.
 258    * It is possible an atlas can be resized multiple times in a single event cycle.
 259    * So atlas 5, can be replaced by atlas 6, which is then replaced by atlas 7.
 260    * Any text-attachments using atlas 5 & 6, need to know they should use atlas 7 now.
 261    * @return texture id list
 262    */
 263   TextureIdList GetTextureIdOfReplacedAtlas();
 264
 265   /**
 266    * Private constructor, use GlyphAtlas::New()
 267    * @param[in] size used to define the width / height of the atlas
 268    */
 269   GlyphAtlas( unsigned int size);
 270
 271 private:
 272
 273   GlyphRequestList            mRequestList;             ///< list of GlyphResourceRequest objects
 274   GlyphStatusContainer        mGlyphContainer;          ///< Glyph status container
 275   Atlas                       mAtlas;                   ///< has block allocation algorithm
 276   unsigned int                mTextureId;               ///< texture id
 277   TextureIdList               mTextureIdOfReplacedAtlases; ///< list of previously replaced atlases
 278
 279 };
 280
 281
 282 } // namespace Internal
 283
 284 } // namespace Dali
 285
 286 #endif // __DALI_INTERNAL_GLYPH_ATLAS_H__