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