(Image) Add support for 9-patch images
[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 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    * Determine the size of an image the resource loaders will provide when given the same
81    * image attributes.
82    * This is a synchronous request.
83    * This function is used to determine the size of an image before it has loaded.
84    * @param[in] filename name of the image.
85    * @param[in] attributes The attributes used to load the image
86    * @param[out] closestSize Size of the image that will be loaded.
87    */
88   virtual void GetClosestImageSize( const std::string& filename,
89                                     const ImageAttributes& attributes,
90                                     Vector2& closestSize ) = 0;
91
92   /**
93    * Determine the size of an image the resource loaders will provide when given the same
94    * image attributes.
95    * This is a synchronous request.
96    * This function is used to determine the size of an image before it has loaded.
97    * @param[in] resourceBuffer A pointer to an encoded image buffer
98    * @param[in] attributes The attributes used to load the image
99    * @param[out] closestSize Size of the image that will be loaded.
100    */
101   virtual void GetClosestImageSize( ResourcePointer resourceBuffer,
102                                     const ImageAttributes& attributes,
103                                     Vector2& closestSize ) = 0;
104
105   /**
106    * Request a resource from the native filesystem. This is an asynchronous request.
107    * After this method returns, FillResourceCache() will be called to retrieve the result(s) of the
108    * resource loading operation. Loading resources in separate worker thread is recommended.
109    * Multi-threading note: this method will be called from the main thread only i.e. not
110    * from within the Core::Render() method.
111    * @param[in] request A unique resource request. This is not guaranteed to survive after LoadResource
112    * returns; the loading process should take a copy.
113    */
114   virtual void LoadResource(const ResourceRequest& request) = 0;
115
116   /**
117    * Request a resource from the native filesystem. This is a synchronous request, i.e.
118    * it will block the main loop whilst executing. It should therefore be used sparingly.
119    *
120    * Multi-threading note: this method will be called from the main thread only i.e. not
121    * from within the Core::Render() method.
122    * @param[in] resourceType The type of resource to load
123    * @param[in] resourcePath The path to the resource
124    * @return A pointer to a ref-counted resource
125    */
126   virtual ResourcePointer LoadResourceSynchronously( const ResourceType& resourceType, const std::string& resourcePath ) = 0;
127
128   /**
129    * Request that a resource be saved to the native filesystem.
130    * This is an asynchronous request.
131    */
132   virtual void SaveResource(const ResourceRequest& request) = 0;
133   /**
134    * Cancel an ongoing LoadResource() request.
135    * Multi-threading note: this method will be called from the main thread only i.e. not
136    * from within the Core::Render() method.
137    * @param[in] id The ID of the resource to cancel.
138    * @param[in] typeId The ID type of the resource to cancel.
139    */
140   virtual void CancelLoad(ResourceId id, ResourceTypeId typeId) = 0;
141
142   /**
143    * Query whether any asynchronous LoadResource() requests are ongoing.
144    * Multi-threading note: this method may be called from either the main or rendering thread.
145    * @return True if resources are being loaded.
146    */
147   virtual bool IsLoading() = 0;
148
149   /**
150    * Retrieve newly loaded resources.
151    * If no resources have finished loading, then this method returns immediately.
152    * Multi-threading note: this method will be called from the update thread, from within
153    * the UpdateManager::Update() method.
154    * @param[in] cache The resource cache to fill.
155    */
156   virtual void GetResources(ResourceCache& cache) = 0;
157
158   /**
159    * Waits for the asynchronous loader threads (if any) to finish.
160    * This will be only be called before Core destruction; no resource loading requests will be
161    * made following this method.
162    */
163   virtual void JoinLoaderThreads() = 0;
164
165   // Font Queries
166
167   /**
168    * Called by Dali to retrieve the default font family for the platform.
169    * Multi-threading note: this method will be called from the main thread only i.e. not
170    * from within the Core::Render() method.
171    * @return The default font family.
172    */
173   virtual std::string GetDefaultFontFamily() const = 0;
174
175   /**
176    * Called by Dali to retrieve the default font size for the platform in points.
177    * Multi-threading note: this method will be called from the main thread only i.e. not
178    * from within the Core::Render() method.
179    * @return The default font size.
180    */
181   virtual const float GetDefaultFontSize() const = 0;
182
183   /**
184    * Gets a font line height to match a given caps-height
185    * @param[in] fontFamily The name of the font's family
186    * @param[in] fontStyle  The style of the font
187    * @param[in] capsHeight The caps-height in pixels
188    */
189   virtual const PixelSize GetFontLineHeightFromCapsHeight(const std::string fontFamily, const std::string& fontStyle, const CapsHeight& capsHeight) const = 0;
190
191   /**
192    * Called by Font objects to synchronously query glyph data.
193    * @note Font's style goes inside the textRequest parameter
194    * @param[in] textRequest  Resource request. Includes font's style.
195    * @param[in] fontFamily   The name of the font's family
196    * @param[in] getBitmap    Whether to load bitmaps for the symbols as well
197    * @return A GlyphSet pointer with a list of the requested glyph metrics.
198    */
199   virtual Integration::GlyphSet* GetGlyphData ( const Integration::TextResourceType& textRequest,
200                                                 const std::string& fontFamily,
201                                                 bool getBitmap) const = 0;
202
203   /**
204    * Called by GlyphResourceManager to synchronously load glyph data.
205    * @param[in] textRequest     resource request
206    * @param[in] fontFamily      name of the font's family
207    * @return A GlyphSet pointer containing the requested glyph bitmaps.
208    */
209   virtual Integration::GlyphSet* GetCachedGlyphData( const TextResourceType& textRequest,
210                                                      const std::string& fontFamily ) const = 0;
211
212   /**
213    * Called by Font objects to synchronously query global font metrics.
214    * @param[in] fontFamily     The name of the font's family
215    * @param[in] fontStyle      The style of the font
216    * @param[out] globalMetrics font requested global metrics.
217    */
218   virtual void GetGlobalMetrics( const std::string& fontFamily,
219                                  const std::string& fontStyle,
220                                  Integration::GlobalMetrics& globalMetrics ) const = 0;
221
222   /**
223    * Sets horizontal and vertical pixels per inch value that is used by the display
224    * @param[in] dpiHorizontal horizontal dpi value
225    * @param[in] dpiVertical   vertical dpi value
226    */
227   virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
228
229   /**
230    * Returns the name of the font's family for displayed text.
231    * If possible, the returned font name should be able to display all characters in text.
232    * Otherwise returns closest match.
233    * @param[in] charsRequested displayed text
234    */
235   virtual std::string GetFontFamilyForChars(const TextArray& charsRequested) const = 0;
236
237   /**
238    * Checks whether all characters of text could be displayed with specified font family.
239    * @param[in] fontFamily     The name of the font's family
240    * @param[in] fontStyle      The style of the font
241    * @param[in] text     displayed text
242    */
243   virtual bool AllGlyphsSupported(const std::string& fontFamily, const std::string& fontStyle, const TextArray& text) const = 0;
244
245   /**
246    * Checks whether fontName is a valid font family name.
247    * closestMatch is always set to the best matching font or the system default font if no near match is detected.
248    * @param[in] fontFamily     The name of the font's family
249    * @param[in] fontStyle      The style of the font
250    * @param[out] isDefaultSystemFont Whether this font has been created with a default system font.
251    * @param[out] closestFontFamilyMatch Name of the font's family found based on the user input family's name
252    * @param[out] closestFontStyleMatch  Name of the font's style found based on the user input font's style
253    * @return     true if fontName is valid, false otherwise
254    */
255   virtual bool ValidateFontFamilyName(const std::string& fontFamily, const std::string& fontStyle, bool& isDefaultSystemFont, std::string& closestFontFamilyMatch, std::string& closestFontStyleMatch) const = 0;
256
257   /**
258    * The mode for GetFontList()
259    */
260   enum FontListMode
261   {
262     LIST_SYSTEM_FONTS,
263     LIST_APPLICATION_FONTS,
264     LIST_ALL_FONTS
265   };
266
267   /**
268    * Gets a list of fonts installed on the system.
269    * @param fontListMode which fonts to include in the list
270    * @return a list of font family names
271    */
272   virtual std::vector<std::string> GetFontList( FontListMode mode ) const = 0;
273
274   /**
275    * Load a file into a buffer
276    * @param[in] filename The filename to load
277    * @param[out] buffer  A buffer to receive the file.
278    *                     The buffer is implemeneted with a std::vector which is resized to fit the file.
279    * @result             true if the file is loaded.
280    */
281   virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
282
283   /**
284    * Load a file into a buffer
285    * @param[in] filename The filename to save
286    * @param[out] buffer  A buffer containing some data
287    *                     The buffer is implemeneted with a std::vector. The size() member specifies the buffer length.
288    * @result             true if the file is saved.
289    */
290   virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
291
292   /**
293    * This method re-loads the device defaults that Dali uses. Adaptor will call this
294    * when devices settings change.
295    */
296   virtual void UpdateDefaultsFromDevice() = 0;
297
298   /**
299    * Get a pointer to the DynamicsFactory.
300    */
301   virtual DynamicsFactory* GetDynamicsFactory() = 0;
302
303   /**
304    * Read from the metrics cache into the global metrics parameter
305    * @param[in] fontFamily The name of the font family
306    * @param[in] fontStyle The name of the font style
307    * @param[out] globalMetrics The data store to write into
308    * @return \e true if the operation succeeded
309    */
310   virtual bool ReadGlobalMetricsFromCache( const std::string& fontFamily,
311                                            const std::string& fontStyle,
312                                            Integration::GlobalMetrics& globalMetrics ) = 0;
313
314   /**
315    * Write the global metrics parameter to the metrics cache
316    * @param[in] fontFamily The name of the font family
317    * @param[in] fontStyle The name of the font style
318    * @param[out] globalMetrics The data store to write
319    */
320   virtual void WriteGlobalMetricsToCache( const std::string& fontFamily,
321                                           const std::string& fontStyle,
322                                           const Integration::GlobalMetrics& globalMetrics ) = 0;
323
324   /**
325    * Read the metrics from the cache into the supplied vector
326    * @param[in] fontFamily The name of the font family
327    * @param[in] fontStyle The name of the font style
328    * @param[out] glyphMetricsContainer The vector of metrics to write
329    * @return true if the operation succeeded
330    */
331   virtual bool ReadMetricsFromCache( const std::string& fontFamily,
332                                      const std::string& fontStyle,
333                                      std::vector<Integration::GlyphMetrics>& glyphMetricsContainer ) = 0;
334
335   /**
336    * Write the metrics to the cache
337    * @param[in] fontFamily The name of the font family
338    * @param[in] fontStyle The name of the font style
339    * @param[in] glyphSet The set of metrics to write
340    */
341   virtual void WriteMetricsToCache( const std::string& fontFamily,
342                                     const std::string& fontStyle,
343                                     const Integration::GlyphSet& glyphSet ) = 0;
344
345 }; // class PlatformAbstraction
346
347 } // namespace Integration
348
349 } // namespace Dali
350
351 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__