Merge remote-tracking branch 'origin/tizen' into new_text
[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/bitmap.h>
23 #include <dali/integration-api/resource-cache.h>
24
25 namespace Dali
26 {
27
28 namespace Integration
29 {
30
31 class Bitmap;
32 class DynamicsFactory;
33
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 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   /**
165    * Sets horizontal and vertical pixels per inch value that is used by the display
166    * @param[in] dpiHorizontal horizontal dpi value
167    * @param[in] dpiVertical   vertical dpi value
168    */
169   virtual void SetDpi (unsigned int dpiHorizontal, unsigned int dpiVertical) = 0;
170
171   /**
172    * Load a file into a buffer
173    * @param[in] filename The filename to load
174    * @param[out] buffer  A buffer to receive the file.
175    * @result             true if the file is loaded.
176    */
177   virtual bool LoadFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
178
179   /**
180    * Load a file into a buffer
181    * @param[in] filename The filename to save
182    * @param[out] buffer  A buffer containing some data
183    *                     The buffer is implemeneted with a std::vector. The size() member specifies the buffer length.
184    * @result             true if the file is saved.
185    */
186   virtual bool SaveFile(const std::string& filename, std::vector< unsigned char >& buffer) const = 0;
187
188   /**
189    * Get a pointer to the DynamicsFactory.
190    */
191   virtual DynamicsFactory* GetDynamicsFactory() = 0;
192
193   /**
194    * Load a shader binary file into a buffer
195    * @param[in] filename The shader binary filename to load
196    * @param[out] buffer  A buffer to receive the file.
197    * @result             true if the file is loaded.
198    */
199   virtual bool LoadShaderBinFile( const std::string& filename, std::vector< unsigned char >& buffer ) const = 0;
200
201 }; // class PlatformAbstraction
202
203 } // namespace Integration
204
205 } // namespace Dali
206
207 #endif // __DALI_INTEGRATION_PLATFORM_ABSTRACTION_H__