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-type-path-id-map.h>
24 #include <dali/internal/event/resources/resource-ticket.h>
25 #include <dali/internal/event/images/context-recovery-interface.h>
26 #include <dali/internal/event/images/image-factory-cache.h>
35 namespace ImageFactoryCache
41 * ImageFactory is an object that manages Image resource load requests.
42 * It utilises an internal caching system where previous requests and associated
43 * resources are stored to avoid accessing the file system when not necessary.
45 class ImageFactory : public ImageFactoryCache::RequestLifetimeObserver
52 ImageFactory( ResourceClient& resourceClient );
57 virtual ~ImageFactory();
60 * Registers a request for an image resource if not yet available, but does not start loading yet.
61 * Use Load( req ) to issue load request.
62 * If image was already requested, an existing request is returned.
63 * @param [in] filename path of requested image resource
64 * @param [in] attributes pointer to the ImageAttributes of the request. If NULL, default attributes are used.
65 * @return request pointer
67 ImageFactoryCache::Request* RegisterRequest( const std::string& filename, const ImageAttributes *attributes );
70 * Issue a request which has already been registered with ImageFactory.
71 * If the associated Ticket is no longer alive ImageFactory issues a resource load request.
72 * @param [in] request Request to be loaded.
73 * @return intrusive pointer to image ticket. If Load fails, returned pointer is invalid. (!ret)
75 ResourceTicketPtr Load( ImageFactoryCache::Request& request );
78 * Tells ResourceManager to reload image from filesystem.
79 * Also sends message to render thread.
80 * This operation uses the originally requested attributes when reloading the image.
81 * @pre req must be registered with ImageFactory
82 * @note if image is still loading, no new load request will be issued
83 * @param[in] request Request to be reloaded.
84 * @return the ResourceTicket mapped to the request
86 ResourceTicketPtr Reload( ImageFactoryCache::Request& request );
89 * Ensures all filesystem images are reloaded into textures.
90 * This operation uses the originally requested attributes when reloading the image.
92 * Recovering from context loss does not change the number of tickets if the
93 * image size has changed on the file system since the last load/reload.
95 * If two different requests mapped to the same resource before, they will still
96 * map to the same resource after context regain even if there would be a better
98 * @pre requests must be registered with ImageFactory
99 * @note If an image is still loading, no new load request will be issued.
101 void RecoverFromContextLoss();
104 * Register an object into the context recovery list of the image factory.
105 * Thus its RecoverFromContextLoss() function would be called when the Stage regaining context.
106 * @param[in] object The object whose RecoverFromContextLoss() function needs to be called to regain the context.
108 void RegisterForContextRecovery( ContextRecoveryInterface* object );
111 * Unregister an object from the context recovery list of the image factory
112 * @param[in] object The object whose RecoverFromContextLoss() function needs to be called to regain the context.
114 void UnregisterFromContextRecovery( ContextRecoveryInterface* object );
117 * Get resource path used in request.
118 * @param [in] request of the image
119 * @return resource path
121 const std::string& GetRequestPath( const ImageFactoryCache::RequestPtr& request ) const;
124 * Get ImageAttributes for an already requested image resource.
125 * @pre id should mark an existing Resource (Ticket is alive)
126 * @param [in] ticket of the image
127 * @return ImageAttributes used for request.
128 * @throws Throws exception if id is not valid.
130 const ImageAttributes& GetActualAttributes( const ResourceTicketPtr& ticket ) const;
133 * Get ImageAttributes used for request.
134 * @pre req must point to a Request registered with ImageFactory
135 * @param [in] request of the image
136 * @return ImageAttributes used for request.
138 const ImageAttributes& GetRequestAttributes( const ImageFactoryCache::RequestPtr& request ) const;
141 * Retrieve the size of an image. This is either the application requested size or
142 * the actual (full size) that is or will be loaded.
143 * @param[in] request of the image
144 * @param[in] ticket of the image
145 * @param[out] size of the image
147 void GetImageSize( const ImageFactoryCache::RequestPtr& request, const ResourceTicketPtr& ticket, Size& size );
150 * Prevents releasing and reloading image resources in the same frame
151 * @param [in] ticket the resource ticket to queue for releasing
153 void ReleaseTicket( ResourceTicket* ticket );
156 * Flush the queue of resource tickets that were about to be relased.
157 * This discards the kept ticket handles at the end of each frame, and this way prevents
158 * releasing and reloading image resources in the same frame.
160 void FlushReleaseQueue();
162 public: // From RequestLifetimeObserver
165 * Finds request by id in mRequestCache and mUrlCache and removes relevant entries.
166 * @param [in] id request id
168 virtual void RequestDiscarded( const ImageFactoryCache::Request& request );
173 ImageFactory( const ImageFactory& );
176 ImageFactory& operator=( const ImageFactory& rhs );
179 * Checks if the previously loaded image's attributes are compatible with a new request
180 * @param [in] requested The requested attributes
181 * @param [in] actual The actual attributes
182 * @return True if the attributes are compatible
184 bool CompareAttributes( const ImageAttributes& requested,
185 const ImageAttributes& actual ) const;
188 * Inserts a new request to the request cache and url cache.
189 * @note this method increases the current request Id counter (mReqIdCurrent)
190 * @param [in] resourceId Ticket id to insert.
191 * @param [in] url The requested url to insert.
192 * @param [in] urlHash Calculated hash value for the url.
193 * @param [in] attr Pointer to the requested attributes, NULL if default values are used.
194 * @return pointer to Request
196 ImageFactoryCache::Request* InsertNewRequest( ResourceId resourceId, const std::string& url, std::size_t urlHash, const ImageAttributes* attr );
199 * Searches request cache for exact match.
200 * @param [in] filename The url of the image resource.
201 * @param [in] hash Hash value for the filename.
202 * @param [in] attributes Pointer to ImageAttributes used for the request or NULL if default attributes were used.
203 * @return pointer to the found request or NULL if no exact match is found.
205 ImageFactoryCache::Request* FindRequest( const std::string& filename, size_t hash, const ImageAttributes *attributes );
208 * Searches through tickets to find a compatible resource.
209 * @param [in] filename The url of the image resource.
210 * @param [in] hash Hash value for the filename.
211 * @param [in] attributes Pointer to ImageAttributes used for the request or NULL if default attributes were used.
212 * @return A ticket pointer to the found resource or an unitialized pointer if no compatible one is found.
214 ResourceTicketPtr FindCompatibleResource( const std::string& filename, size_t hash, const ImageAttributes* attributes );
217 * Helper function that requests the image resource from platform abstraction.
218 * @param [in] filename The url of the image resource.
219 * @param [in] attributes Pointer to ImageAttributes to be used for the request or NULL if default attributes are used.
220 * @return intrusive pointer to Ticket
222 ResourceTicketPtr IssueLoadRequest( const std::string& filename, const ImageAttributes* attributes );
225 * Looks-up the hash of the string locator of the already-registered Request
227 * @param[in] request The image load request to return a locator string hash for.
228 * @return The hash of the locator string used in the request.
230 std::size_t GetHashForCachedRequest( const ImageFactoryCache::Request& request );
233 ResourceClient& mResourceClient;
234 ImageFactoryCache::RequestPathHashMap mUrlCache; ///< A multimap of url hashes and request IDs
235 ImageFactoryCache::RequestIdMap mRequestCache; ///< A map of request IDs and request information.
236 ResourceTicketContainer mTicketsToRelease; ///< List of ticket handles
237 Vector<ContextRecoveryInterface*> mContextRecoveryList; ///< List of the objects who needs context recovery
238 float mMaxScale; ///< Defines maximum size difference between compatible resources
239 ImageFactoryCache::RequestId mReqIdCurrent; ///< Internal counter for Request IDs
242 } // namespace Internal
246 #endif // __DALI_INTERNAL_IMAGE_FACTORY_H__