1 #ifndef __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__
2 #define __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali/integration-api/glyph-set.h>
23 #include <dali/integration-api/resource-cache.h>
24 #include <dali/integration-api/text-array.h>
33 class DynamicsFactory;
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.
40 class DALI_IMPORT_API PlatformAbstraction
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.
54 virtual void GetTimeMicroseconds(unsigned int& seconds, unsigned int& microSeconds) = 0;
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.
64 virtual void Suspend() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
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.
72 virtual void Resume() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
77 * Determine the size of an image the resource loaders will provide when given the same
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.
85 virtual void GetClosestImageSize( const std::string& filename,
86 const ImageAttributes& attributes,
87 Vector2& closestSize ) = 0;
90 * Determine the size of an image the resource loaders will provide when given the same
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.
98 virtual void GetClosestImageSize( ResourcePointer resourceBuffer,
99 const ImageAttributes& attributes,
100 Vector2& closestSize ) = 0;
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.
111 virtual void LoadResource(const ResourceRequest& request) = 0;
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.
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
123 virtual ResourcePointer LoadResourceSynchronously( const ResourceType& resourceType, const std::string& resourcePath ) = 0;
126 * Request that a resource be saved to the native filesystem.
127 * This is an asynchronous request.
129 virtual void SaveResource(const ResourceRequest& request) = 0;
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.
137 virtual void CancelLoad(ResourceId id, ResourceTypeId typeId) = 0;
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.
144 virtual bool IsLoading() = 0;
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.
153 virtual void GetResources(ResourceCache& cache) = 0;
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.
160 virtual void JoinLoaderThreads() = 0;
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.
170 virtual const std::string& GetDefaultFontFamily() const = 0;
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.
178 virtual float GetDefaultFontSize() const = 0;
181 * Gets a font line height to match a given caps-height
183 * @note fontFamily and fontStyle must have been validated previously.
184 * @see ValidateFontFamilyName().
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
190 virtual PixelSize GetFontLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, CapsHeight capsHeight) const = 0;
193 * Called by Font objects to synchronously query glyph data.
195 * @note fontFamily and font style, included in the resource request, must have been validated previously.
196 * @see ValidateFontFamilyName().
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.
204 virtual Integration::GlyphSet* GetGlyphData ( const Integration::TextResourceType& textRequest,
205 const std::string& fontFamily,
206 bool getBitmap) const = 0;
209 * Called by GlyphResourceManager to synchronously load glyph data.
211 * @note fontFamily and font style, included in the resource request, must have been validated previously.
212 * @see ValidateFontFamilyName().
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.
218 virtual Integration::GlyphSet* GetCachedGlyphData( const TextResourceType& textRequest,
219 const std::string& fontFamily ) const = 0;
222 * Called by Font objects to synchronously query global font metrics.
224 * @note fontFamily and fontStyle, must have been validated previously.
225 * @see ValidateFontFamilyName().
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.
231 virtual void GetGlobalMetrics( const std::string& fontFamily,
232 const std::string& fontStyle,
233 Integration::GlobalMetrics& globalMetrics ) const = 0;
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
240 virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
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
248 virtual const std::string& GetFontFamilyForChars(const TextArray& charsRequested) const = 0;
251 * Checks whether all characters of text could be displayed with specified font family.
253 * @note fontFamily and fontStyle must have been validated previously.
254 * @see ValidateFontFamilyName().
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
260 virtual bool AllGlyphsSupported(const std::string& fontFamily, const std::string& fontStyle, const TextArray& text) const = 0;
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.
273 virtual bool ValidateFontFamilyName(const std::string& fontFamily, const std::string& fontStyle, bool& isDefaultSystemFont, std::string& closestFontFamilyMatch, std::string& closestFontStyleMatch) const = 0;
276 * The mode for GetFontList()
281 LIST_APPLICATION_FONTS,
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.
290 virtual void GetFontList( FontListMode mode, std::vector<std::string>& fontList ) const = 0;
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.
299 virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
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.
308 virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
311 * This method re-loads the device defaults that Dali uses. Adaptor will call this
312 * when devices settings change.
314 virtual void UpdateDefaultsFromDevice() = 0;
317 * Get a pointer to the DynamicsFactory.
319 virtual DynamicsFactory* GetDynamicsFactory() = 0;
322 * Read from the metrics cache into the global metrics parameter
324 * @note fontFamily and fontStyle must have been validated previously.
325 * @see ValidateFontFamilyName().
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
332 virtual bool ReadGlobalMetricsFromCache( const std::string& fontFamily,
333 const std::string& fontStyle,
334 Integration::GlobalMetrics& globalMetrics ) = 0;
338 * @note fontFamily and fontStyle must have been validated previously.
339 * @see ValidateFontFamilyName().
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
346 virtual void WriteGlobalMetricsToCache( const std::string& fontFamily,
347 const std::string& fontStyle,
348 const Integration::GlobalMetrics& globalMetrics ) = 0;
351 * Read the metrics from the cache into the supplied vector
353 * @note fontFamily and fontStyle must have been validated previously.
354 * @see ValidateFontFamilyName().
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
361 virtual bool ReadMetricsFromCache( const std::string& fontFamily,
362 const std::string& fontStyle,
363 std::vector<Integration::GlyphMetrics>& glyphMetricsContainer ) = 0;
366 * Write the metrics to the cache
368 * @note fontFamily and fontStyle must have been validated previously.
369 * @see ValidateFontFamilyName().
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
375 virtual void WriteMetricsToCache( const std::string& fontFamily,
376 const std::string& fontStyle,
377 const Integration::GlyphSet& glyphSet ) = 0;
380 * Retrieves file names from the given directory.
382 * @param[in] directoryName The directory name.
383 * @param[out] fileNames The file names in the given directory.
385 virtual void GetFileNamesFromDirectory( const std::string& directoryName,
386 std::vector<std::string>& fileNames ) = 0;
389 * Retrieves the glyph image which represents the character.
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.
396 * @return A bitmap representing the character.
398 virtual Integration::BitmapPtr GetGlyphImage( const std::string& fontFamily, const std::string& fontStyle, float fontSize, uint32_t character ) const = 0;
400 }; // class PlatformAbstraction
402 } // namespace Integration
406 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__