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