Merge "LLVM/Emscripten fixes" into tizen
[platform/core/uifw/dali-core.git] / 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   virtual ~PlatformAbstraction() {}
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() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 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() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 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, FillResourceCache() will be called 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 const 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 float GetDefaultFontSize() const = 0;
181
182   /**
183    * Gets a font line height to match a given caps-height
184    *
185    * @note fontFamily and fontStyle must have been validated previously.
186    * @see ValidateFontFamilyName().
187    *
188    * @param[in] fontFamily The name of the font's family
189    * @param[in] fontStyle  The style of the font
190    * @param[in] capsHeight The caps-height in pixels
191    */
192   virtual PixelSize GetFontLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, CapsHeight capsHeight) const = 0;
193
194   /**
195    * Called by Font objects to synchronously query glyph data.
196    *
197    * @note fontFamily and font style, included in the resource request,  must have been validated previously.
198    * @see ValidateFontFamilyName().
199    *
200    * @note Font's style goes inside the textRequest parameter
201    * @param[in] textRequest  Resource request. Includes font's style.
202    * @param[in] fontFamily   The name of the font's family
203    * @param[in] getBitmap    Whether to load bitmaps for the symbols as well
204    * @return A GlyphSet pointer with a list of the requested glyph metrics.
205    */
206   virtual Integration::GlyphSet* GetGlyphData ( const Integration::TextResourceType& textRequest,
207                                                 const std::string& fontFamily,
208                                                 bool getBitmap) const = 0;
209
210   /**
211    * Called by GlyphResourceManager to synchronously load glyph data.
212    *
213    * @note fontFamily and font style, included in the resource request,  must have been validated previously.
214    * @see ValidateFontFamilyName().
215    *
216    * @param[in] textRequest     resource request
217    * @param[in] fontFamily      name of the font's family
218    * @return A GlyphSet pointer containing the requested glyph bitmaps.
219    */
220   virtual Integration::GlyphSet* GetCachedGlyphData( const TextResourceType& textRequest,
221                                                      const std::string& fontFamily ) const = 0;
222
223   /**
224    * Called by Font objects to synchronously query global font metrics.
225    *
226    * @note fontFamily and fontStyle, must have been validated previously.
227    * @see ValidateFontFamilyName().
228    *
229    * @param[in] fontFamily     The name of the font's family
230    * @param[in] fontStyle      The style of the font
231    * @param[out] globalMetrics font requested global metrics.
232    */
233   virtual void GetGlobalMetrics( const std::string& fontFamily,
234                                  const std::string& fontStyle,
235                                  Integration::GlobalMetrics& globalMetrics ) const = 0;
236
237   /**
238    * Sets horizontal and vertical pixels per inch value that is used by the display
239    * @param[in] dpiHorizontal horizontal dpi value
240    * @param[in] dpiVertical   vertical dpi value
241    */
242   virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
243
244   /**
245    * Returns the name of the font's family for displayed text.
246    * If possible, the returned font name should be able to display all characters in text.
247    * Otherwise returns closest match.
248    * @param[in] charsRequested displayed text
249    */
250   virtual const std::string& GetFontFamilyForChars(const TextArray& charsRequested) const = 0;
251
252   /**
253    * Checks whether all characters of text could be displayed with specified font family.
254    *
255    * @note fontFamily and fontStyle must have been validated previously.
256    * @see ValidateFontFamilyName().
257    *
258    * @param[in] fontFamily     The name of the font's family
259    * @param[in] fontStyle      The style of the font
260    * @param[in] text     displayed text
261    */
262   virtual bool AllGlyphsSupported(const std::string& fontFamily, const std::string& fontStyle, const TextArray& text) const = 0;
263
264   /**
265    * Checks whether fontName is a valid font family name and fontStyle is a valid font style.
266    * closestFontFamilyMatch and closestFontStyleMatch are always set to the best matching font
267    * or the system default font if no near match is detected.
268    * @param[in] fontFamily     The name of the font's family
269    * @param[in] fontStyle      The style of the font
270    * @param[out] isDefaultSystemFont Whether this font has been created with a default system font.
271    * @param[out] closestFontFamilyMatch Name of the font's family found based on the user input family's name
272    * @param[out] closestFontStyleMatch  Name of the font's style found based on the user input font's style
273    * @return Whether a valid match has been found.
274    */
275   virtual bool ValidateFontFamilyName(const std::string& fontFamily, const std::string& fontStyle, bool& isDefaultSystemFont, std::string& closestFontFamilyMatch, std::string& closestFontStyleMatch) const = 0;
276
277   /**
278    * The mode for GetFontList()
279    */
280   enum FontListMode
281   {
282     LIST_SYSTEM_FONTS,
283     LIST_APPLICATION_FONTS,
284     LIST_ALL_FONTS
285   };
286
287   /**
288    * Gets a list of fonts installed on the system.
289    * @param[in] mode which fonts to include in the list.
290    * @param[out] fontList The list of font family names.
291    */
292   virtual void GetFontList( FontListMode mode, std::vector<std::string>& fontList ) const = 0;
293
294   /**
295    * Load a file into a buffer
296    * @param[in] filename The filename to load
297    * @param[out] buffer  A buffer to receive the file.
298    *                     The buffer is implemeneted with a std::vector which is resized to fit the file.
299    * @result             true if the file is loaded.
300    */
301   virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
302
303   /**
304    * Load a file into a buffer
305    * @param[in] filename The filename to save
306    * @param[out] buffer  A buffer containing some data
307    *                     The buffer is implemeneted with a std::vector. The size() member specifies the buffer length.
308    * @result             true if the file is saved.
309    */
310   virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
311
312   /**
313    * This method re-loads the device defaults that Dali uses. Adaptor will call this
314    * when devices settings change.
315    */
316   virtual void UpdateDefaultsFromDevice() = 0;
317
318   /**
319    * Get a pointer to the DynamicsFactory.
320    */
321   virtual DynamicsFactory* GetDynamicsFactory() = 0;
322
323   /**
324    * Read from the metrics cache into the global metrics parameter
325    *
326    * @note fontFamily and fontStyle must have been validated previously.
327    * @see ValidateFontFamilyName().
328    *
329    * @param[in] fontFamily The name of the font family
330    * @param[in] fontStyle The name of the font style
331    * @param[out] globalMetrics The data store to write into
332    * @return \e true if the operation succeeded
333    */
334   virtual bool ReadGlobalMetricsFromCache( const std::string& fontFamily,
335                                            const std::string& fontStyle,
336                                            Integration::GlobalMetrics& globalMetrics ) = 0;
337
338   /**
339    *
340    * @note fontFamily and fontStyle must have been validated previously.
341    * @see ValidateFontFamilyName().
342    *
343    * Write the global metrics parameter to the metrics cache
344    * @param[in] fontFamily The name of the font family
345    * @param[in] fontStyle The name of the font style
346    * @param[out] globalMetrics The data store to write
347    */
348   virtual void WriteGlobalMetricsToCache( const std::string& fontFamily,
349                                           const std::string& fontStyle,
350                                           const Integration::GlobalMetrics& globalMetrics ) = 0;
351
352   /**
353    * Read the metrics from the cache into the supplied vector
354    *
355    * @note fontFamily and fontStyle must have been validated previously.
356    * @see ValidateFontFamilyName().
357    *
358    * @param[in] fontFamily The name of the font family
359    * @param[in] fontStyle The name of the font style
360    * @param[out] glyphMetricsContainer The vector of metrics to write
361    * @return true if the operation succeeded
362    */
363   virtual bool ReadMetricsFromCache( const std::string& fontFamily,
364                                      const std::string& fontStyle,
365                                      std::vector<Integration::GlyphMetrics>& glyphMetricsContainer ) = 0;
366
367   /**
368    * Write the metrics to the cache
369    *
370    * @note fontFamily and fontStyle must have been validated previously.
371    * @see ValidateFontFamilyName().
372    *
373    * @param[in] fontFamily The name of the font family
374    * @param[in] fontStyle The name of the font style
375    * @param[in] glyphSet The set of metrics to write
376    */
377   virtual void WriteMetricsToCache( const std::string& fontFamily,
378                                     const std::string& fontStyle,
379                                     const Integration::GlyphSet& glyphSet ) = 0;
380
381   /**
382    * Retrieves file names from the given directory.
383    *
384    * @param[in] directoryName The directory name.
385    * @param[out] fileNames The file names in the given directory.
386    */
387   virtual void GetFileNamesFromDirectory( const std::string& directoryName,
388                                           std::vector<std::string>& fileNames ) = 0;
389
390   /**
391    * Retrieves the glyph image which represents the character.
392    *
393    * @param[in] fontFamily The font's family name.
394    * @param[in] fontStyle The font's style.
395    * @param[in] fontSize The font's size (in points).
396    * @param[in] character The given character.
397    *
398    * @return A bitmap representing the character.
399    */
400   virtual Integration::BitmapPtr GetGlyphImage( const std::string& fontFamily, const std::string& fontStyle, float fontSize, uint32_t character ) const = 0;
401
402 }; // class PlatformAbstraction
403
404 } // namespace Integration
405
406 } // namespace Dali
407
408 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__