1 #ifndef __DALI_INTERNAL_IMAGE_FACTORY_H__
2 #define __DALI_INTERNAL_IMAGE_FACTORY_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/public-api/common/dali-vector.h>
23 #include <dali/internal/event/resources/resource-ticket.h>
24 #include <dali/internal/event/images/context-recovery-interface.h>
25 #include <dali/internal/event/images/image-factory-cache.h>
34 namespace ImageFactoryCache
40 * ImageFactory is an object that manages Image resource load requests.
41 * It utilises an internal caching system where previous requests and associated
42 * resources are stored to avoid accessing the file system when not necessary.
44 class ImageFactory : public ImageFactoryCache::RequestLifetimeObserver
51 ImageFactory( ResourceClient& resourceClient );
56 virtual ~ImageFactory();
59 * Registers a request for an image resource if not yet available, but does not start loading yet.
60 * Use Load( req ) to issue load request.
61 * If image was already requested, an existing request is returned.
62 * @param [in] filename path of requested image resource
63 * @param [in] attributes pointer to the ImageAttributes of the request. If NULL, default attributes are used.
64 * @return request pointer
66 ImageFactoryCache::Request* RegisterRequest( const std::string& filename, const ImageAttributes *attributes );
69 * Issue a request which has already been registered with ImageFactory.
70 * If the associated Ticket is no longer alive ImageFactory issues a resource load request.
71 * @param [in] request Request to be loaded.
72 * @return intrusive pointer to image ticket. If Load fails, returned pointer is invalid. (!ret)
74 ResourceTicketPtr Load( ImageFactoryCache::Request& request );
77 * Tells ResourceManager to reload image from filesystem.
78 * Also sends message to render thread.
79 * This operation uses the originally requested attributes when reloading the image.
80 * @pre req must be registered with ImageFactory
81 * @note if image is still loading, no new load request will be issued
82 * @param[in] request Request to be reloaded.
83 * @return the ResourceTicket mapped to the request
85 ResourceTicketPtr Reload( ImageFactoryCache::Request& request );
88 * Ensures all filesystem images are reloaded into textures.
89 * This operation uses the originally requested attributes when reloading the image.
91 * Recovering from context loss does not change the number of tickets if the
92 * image size has changed on the file system since the last load/reload.
94 * If two different requests mapped to the same resource before, they will still
95 * map to the same resource after context regain even if there would be a better
97 * @pre requests must be registered with ImageFactory
98 * @note If an image is still loading, no new load request will be issued.
100 void RecoverFromContextLoss();
103 * Register an object into the context recovery list of the image factory.
104 * Thus its RecoverFromContextLoss() function would be called when the Stage regaining context.
105 * @param[in] object The object whose RecoverFromContextLoss() function needs to be called to regain the context.
107 void RegisterForContextRecovery( ContextRecoveryInterface* object );
110 * Unregister an object from the context recovery list of the image factory
111 * @param[in] object The object whose RecoverFromContextLoss() function needs to be called to regain the context.
113 void UnregisterFromContextRecovery( ContextRecoveryInterface* object );
116 * Get resource path used in request.
117 * @param [in] request of the image
118 * @return resource path
120 const std::string& GetRequestPath( const ImageFactoryCache::RequestPtr& request ) const;
123 * Get ImageAttributes for an already requested image resource.
124 * @pre id should mark an existing Resource (Ticket is alive)
125 * @param [in] ticket of the image
126 * @return ImageAttributes used for request.
127 * @throws Throws exception if id is not valid.
129 const ImageAttributes& GetActualAttributes( const ResourceTicketPtr& ticket ) const;
132 * Get ImageAttributes used for request.
133 * @pre req must point to a Request registered with ImageFactory
134 * @param [in] request of the image
135 * @return ImageAttributes used for request.
137 const ImageAttributes& GetRequestAttributes( const ImageFactoryCache::RequestPtr& request ) const;
140 * Retrieve the size of an image. This is either the application requested size or
141 * the actual (full size) that is or will be loaded.
142 * @param[in] request of the image
143 * @param[in] ticket of the image
144 * @param[out] size of the image
146 void GetImageSize( const ImageFactoryCache::RequestPtr& request, const ResourceTicketPtr& ticket, Size& size );
149 * Prevents releasing and reloading image resources in the same frame
150 * @param [in] ticket the resource ticket to queue for releasing
152 void ReleaseTicket( ResourceTicket* ticket );
155 * Flush the queue of resource tickets that were about to be relased.
156 * This discards the kept ticket handles at the end of each frame, and this way prevents
157 * releasing and reloading image resources in the same frame.
159 void FlushReleaseQueue();
161 public: // From RequestLifetimeObserver
164 * Finds request by id in mRequestCache and mUrlCache and removes relevant entries.
165 * @param [in] id request id
167 virtual void RequestDiscarded( const ImageFactoryCache::Request& request );
172 ImageFactory( const ImageFactory& );
175 ImageFactory& operator=( const ImageFactory& rhs );
178 * Checks if the previously loaded image's attributes are compatible with a new request
179 * @param [in] requested The requested attributes
180 * @param [in] actual The actual attributes
181 * @return True if the attributes are compatible
183 bool CompareAttributes( const ImageAttributes& requested,
184 const ImageAttributes& actual ) const;
187 * Inserts a new request to the request cache and url cache.
188 * @note this method increases the current request Id counter (mReqIdCurrent)
189 * @param [in] resourceId Ticket id to insert.
190 * @param [in] url The requested url to insert.
191 * @param [in] urlHash Calculated hash value for the url.
192 * @param [in] attr Pointer to the requested attributes, NULL if default values are used.
193 * @return pointer to Request
195 ImageFactoryCache::Request* InsertNewRequest( ResourceId resourceId, const std::string& url, std::size_t urlHash, const ImageAttributes* attr );
198 * Searches request cache for exact match.
199 * @param [in] filename The url of the image resource.
200 * @param [in] hash Hash value for the filename.
201 * @param [in] attributes Pointer to ImageAttributes used for the request or NULL if default attributes were used.
202 * @return pointer to the found request or NULL if no exact match is found.
204 ImageFactoryCache::Request* FindRequest( const std::string& filename, size_t hash, const ImageAttributes *attributes );
207 * Searches through tickets to find a compatible resource.
208 * @param [in] filename The url of the image resource.
209 * @param [in] hash Hash value for the filename.
210 * @param [in] attributes Pointer to ImageAttributes used for the request or NULL if default attributes were used.
211 * @return A ticket pointer to the found resource or an unitialized pointer if no compatible one is found.
213 ResourceTicketPtr FindCompatibleResource( const std::string& filename, size_t hash, const ImageAttributes* attributes );
216 * Helper function that requests the image resource from platform abstraction.
217 * @param [in] filename The url of the image resource.
218 * @param [in] attributes Pointer to ImageAttributes to be used for the request or NULL if default attributes are used.
219 * @return intrusive pointer to Ticket
221 ResourceTicketPtr IssueLoadRequest( const std::string& filename, const ImageAttributes* attributes );
224 * Looks-up the hash of the string locator of the already-registered Request
226 * @param[in] request The image load request to return a locator string hash for.
227 * @return The hash of the locator string used in the request.
229 std::size_t GetHashForCachedRequest( const ImageFactoryCache::Request& request );
232 ResourceClient& mResourceClient;
233 ImageFactoryCache::RequestPathHashMap mUrlCache; ///< A multimap of url hashes and request IDs
234 ImageFactoryCache::RequestIdMap mRequestCache; ///< A map of request IDs and request information.
235 ResourceTicketContainer mTicketsToRelease; ///< List of ticket handles
236 Vector<ContextRecoveryInterface*> mContextRecoveryList; ///< List of the objects who needs context recovery
237 float mMaxScale; ///< Defines maximum size difference between compatible resources
238 ImageFactoryCache::RequestId mReqIdCurrent; ///< Internal counter for Request IDs
241 } // namespace Internal
245 #endif // __DALI_INTERNAL_IMAGE_FACTORY_H__