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