dali/integration-api/platform-abstraction.h

   1 #ifndef __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__
   2 #define __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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
  23 // INTERNAL INCLUDES
  24 #include <dali/integration-api/resource-cache.h>
  25 #include <dali/integration-api/glyph-set.h>
  26
  27 namespace Dali
  28 {
  29
  30 typedef std::vector<uint32_t> TextArray;
  31
  32 namespace Integration
  33 {
  34
  35 class Bitmap;
  36 class DynamicsFactory;
  37
  38 /**
  39  * PlatformAbstraction is an abstract interface, used by Dali to access platform specific services.
  40  * A concrete implementation must be created for each platform, and provided when creating the
  41  * Dali::Integration::Core object.
  42  */
  43 class DALI_IMPORT_API PlatformAbstraction
  44 {
  45 public:
  46
  47   // Dali Lifecycle
  48
  49   /**
  50    * Get the monotonic time since an unspecified reference point.
  51    * This is used by Dali to calculate time intervals during animations; the interval is
  52    * recalculated when Dali is resumed with Dali::Integration::Core::Resume().
  53    * Multi-threading note: this method may be called from either the main or rendering thread.
  54    * @param[out] seconds The time in seconds since the reference point.
  55    * @param[out] microSeconds The remainder in microseconds.
  56    */
  57   virtual void GetTimeMicroseconds(unsigned int &seconds, unsigned int &microSeconds) = 0;
  58
  59   /**
  60    * Tell the platform abstraction that Dali is ready to pause, such as when the
  61    * application enters a background state.
  62    * Allows background threads to pause their work until Resume() is called.
  63    * This is a good time to release recreatable data such as memory caches
  64    * to cooperate with other apps and reduce the chance of this one being
  65    * force-killed in a low memory situation.
  66    */
  67   virtual void Suspend() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
  68
  69   /**
  70    * Tell the platform abstraction that Dali is resuming from a pause, such as
  71    * when it has transitioned from a background state to a foreground one.
  72    * It is time to wake up sleeping background threads and recreate memory
  73    * caches and other temporary data.
  74    */
  75   virtual void Resume() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
  76
  77   // Resource Loading
  78
  79   /**
  80    * Load metadata from an image on the native filesystem. This is a synchronous request.
  81    * This function is used when the size of an image needs to be determined before it has loaded.
  82    * @param[in] filename name of the string to load.
  83    * @param[out] size Size of the image.
  84    */
  85   virtual void LoadImageMetadata(const std::string filename, Vector2 &size) = 0;
  86
  87   /**
  88    * Request a resource from the native filesystem. This is an asynchronous request.
  89    * After this method returns, FillResourceCache() will be called to retrieve the result(s) of the
  90    * resource loading operation. Loading resources in separate worker thread is recommended.
  91    * Multi-threading note: this method will be called from the main thread only i.e. not
  92    * from within the Core::Render() method.
  93    * @param[in] request A unique resource request. This is not guaranteed to survive after LoadResource
  94    * returns; the loading process should take a copy.
  95    */
  96   virtual void LoadResource(const ResourceRequest& request) = 0;
  97
  98   /**
  99    * Request that a resource be saved to the native filesystem.
 100    * This is an asynchronous request.
 101    */
 102   virtual void SaveResource(const ResourceRequest& request) = 0;
 103   /**
 104    * Cancel an ongoing LoadResource() request.
 105    * Multi-threading note: this method will be called from the main thread only i.e. not
 106    * from within the Core::Render() method.
 107    * @param[in] id The ID of the resource to cancel.
 108    * @param[in] typeId The ID type of the resource to cancel.
 109    */
 110   virtual void CancelLoad(ResourceId id, ResourceTypeId typeId) = 0;
 111
 112   /**
 113    * Query whether any asynchronous LoadResource() requests are ongoing.
 114    * Multi-threading note: this method may be called from either the main or rendering thread.
 115    * @return True if resources are being loaded.
 116    */
 117   virtual bool IsLoading() = 0;
 118
 119   /**
 120    * Retrieve newly loaded resources.
 121    * If no resources have finished loading, then this method returns immediately.
 122    * Multi-threading note: this method will be called from the update thread, from within
 123    * the UpdateManager::Update() method.
 124    * @param[in] cache The resource cache to fill.
 125    */
 126   virtual void GetResources(ResourceCache& cache) = 0;
 127
 128   /**
 129    * Waits for the asynchronous loader threads (if any) to finish.
 130    * This will be only be called before Core destruction; no resource loading requests will be
 131    * made following this method.
 132    */
 133   virtual void JoinLoaderThreads() = 0;
 134
 135   // Font Queries
 136
 137   /**
 138    * Called by Dali to retrieve the default font family for the platform.
 139    * Multi-threading note: this method will be called from the main thread only i.e. not
 140    * from within the Core::Render() method.
 141    * @return The default font family.
 142    */
 143   virtual std::string GetDefaultFontFamily() const = 0;
 144
 145   /**
 146    * Called by Dali to retrieve the default font size for the platform in points.
 147    * Multi-threading note: this method will be called from the main thread only i.e. not
 148    * from within the Core::Render() method.
 149    * @return The default font size.
 150    */
 151   virtual const float GetDefaultFontSize() const = 0;
 152
 153   /**
 154    * Gets a font line height to match a given caps-height
 155    * @param[in] fontFamily The name of the font's family
 156    * @param[in] fontStyle  The style of the font
 157    * @param[in] capsHeight The caps-height in pixels
 158    */
 159   virtual const PixelSize GetFontLineHeightFromCapsHeight(const std::string fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight) const = 0;
 160
 161   /**
 162    * Called by Font objects to synchronously query glyph data.
 163    * @note Font's style goes inside the textRequest parameter
 164    * @param[in] textRequest  Resource request. Includes font's style.
 165    * @param[in] fontFamily   The name of the font's family
 166    * @param[in] getBitmap    Whether to load bitmaps for the symbols as well
 167    * @return A GlyphSet pointer with a list of the requested glyph metrics.
 168    */
 169   virtual Integration::GlyphSet* GetGlyphData ( const Integration::TextResourceType& textRequest,
 170                                                 const std::string& fontFamily,
 171                                                 bool getBitmap) const = 0;
 172
 173   /**
 174    * Called by GlyphResourceManager to synchronously load glyph data.
 175    * @param[in] textRequest     resource request
 176    * @param[in] fontFamily      name of the font's family
 177    * @return A GlyphSet pointer containing the requested glyph bitmaps.
 178    */
 179   virtual Integration::GlyphSet* GetCachedGlyphData( const TextResourceType& textRequest,
 180                                                      const std::string& fontFamily ) const = 0;
 181
 182   /**
 183    * Called by Font objects to synchronously query global font metrics.
 184    * @param[in] fontFamily     The name of the font's family
 185    * @param[in] fontStyle      The style of the font
 186    * @param[out] globalMetrics font requested global metrics.
 187    */
 188   virtual void GetGlobalMetrics( const std::string& fontFamily,
 189                                  const std::string& fontStyle,
 190                                  Integration::GlobalMetrics& globalMetrics ) const = 0;
 191
 192   /**
 193    * Sets horizontal and vertical pixels per inch value that is used by the display
 194    * @param[in] dpiHorizontal horizontal dpi value
 195    * @param[in] dpiVertical   vertical dpi value
 196    */
 197   virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
 198
 199   /**
 200    * Returns the name of the font's family for displayed text.
 201    * If possible, the returned font name should be able to display all characters in text.
 202    * Otherwise returns closest match.
 203    * @param[in] charsRequested displayed text
 204    */
 205   virtual std::string GetFontFamilyForChars(const TextArray& charsRequested) const = 0;
 206
 207   /**
 208    * Checks whether all characters of text could be displayed with specified font family.
 209    * @param[in] fontFamily     The name of the font's family
 210    * @param[in] fontStyle      The style of the font
 211    * @param[in] text     displayed text
 212    */
 213   virtual bool AllGlyphsSupported(const std::string& fontFamily, const std::string& fontStyle, const TextArray& text) const = 0;
 214
 215   /**
 216    * Checks whether fontName is a valid font family name.
 217    * closestMatch is always set to the best matching font or the system default font if no near match is detected.
 218    * @param[in] fontFamily     The name of the font's family
 219    * @param[in] fontStyle      The style of the font
 220    * @param[out] isDefaultSystemFont Whether this font has been created with a default system font.
 221    * @param[out] closestFontFamilyMatch Name of the font's family found based on the user input family's name
 222    * @param[out] closestFontStyleMatch  Name of the font's style found based on the user input font's style
 223    * @return     true if fontName is valid, false otherwise
 224    */
 225   virtual bool ValidateFontFamilyName(const std::string& fontFamily, const std::string& fontStyle, bool& isDefaultSystemFont, std::string& closestFontFamilyMatch, std::string& closestFontStyleMatch) const = 0;
 226
 227   /**
 228    * The mode for GetFontList()
 229    */
 230   enum FontListMode
 231   {
 232     LIST_SYSTEM_FONTS,
 233     LIST_APPLICATION_FONTS,
 234     LIST_ALL_FONTS
 235   };
 236
 237   /**
 238    * Gets a list of fonts installed on the system.
 239    * @param fontListMode which fonts to include in the list
 240    * @return a list of font family names
 241    */
 242   virtual std::vector<std::string> GetFontList( FontListMode mode ) const = 0;
 243
 244   /**
 245    * Load a file into a buffer
 246    * @param[in] filename The filename to load
 247    * @param[out] buffer  A buffer to receive the file.
 248    *                     The buffer is implemeneted with a std::vector which is resized to fit the file.
 249    * @result             true if the file is loaded.
 250    */
 251   virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
 252
 253   /**
 254    * Load a file into a buffer
 255    * @param[in] filename The filename to save
 256    * @param[out] buffer  A buffer containing some data
 257    *                     The buffer is implemeneted with a std::vector. The size() member specifies the buffer length.
 258    * @result             true if the file is saved.
 259    */
 260   virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
 261
 262   /**
 263    * This method re-loads the device defaults that Dali uses. Adaptor will call this
 264    * when devices settings change.
 265    */
 266   virtual void UpdateDefaultsFromDevice() = 0;
 267
 268   /**
 269    * Get a pointer to the DynamicsFactory.
 270    */
 271   virtual DynamicsFactory* GetDynamicsFactory() = 0;
 272
 273   /**
 274    * Read from the metrics cache into the global metrics parameter
 275    * @param[in] fontFamily The name of the font family
 276    * @param[in] fontStyle The name of the font style
 277    * @param[out] globalMetrics The data store to write into
 278    * @return \e true if the operation succeeded
 279    */
 280   virtual bool ReadGlobalMetricsFromCache( const std::string& fontFamily,
 281                                            const std::string& fontStyle,
 282                                            Integration::GlobalMetrics& globalMetrics ) = 0;
 283
 284   /**
 285    * Write the global metrics parameter to the metrics cache
 286    * @param[in] fontFamily The name of the font family
 287    * @param[in] fontStyle The name of the font style
 288    * @param[out] globalMetrics The data store to write
 289    */
 290   virtual void WriteGlobalMetricsToCache( const std::string& fontFamily,
 291                                           const std::string& fontStyle,
 292                                           const Integration::GlobalMetrics& globalMetrics ) = 0;
 293
 294   /**
 295    * Read the metrics from the cache into the supplied vector
 296    * @param[in] fontFamily The name of the font family
 297    * @param[in] fontStyle The name of the font style
 298    * @param[out] glyphMetricsContainer The vector of metrics to write
 299    * @return true if the operation succeeded
 300    */
 301   virtual bool ReadMetricsFromCache( const std::string& fontFamily,
 302                                      const std::string& fontStyle,
 303                                      std::vector<Integration::GlyphMetrics>& glyphMetricsContainer ) = 0;
 304
 305   /**
 306    * Write the metrics to the cache
 307    * @param[in] fontFamily The name of the font family
 308    * @param[in] fontStyle The name of the font style
 309    * @param[in] glyphSet The set of metrics to write
 310    */
 311   virtual void WriteMetricsToCache( const std::string& fontFamily,
 312                                     const std::string& fontStyle,
 313                                     const Integration::GlyphSet& glyphSet ) = 0;
 314
 315 }; // class PlatformAbstraction
 316
 317 } // namespace Integration
 318
 319 } // namespace Dali
 320
 321 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__