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.
25 #include <dali/integration-api/resource-cache.h>
26 #include <dali/integration-api/glyph-set.h>
31 typedef std::vector<uint32_t> TextArray;
37 class DynamicsFactory;
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.
44 class DALI_IMPORT_API PlatformAbstraction
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.
58 virtual void GetTimeMicroseconds(unsigned int& seconds, unsigned int& microSeconds) = 0;
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.
68 virtual void Suspend() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
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.
76 virtual void Resume() {} ///!ToDo: Make pure virtual once dali-adaptor patch is in place = 0;
81 * Determine the size of an image the resource loaders will provide when given the same
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.
89 virtual void GetClosestImageSize( const std::string& filename,
90 const ImageAttributes& attributes,
91 Vector2& closestSize ) = 0;
94 * Determine the size of an image the resource loaders will provide when given the same
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.
102 virtual void GetClosestImageSize( ResourcePointer resourceBuffer,
103 const ImageAttributes& attributes,
104 Vector2& closestSize ) = 0;
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.
115 virtual void LoadResource(const ResourceRequest& request) = 0;
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.
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
127 virtual ResourcePointer LoadResourceSynchronously( const ResourceType& resourceType, const std::string& resourcePath ) = 0;
130 * Request that a resource be saved to the native filesystem.
131 * This is an asynchronous request.
133 virtual void SaveResource(const ResourceRequest& request) = 0;
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.
141 virtual void CancelLoad(ResourceId id, ResourceTypeId typeId) = 0;
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.
148 virtual bool IsLoading() = 0;
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.
157 virtual void GetResources(ResourceCache& cache) = 0;
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.
164 virtual void JoinLoaderThreads() = 0;
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.
174 virtual const std::string& GetDefaultFontFamily() const = 0;
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.
182 virtual float GetDefaultFontSize() const = 0;
185 * Gets a font line height to match a given caps-height
187 * @note fontFamily and fontStyle must have been validated previously.
188 * @see ValidateFontFamilyName().
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
194 virtual PixelSize GetFontLineHeightFromCapsHeight(const std::string& fontFamily, const std::string& fontStyle, CapsHeight capsHeight) const = 0;
197 * Called by Font objects to synchronously query glyph data.
199 * @note fontFamily and font style, included in the resource request, must have been validated previously.
200 * @see ValidateFontFamilyName().
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.
208 virtual Integration::GlyphSet* GetGlyphData ( const Integration::TextResourceType& textRequest,
209 const std::string& fontFamily,
210 bool getBitmap) const = 0;
213 * Called by GlyphResourceManager to synchronously load glyph data.
215 * @note fontFamily and font style, included in the resource request, must have been validated previously.
216 * @see ValidateFontFamilyName().
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.
222 virtual Integration::GlyphSet* GetCachedGlyphData( const TextResourceType& textRequest,
223 const std::string& fontFamily ) const = 0;
226 * Called by Font objects to synchronously query global font metrics.
228 * @note fontFamily and fontStyle, must have been validated previously.
229 * @see ValidateFontFamilyName().
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.
235 virtual void GetGlobalMetrics( const std::string& fontFamily,
236 const std::string& fontStyle,
237 Integration::GlobalMetrics& globalMetrics ) const = 0;
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
244 virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
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
252 virtual const std::string& GetFontFamilyForChars(const TextArray& charsRequested) const = 0;
255 * Checks whether all characters of text could be displayed with specified font family.
257 * @note fontFamily and fontStyle must have been validated previously.
258 * @see ValidateFontFamilyName().
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
264 virtual bool AllGlyphsSupported(const std::string& fontFamily, const std::string& fontStyle, const TextArray& text) const = 0;
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.
277 virtual bool ValidateFontFamilyName(const std::string& fontFamily, const std::string& fontStyle, bool& isDefaultSystemFont, std::string& closestFontFamilyMatch, std::string& closestFontStyleMatch) const = 0;
280 * The mode for GetFontList()
285 LIST_APPLICATION_FONTS,
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.
294 virtual void GetFontList( FontListMode mode, std::vector<std::string>& fontList ) const = 0;
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.
303 virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
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.
312 virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
315 * This method re-loads the device defaults that Dali uses. Adaptor will call this
316 * when devices settings change.
318 virtual void UpdateDefaultsFromDevice() = 0;
321 * Get a pointer to the DynamicsFactory.
323 virtual DynamicsFactory* GetDynamicsFactory() = 0;
326 * Read from the metrics cache into the global metrics parameter
328 * @note fontFamily and fontStyle must have been validated previously.
329 * @see ValidateFontFamilyName().
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
336 virtual bool ReadGlobalMetricsFromCache( const std::string& fontFamily,
337 const std::string& fontStyle,
338 Integration::GlobalMetrics& globalMetrics ) = 0;
342 * @note fontFamily and fontStyle must have been validated previously.
343 * @see ValidateFontFamilyName().
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
350 virtual void WriteGlobalMetricsToCache( const std::string& fontFamily,
351 const std::string& fontStyle,
352 const Integration::GlobalMetrics& globalMetrics ) = 0;
355 * Read the metrics from the cache into the supplied vector
357 * @note fontFamily and fontStyle must have been validated previously.
358 * @see ValidateFontFamilyName().
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
365 virtual bool ReadMetricsFromCache( const std::string& fontFamily,
366 const std::string& fontStyle,
367 std::vector<Integration::GlyphMetrics>& glyphMetricsContainer ) = 0;
370 * Write the metrics to the cache
372 * @note fontFamily and fontStyle must have been validated previously.
373 * @see ValidateFontFamilyName().
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
379 virtual void WriteMetricsToCache( const std::string& fontFamily,
380 const std::string& fontStyle,
381 const Integration::GlyphSet& glyphSet ) = 0;
384 * Retrieves file names from the given directory.
386 * @param[in] directoryName The directory name.
387 * @param[out] fileNames The file names in the given directory.
389 virtual void GetFileNamesFromDirectory( const std::string& directoryName,
390 std::vector<std::string>& fileNames ) = 0;
393 * Retrieves the glyph image which represents the character.
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.
400 * @return A bitmap representing the character.
402 virtual Integration::BitmapPtr GetGlyphImage( const std::string& fontFamily, const std::string& fontStyle, float fontSize, uint32_t character ) const = 0;
404 }; // class PlatformAbstraction
406 } // namespace Integration
410 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__