dali/internal/event/images/image-factory.h

   1 #ifndef __DALI_INTERNAL_IMAGE_FACTORY_H__
   2 #define __DALI_INTERNAL_IMAGE_FACTORY_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/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>
  27
  28 namespace Dali
  29 {
  30
  31 namespace Internal
  32 {
  33 class ResourceType;
  34
  35 namespace ImageFactoryCache
  36 {
  37 struct Request;
  38 }
  39
  40 /**
  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.
  44  */
  45 class ImageFactory : public ImageFactoryCache::RequestLifetimeObserver
  46 {
  47 public:
  48
  49   /**
  50    * default constructor
  51    */
  52   ImageFactory( ResourceClient& resourceClient );
  53
  54   /**
  55    * Default destructor
  56    */
  57   virtual ~ImageFactory();
  58
  59   /**
  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
  66    */
  67   ImageFactoryCache::Request* RegisterRequest( const std::string& filename, const ImageAttributes *attributes );
  68
  69   /**
  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)
  74    */
  75   ResourceTicketPtr Load( ImageFactoryCache::Request& request );
  76
  77   /**
  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
  85    */
  86   ResourceTicketPtr Reload( ImageFactoryCache::Request& request );
  87
  88   /**
  89    * Ensures all filesystem images are reloaded into textures.
  90    * This operation uses the originally requested attributes when reloading the image.
  91    *
  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.
  94    *
  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
  97    * fitting texture.
  98    * @pre requests must be registered with ImageFactory
  99    * @note If an image is still loading, no new load request will be issued.
 100    */
 101   void RecoverFromContextLoss();
 102
 103   /**
 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.
 107    */
 108   void RegisterForContextRecovery( ContextRecoveryInterface* object  );
 109
 110   /**
 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.
 113    */
 114   void UnregisterFromContextRecovery( ContextRecoveryInterface* object  );
 115
 116   /**
 117    * Get resource path used in request.
 118    * @param [in] request of the image
 119    * @return     resource path
 120    */
 121   const std::string& GetRequestPath( const ImageFactoryCache::RequestPtr& request ) const;
 122
 123   /**
 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.
 129    */
 130   const ImageAttributes& GetActualAttributes( const ResourceTicketPtr& ticket ) const;
 131
 132   /**
 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.
 137    */
 138   const ImageAttributes& GetRequestAttributes( const ImageFactoryCache::RequestPtr& request ) const;
 139
 140   /**
 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
 146    */
 147   void GetImageSize( const ImageFactoryCache::RequestPtr& request, const ResourceTicketPtr& ticket, Size& size );
 148
 149   /**
 150    * Prevents releasing and reloading image resources in the same frame
 151    * @param [in] ticket the resource ticket to queue for releasing
 152    */
 153   void ReleaseTicket( ResourceTicket* ticket );
 154
 155   /**
 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.
 159    */
 160   void FlushReleaseQueue();
 161
 162 public: // From RequestLifetimeObserver
 163
 164   /**
 165    * Finds request by id in mRequestCache and mUrlCache and removes relevant entries.
 166    * @param [in] id request id
 167    */
 168   virtual void RequestDiscarded( const ImageFactoryCache::Request& request );
 169
 170 private:
 171
 172   // Undefined
 173   ImageFactory( const ImageFactory& );
 174
 175   // Undefined
 176   ImageFactory& operator=( const ImageFactory& rhs );
 177
 178   /**
 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
 183    */
 184   bool CompareAttributes( const ImageAttributes& requested,
 185                           const ImageAttributes& actual ) const;
 186
 187   /**
 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
 195    */
 196   ImageFactoryCache::Request* InsertNewRequest( ResourceId resourceId, const std::string& url, std::size_t urlHash, const ImageAttributes* attr );
 197
 198   /**
 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.
 204    */
 205   ImageFactoryCache::Request* FindRequest( const std::string& filename, size_t hash, const ImageAttributes *attributes );
 206
 207   /**
 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.
 213    */
 214   ResourceTicketPtr FindCompatibleResource( const std::string& filename, size_t hash, const ImageAttributes* attributes );
 215
 216   /**
 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
 221    */
 222   ResourceTicketPtr IssueLoadRequest( const std::string& filename, const ImageAttributes* attributes );
 223
 224   /**
 225    * Looks-up the hash of the string locator of the already-registered Request
 226    * passed in.
 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.
 229    */
 230   std::size_t GetHashForCachedRequest( const ImageFactoryCache::Request& request );
 231
 232 private:
 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
 240 };
 241
 242 } // namespace Internal
 243
 244 } // namespace Dali
 245
 246 #endif // __DALI_INTERNAL_IMAGE_FACTORY_H__