DALi Version 1.2.57
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / visuals / texture-manager.h
1 #ifndef DALI_TOOLKIT_TEXTURE_MANAGER_H
2 #define DALI_TOOLKIT_TEXTURE_MANAGER_H
3
4 /*
5  * Copyright (c) 2017 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 // EXTERNAL INCLUDES
21 #include <deque>
22 #include <functional>
23 #include <string>
24 #include <dali/public-api/common/dali-vector.h>
25 #include <dali/public-api/object/ref-object.h>
26 #include <dali/public-api/rendering/texture-set.h>
27 #include <dali/devel-api/common/owner-container.h>
28 #include <dali/devel-api/adaptor-framework/pixel-buffer.h>
29
30 // INTERNAL INCLUDES
31 #include <dali-toolkit/devel-api/image-loader/async-image-loader-devel.h>
32 #include <dali-toolkit/devel-api/image-loader/image-atlas.h>
33 #include <dali-toolkit/public-api/image-loader/async-image-loader.h>
34 #include <dali-toolkit/internal/visuals/texture-upload-observer.h>
35 #include <dali-toolkit/internal/visuals/visual-url.h>
36 #include <dali-toolkit/internal/helpers/round-robin-container-view.h>
37 #include <dali-toolkit/internal/image-loader/async-image-loader-impl.h>
38
39
40 namespace Dali
41 {
42
43 namespace Toolkit
44 {
45
46 namespace Internal
47 {
48
49 /**
50  * The TextureManager provides a common Image loading API for Visuals.
51  *
52  * The TextureManager is responsible for providing sync, async, atlased and non-atlased loads.
53  * Texture caching is provided and performed when possible.
54  * Broken Images are automatically provided on load failure.
55  */
56 class TextureManager : public ConnectionTracker
57 {
58 public:
59
60   typedef int32_t TextureId;       ///< The TextureId type. This is used as a handle to refer to a particular Texture.
61   static const int INVALID_TEXTURE_ID = -1; ///< Used to represent a null TextureId or error
62
63   /**
64    * Whether the texture should be atlased or uploaded into it's own GPU texture
65    */
66   enum UseAtlas
67   {
68     NO_ATLAS,
69     USE_ATLAS
70   };
71
72   /**
73    * Whether the pixel data should be kept in TextureManager, or uploaded for rendering
74    */
75   enum StorageType
76   {
77     KEEP_PIXEL_BUFFER,
78     UPLOAD_TO_TEXTURE
79   };
80
81   /**
82    * Whether the texture should be loaded synchronously or asynchronously.
83    */
84   enum LoadType
85   {
86     LOAD_ASYNCHRONOUSLY,
87     LOAD_SYNCHRONOUSLY
88   };
89
90   /**
91    * @brief The LoadState Enumeration represents the current state of a particular Texture's life-cycle.
92    */
93   enum LoadState
94   {
95     NOT_STARTED,     ///< Default
96     LOADING,         ///< Loading has been started, but not finished.
97     LOAD_FINISHED,   ///< Loading has finished. (for CPU storage only)
98     WAITING_FOR_MASK,///< Loading has finished, but waiting for mask image
99     UPLOADED,        ///< Uploaded and ready. (For GPU upload only)
100     CANCELLED,       ///< Removed before loading completed
101     LOAD_FAILED      ///< Async loading failed, e.g. connection problem
102   };
103
104 public:
105
106   /**
107    * Constructor.
108    */
109   TextureManager();
110
111   /**
112    * Destructor.
113    */
114   ~TextureManager();
115
116
117   // TextureManager Main API:
118
119   /**
120    * @brief Requests an image load of the given URL.
121    *
122    * The parameters are used to specify how the image is loaded.
123    * The observer has the UploadComplete method called when the load is ready.
124    *
125    * When the client has finished with the Texture, Remove() should be called.
126    *
127    * @param[in] url               The URL of the image to load
128    * @param[in] desiredSize       The size the image is likely to appear at. This can be set to 0,0 for automatic
129    * @param[in] fittingMode       The FittingMode to use
130    * @param[in] samplingMode      The SamplingMode to use
131    * @param[in] useAtlasing       Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still be loaded, and marked successful,
132    *                              but "useAtlasing" will be set to false in the "UploadCompleted" callback from the TextureManagerUploadObserver.
133    * @param[in] observer          The client object should inherit from this and provide the "UploadCompleted" virtual.
134    *                              This is called when an image load completes (or fails).
135    * @return                      A TextureId to use as a handle to reference this Texture
136    */
137   TextureId RequestLoad( const VisualUrl&         url,
138                          const ImageDimensions    desiredSize,
139                          FittingMode::Type        fittingMode,
140                          Dali::SamplingMode::Type samplingMode,
141                          const UseAtlas           useAtlasing,
142                          TextureUploadObserver*   observer );
143
144   /**
145    * @brief Requests an image load of the given URL, when the texture has
146    * have loaded, it will perform a blend with the image mask, and upload
147    * the blended texture.
148    *
149    * The parameters are used to specify how the image is loaded.
150    * The observer has the UploadComplete method called when the load is ready.
151    *
152    * When the client has finished with the Texture, Remove() should be called.
153    *
154    * @param[in] url               The URL of the image to load
155    * @param[in] maskTextureId     The texture id of an image to mask this with (can be INVALID if no masking required)
156    * @param[in] contentScale      The scale factor to apply to the image before masking
157    * @param[in] desiredSize       The size the image is likely to appear at. This can be set to 0,0 for automatic
158    * @param[in] fittingMode       The FittingMode to use
159    * @param[in] samplingMode      The SamplingMode to use
160    * @param[in] useAtlasing       Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still be loaded, and marked successful,
161    *                              but "useAtlasing" will be set to false in the "UploadCompleted" callback from the TextureManagerUploadObserver.
162    * @param[in] cropToMask        Only used with masking, this will crop the scaled image to the mask size. If false, then the mask will be scaled to fit the image before being applied.
163    * @param[in] observer          The client object should inherit from this and provide the "UploadCompleted" virtual.
164    *                              This is called when an image load completes (or fails).
165    * @return                      A TextureId to use as a handle to reference this Texture
166    */
167   TextureId RequestLoad( const VisualUrl&         url,
168                          TextureId                maskTextureId,
169                          float                    contentScale,
170                          const ImageDimensions    desiredSize,
171                          FittingMode::Type        fittingMode,
172                          Dali::SamplingMode::Type samplingMode,
173                          const UseAtlas           useAtlasing,
174                          bool                     cropToMask,
175                          TextureUploadObserver*   observer );
176
177   /**
178    * Requests a masking image to be loaded. This mask is not uploaded to GL,
179    * instead, it is stored in CPU memory, and can be used for CPU blending.
180    */
181   TextureId RequestMaskLoad( const VisualUrl& maskUrl );
182
183   /**
184    * @brief Remove a Texture from the TextureManager.
185    *
186    * Textures are cached and therefore only the removal of the last
187    * occurrence of a Texture will cause its removal internally.
188    *
189    * @param[in] textureId The ID of the Texture to remove.
190    */
191   void Remove( const TextureManager::TextureId textureId );
192
193   /**
194    * Get the visualUrl associated with the texture id
195    */
196   const VisualUrl& GetVisualUrl( TextureId textureId );
197
198   /**
199    * @brief Get the current state of a texture
200    * @param[in] textureId The texture id to query
201    * @return The loading state if the texture is valid, or NOT_STARTED if the textureId
202    * is not valid.
203    */
204   LoadState GetTextureState( TextureId textureId );
205
206   /**
207    * @brief Get the associated texture set if the texture id is valid
208    * @param[in] textureId The texture Id to look up
209    * @return the associated texture set, or an empty handle if textureId is not valid
210    */
211   TextureSet GetTextureSet( TextureId textureId );
212
213 private:
214
215   /**
216    * @brief Requests an image load of the given URL, when the texture has
217    * have loaded, if there is a valid maskTextureId, it will perform a
218    * CPU blend with the mask, and upload the blend texture.
219    *
220    * The parameters are used to specify how the image is loaded.
221    * The observer has the UploadComplete method called when the load is ready.
222    *
223    * When the client has finished with the Texture, Remove() should be called.
224    *
225    * @param[in] url               The URL of the image to load
226    * @param[in] maskTextureId     The texture id of an image to use as a mask. If no mask is required, then set to INVALID_TEXTURE_ID
227    * @param[in] contentScale      The scaling factor to apply to the content when masking
228    * @param[in] desiredSize       The size the image is likely to appear at. This can be set to 0,0 for automatic
229    * @param[in] fittingMode       The FittingMode to use
230    * @param[in] samplingMode      The SamplingMode to use
231    * @param[in] useAtlasing       Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still be loaded, and marked successful,
232    *                              but "useAtlasing" will be set to false in the "UploadCompleted" callback from the TextureManagerUploadObserver.
233    * @param[in] cropToMask        Whether to crop the target after masking, or scale the mask to the image before masking.
234    * @param[in] storageType,      Whether the pixel data is stored in the cache or uploaded to the GPU
235    * @param[in] observer          The client object should inherit from this and provide the "UploadCompleted" virtual.
236    *                              This is called when an image load completes (or fails).
237    * @return                      A TextureId to use as a handle to reference this Texture
238    */
239   TextureId RequestLoadInternal(
240     const VisualUrl&         url,
241     TextureId                maskTextureId,
242     float                    contentScale,
243     const ImageDimensions    desiredSize,
244     FittingMode::Type        fittingMode,
245     Dali::SamplingMode::Type samplingMode,
246     UseAtlas                 useAtlas,
247     bool                     cropToMask,
248     StorageType              storageType,
249     TextureUploadObserver*   observer );
250
251
252   typedef size_t TextureHash; ///< The type used to store the hash used for Texture caching.
253
254   /**
255    * @brief This struct is used to manage the life-cycle of Texture loading and caching.
256    */
257   struct TextureInfo
258   {
259     TextureInfo( TextureId textureId,
260                  TextureId maskTextureId,
261                  const VisualUrl& url,
262                  ImageDimensions desiredSize,
263                  float scaleFactor,
264                  FittingMode::Type fittingMode,
265                  Dali::SamplingMode::Type samplingMode,
266                  bool loadSynchronously,
267                  bool cropToMask,
268                  UseAtlas useAtlas,
269                  TextureManager::TextureHash hash )
270     : url( url ),
271       desiredSize( desiredSize ),
272       useSize( desiredSize ),
273       atlasRect( 0.0f, 0.0f, 1.0f, 1.0f ), // Full atlas rectangle
274       textureId( textureId ),
275       maskTextureId( maskTextureId ),
276       hash( hash ),
277       scaleFactor( scaleFactor ),
278       referenceCount( 1u ),
279       loadState( NOT_STARTED ),
280       fittingMode( fittingMode ),
281       samplingMode( samplingMode ),
282       storageType( UPLOAD_TO_TEXTURE ),
283       loadSynchronously( loadSynchronously ),
284       useAtlas( useAtlas ),
285       cropToMask( cropToMask )
286     {
287     }
288
289     /**
290      * Container type used to store all observer clients of this Texture
291      */
292     typedef Dali::Vector< TextureUploadObserver* > ObserverListType;
293
294     ObserverListType observerList; ///< Container used to store all observer clients of this Texture
295     Toolkit::ImageAtlas atlas;     ///< The atlas this Texture lays within (if any)
296     Devel::PixelBuffer pixelBuffer;///< The PixelBuffer holding the image data (May be empty after upload)
297     TextureSet textureSet;         ///< The TextureSet holding the Texture
298     VisualUrl url;                 ///< The URL of the image
299     ImageDimensions desiredSize;   ///< The size requested
300     ImageDimensions useSize;       ///< The size used
301     Vector4 atlasRect;             ///< The atlas rect used if atlased
302     TextureId textureId;           ///< The TextureId associated with this Texture
303     TextureId maskTextureId;       ///< The mask TextureId to be applied on load
304     TextureManager::TextureHash hash; ///< The hash used to cache this Texture
305     float scaleFactor;             ///< The scale factor to apply to the Texture when masking
306     int16_t referenceCount;        ///< The reference count of clients using this Texture
307     LoadState loadState:3;         ///< The load state showing the load progress of the Texture
308     FittingMode::Type fittingMode:2; ///< The requested FittingMode
309     Dali::SamplingMode::Type samplingMode:3; ///< The requested SamplingMode
310     StorageType storageType:1;     ///< CPU storage / GPU upload;
311     bool loadSynchronously:1;      ///< True if synchronous loading was requested
312     UseAtlas useAtlas:1;           ///< USE_ATLAS if an atlas was requested. This is updated to false if atlas is not used
313     bool cropToMask:1;             ///< true if the image should be cropped to the mask size.
314   };
315
316   // Structs:
317
318   /**
319    * Struct to hold information about a requested Async load.
320    * This is used to look up a TextureManager::TextureId from the returned AsyncLoad Id.
321    */
322   struct AsyncLoadingInfo
323   {
324     AsyncLoadingInfo( TextureId textureId )
325     : textureId( textureId ),
326       loadId( 0 )
327     {
328     }
329
330     TextureId           textureId;   ///< The external Texture Id assigned to this load
331     unsigned short      loadId;      ///< The load Id used by the async loader to reference this load
332   };
333
334   /**
335    * @brief This struct is used within a container to manage atlas creation and destruction.
336    */
337   struct AtlasInfo
338   {
339     AtlasInfo( Toolkit::ImageAtlas atlas, TextureSet textureSet )
340     : atlas( atlas ),
341       textureSet( textureSet )
342     {
343     }
344
345     Toolkit::ImageAtlas                 atlas;                          ///< The ImageAtlas object
346     TextureSet                          textureSet;                     ///< The TextureSet is kept in the struct to allow fast lookup of TextureSet to Atlas
347   };
348
349   // Private typedefs:
350
351   typedef std::deque<AsyncLoadingInfo>  AsyncLoadingInfoContainerType;  ///< The container type used to manage Asynchronous loads in progress
352   typedef std::vector<AtlasInfo>        AtlasInfoContainerType;         ///< The container type used to manage Atlas creation and destruction
353   typedef std::vector<TextureInfo>      TextureInfoContainerType;       ///< The container type used to manage the life-cycle and caching of Textures
354
355   /**
356    * @brief Used internally to initiate a load.
357    * @param[in] textureInfo The TextureInfo struct associated with the Texture
358    * @return                True if the load was initiated
359    */
360   bool LoadTexture( TextureInfo& textureInfo );
361
362   /**
363    * Add the observer to the observer list
364    * @param[in] textureInfo The TextureInfo struct associated with the texture
365    * observer The observer wishing to observe the texture upload
366    */
367   void ObserveTexture( TextureInfo & textureInfo, TextureUploadObserver* observer );
368
369   /**
370    * @brief This signal handler is called when the async local loader finishes loading.
371    * @param[in] id        This is the async image loaders Id
372    * @param[in] pixelBuffer The loaded image data
373    */
374   void AsyncLocalLoadComplete( uint32_t id, Devel::PixelBuffer pixelBuffer );
375
376   /**
377    * @brief This signal handler is called when the async local loader finishes loading.
378    * @param[in] id        This is the async image loaders Id
379    * @param[in] pixelBuffer The loaded image data
380    */
381   void AsyncRemoteLoadComplete( uint32_t id, Devel::PixelBuffer pixelBuffer );
382
383   /**
384    * Common method to handle loading completion
385    * @param[in] container The Async loading container
386    * @param[in] id        This is the async image loaders Id
387    * @param[in] pixelBuffer The loaded image data
388    */
389   void AsyncLoadComplete( AsyncLoadingInfoContainerType& container, uint32_t id, Devel::PixelBuffer pixelBuffer );
390
391   /**
392    * @brief Performs Post-Load steps including atlasing.
393    * @param[in] textureInfo The struct associated with this Texture
394    * @param[in] pixelBuffer The image pixelBuffer
395    * @return    True if successful
396    */
397   void PostLoad( TextureManager::TextureInfo& textureInfo, Devel::PixelBuffer& pixelBuffer );
398
399   /**
400    * Check if there is a texture waiting to be masked. If there
401    * is then apply this mask and upload it.
402    * @param[in] maskTextureInfo The texture info of the mask that has just loaded.
403    */
404   void CheckForWaitingTexture( TextureInfo& maskTextureInfo );
405
406   /**
407    * Apply the mask to the pixelBuffer.
408    * @param[in] pixelBuffer The pixelBuffer to apply the mask to
409    * @param[in] maskTextureId The texture id of the mask.
410    * @param[in] contentScale The factor to scale the content
411    * @param[in] cropToMask Whether to crop the content to the mask size
412    */
413   void ApplyMask( Devel::PixelBuffer& pixelBuffer, TextureId maskTextureId,
414                   float contentScale, bool cropToMask );
415
416   /**
417    * Upload the texture specified in pixelBuffer to the appropriate location
418    * @param[in] pixelBuffer The image data to upload
419    * @param[in] textureInfo The texture info containing the location to
420    * store the data to.
421    */
422   void UploadTexture( Devel::PixelBuffer& pixelBuffer, TextureInfo& textureInfo );
423
424   /**
425    * Mark the texture as complete, and inform observers
426    * @param[in] textureInfo The struct associated with this Texture
427    */
428   void UploadComplete( TextureInfo& textureInfo );
429
430   /**
431    * Notify the current observers that the texture upload is complete,
432    * then remove the observers from the list.
433    * @param[in] textureInfo The struct associated with this Texture
434    * @param[in] success If the pixel data was retrieved successfully and uploaded to GPU
435    */
436   void NotifyObservers( TextureInfo& textureInfo, bool success );
437
438   /**
439    * @brief Generates a new, unique TextureId
440    * @return A unique TextureId
441    */
442   TextureManager::TextureId GenerateUniqueTextureId();
443
444   /**
445    * @brief Used to lookup an index into the TextureInfoContainer from a TextureId
446    * @param[in] textureId The TextureId to look up
447    * @return              The cache index
448    */
449   int GetCacheIndexFromId( TextureId textureId );
450
451
452   /**
453    * @brief Generates a hash for caching based on the input parameters.
454    * Only applies size, fitting mode andsampling mode if the size is specified.
455    * Only applies maskTextureId if it isn't INVALID_TEXTURE_ID
456    * Always applies useAtlas.
457    * @param[in] url          The URL of the image to load
458    * @param[in] size         The image size
459    * @param[in] fittingMode  The FittingMode to use
460    * @param[in] samplingMode The SamplingMode to use
461    * @param[in] useAtlas     True if atlased
462    * @param[in] maskTextureId The masking texture id (or INVALID_TEXTURE_ID)
463    * @return                 A hash of the provided data for caching.
464    */
465   TextureHash GenerateHash( const std::string& url, const ImageDimensions size,
466                             const FittingMode::Type fittingMode,
467                             const Dali::SamplingMode::Type samplingMode, const UseAtlas useAtlas,
468                             TextureId maskTextureId );
469   /**
470    * @brief Looks up a cached texture by its hash.
471    * If found, the given parameters are used to check there is no hash-collision.
472    * @param[in] hash          The hash to look up
473    * @param[in] url           The URL of the image to load
474    * @param[in] size          The image size
475    * @param[in] fittingMode   The FittingMode to use
476    * @param[in] samplingMode  The SamplingMode to use
477    * @param[in] useAtlas      True if atlased
478    * @param[in] maskTextureId Optional texture ID to use to mask this image
479    * @return A TextureId of a cached Texture if found. Or INVALID_TEXTURE_ID if not found.
480    */
481   TextureManager::TextureId FindCachedTexture(
482     const TextureManager::TextureHash hash,
483     const std::string& url,
484     const ImageDimensions size,
485     const FittingMode::Type fittingMode,
486     const Dali::SamplingMode::Type samplingMode,
487     const bool useAtlas,
488     TextureId maskTextureId );
489
490 private:
491
492   /**
493    * @brief Helper class to keep the relation between AsyncImageLoader and corresponding LoadingInfo container
494    */
495   class AsyncLoadingHelper : public ConnectionTracker
496   {
497   public:
498     /**
499      * @brief Create an AsyncLoadingHelper.
500      * @param[in] textureManager Reference to the texture manager
501      */
502     AsyncLoadingHelper(TextureManager& textureManager);
503
504     /**
505      * @brief Load a new texture.
506      * @param[in] textureId             TextureId to reference the texture that will be loaded
507      * @param[in] url                   The URL of the image to load
508      * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
509      * @param[in] fittingMode           The FittingMode to use
510      * @param[in] samplingMode          The SamplingMode to use
511      * @param[in] orientationCorrection Whether to use image metadata to rotate or flip the image, e.g., from portrait to landscape
512      */
513     void Load(TextureId textureId,
514               const VisualUrl& url,
515               ImageDimensions desiredSize,
516               FittingMode::Type fittingMode,
517               SamplingMode::Type samplingMode,
518               bool orientationCorrection);
519
520   public:
521     AsyncLoadingHelper(const AsyncLoadingHelper&) = delete;
522     AsyncLoadingHelper& operator=(const AsyncLoadingHelper&) = delete;
523
524     AsyncLoadingHelper(AsyncLoadingHelper&& rhs);
525     AsyncLoadingHelper& operator=(AsyncLoadingHelper&&rhs) = delete;
526
527   private:
528     /**
529      * @brief Main constructor that used by all other constructors
530      */
531     AsyncLoadingHelper(Toolkit::AsyncImageLoader loader,
532                        TextureManager& textureManager,
533                        AsyncLoadingInfoContainerType&& loadingInfoContainer);
534
535     /**
536      * @brief Callback to be called when texture loading is complete, it passes the pixel buffer on to texture manager.
537      * @param[in] id          Loader id
538      * @param[in] pixelBuffer Image data
539      */
540     void AsyncLoadComplete(uint32_t id, Devel::PixelBuffer pixelBuffer);
541
542   private:
543     Toolkit::AsyncImageLoader     mLoader;
544     TextureManager&               mTextureManager;
545     AsyncLoadingInfoContainerType mLoadingInfoContainer;
546   };
547
548 private:
549
550   /**
551    * Deleted copy constructor.
552    */
553   TextureManager( const TextureManager& ) = delete;
554
555   /**
556    * Deleted assignment operator.
557    */
558   TextureManager& operator=( const TextureManager& rhs ) = delete;
559
560   /**
561    * This is called by the TextureManagerUploadObserver when an observer is destroyed.
562    * We use the callback to know when to remove an observer from our notify list.
563    * @param[in] observer The observer that generated the callback
564    */
565   void ObserverDestroyed( TextureUploadObserver* observer );
566
567 private:  // Member Variables:
568
569   AtlasInfoContainerType        mAtlasContainer;                  ///< Used to manage Atlas creation and destruction
570   TextureInfoContainerType      mTextureInfoContainer;            ///< Used to manage the life-cycle and caching of Textures
571   TextureId                     mCurrentTextureId;                ///< The current value used for the unique Texture Id generation
572
573   RoundRobinContainerView<AsyncLoadingHelper> mAsyncLocalLoaders;  ///< The Asynchronous image loaders used to provide all local async loads
574   RoundRobinContainerView<AsyncLoadingHelper> mAsyncRemoteLoaders; ///< The Asynchronous image loaders used to provide all remote async loads
575 };
576
577
578 } // name Internal
579
580 } // namespace Toolkit
581
582 } // namespace Dali
583
584 #endif // DALI_TOOLKIT_TEXTURE_MANAGER_H