[dali_1.9.30] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / visuals / texture-manager-impl.h
1 #ifndef DALI_TOOLKIT_TEXTURE_MANAGER_IMPL_H
2 #define DALI_TOOLKIT_TEXTURE_MANAGER_IMPL_H
3
4 /*
5  * Copyright (c) 2020 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 <memory>
25 #include <dali/public-api/common/dali-vector.h>
26 #include <dali/public-api/object/ref-object.h>
27 #include <dali/public-api/rendering/texture-set.h>
28 #include <dali/devel-api/common/owner-container.h>
29 #include <dali/devel-api/adaptor-framework/pixel-buffer.h>
30 #include <dali/public-api/rendering/geometry.h>
31
32 // INTERNAL INCLUDES
33 #include <dali-toolkit/devel-api/image-loader/async-image-loader-devel.h>
34 #include <dali-toolkit/devel-api/image-loader/image-atlas.h>
35 #include <dali-toolkit/public-api/image-loader/async-image-loader.h>
36 #include <dali-toolkit/internal/visuals/texture-upload-observer.h>
37 #include <dali-toolkit/internal/visuals/visual-url.h>
38 #include <dali-toolkit/internal/helpers/round-robin-container-view.h>
39 #include <dali-toolkit/internal/image-loader/async-image-loader-impl.h>
40
41
42 namespace Dali
43 {
44
45 namespace Toolkit
46 {
47
48 namespace Internal
49 {
50 class ImageAtlasManager;
51 typedef IntrusivePtr<ImageAtlasManager> ImageAtlasManagerPtr;
52
53 /**
54  * The TextureManager provides a common Image loading API for Visuals.
55  *
56  * The TextureManager is responsible for providing sync, async, atlased and non-atlased loads.
57  * Texture caching is provided and performed when possible.
58  * Broken Images are automatically provided on load failure.
59  */
60 class TextureManager : public ConnectionTracker
61 {
62 public:
63
64   typedef int32_t TextureId;       ///< The TextureId type. This is used as a handle to refer to a particular Texture.
65   static const int INVALID_TEXTURE_ID = -1; ///< Used to represent a null TextureId or error
66
67   /**
68    * Whether the texture should be atlased or uploaded into it's own GPU texture
69    */
70   enum UseAtlas
71   {
72     NO_ATLAS,
73     USE_ATLAS
74   };
75
76   /**
77    * Whether the pixel data should be kept in TextureManager, returned with pixelBuffer or uploaded for rendering
78    */
79   enum StorageType
80   {
81     KEEP_PIXEL_BUFFER,
82     RETURN_PIXEL_BUFFER,
83     UPLOAD_TO_TEXTURE
84   };
85
86   /**
87    * Whether the texture should be loaded synchronously or asynchronously.
88    */
89   enum LoadType
90   {
91     LOAD_ASYNCHRONOUSLY,
92     LOAD_SYNCHRONOUSLY
93   };
94
95   /**
96    * @brief The LoadState Enumeration represents the current state of a particular Texture's life-cycle.
97    */
98   enum LoadState
99   {
100     NOT_STARTED,     ///< Default
101     LOADING,         ///< Loading has been started, but not finished.
102     LOAD_FINISHED,   ///< Loading has finished. (for CPU storage only)
103     WAITING_FOR_MASK,///< Loading has finished, but waiting for mask image
104     MASK_APPLYING,   ///< Loading has finished, Mask is applying
105     MASK_APPLIED,    ///< Loading has finished, Mask is applyied by GPU
106     UPLOADED,        ///< Uploaded and ready. (For GPU upload only)
107     CANCELLED,       ///< Removed before loading completed
108     LOAD_FAILED      ///< Async loading failed, e.g. connection problem
109   };
110
111   /**
112    * @brief Types of reloading policies
113    */
114   enum class ReloadPolicy
115   {
116     CACHED = 0,             ///< Loads cached texture if it exists.
117     FORCED                  ///< Forces reloading of texture.
118   };
119
120   /**
121    * @brief Whether to multiply alpha into color channels on load
122    */
123   enum class MultiplyOnLoad
124   {
125     LOAD_WITHOUT_MULTIPLY = 0, ///< Don't modify the image
126     MULTIPLY_ON_LOAD           ///< Multiply alpha into color channels on load
127   };
128
129 public:
130
131   struct MaskingData
132   {
133     MaskingData();
134     ~MaskingData() = default;
135
136     VisualUrl mAlphaMaskUrl;
137     TextureManager::TextureId mAlphaMaskId;
138     float mContentScaleFactor;
139     bool mCropToMask;
140   };
141   using MaskingDataPointer = std::unique_ptr<MaskingData>;
142
143
144   /**
145    * Class to provide lifecycle event on destruction of texture manager.
146    */
147   struct LifecycleObserver
148   {
149     /**
150      * Called shortly before the texture manager is destroyed.
151      */
152     virtual void TextureManagerDestroyed() = 0;
153   };
154
155   /**
156    * Constructor.
157    */
158   TextureManager();
159
160   /**
161    * Destructor.
162    */
163   ~TextureManager();
164
165   // TextureManager Main API:
166
167   /**
168    * @brief Requests an frame of animated image load.
169    *
170    * The parameters are used to specify how the animated image is loaded.
171    * The observer has the LoadComplete method called when the load is ready.
172    *
173    * @param[in] animatedImageLoading  The AnimatedImageLoading that contain the animated image information
174    * @param[in] frameIndex            The frame index to load.
175    * @param[in] samplingMode          The SamplingMode to use
176    * @param[in] synchronousLoading    true if the frame should be loaded synchronously
177    * @param[out] textureId            The textureId of the frame
178    * @param[in] wrapModeU             Horizontal Wrap mode
179    * @param[in] wrapModeV             Vertical Wrap mode
180    * @param[in] textureObserver       The client object should inherit from this and provide the "UploadCompleted" virtual.
181    *                                  This is called when an image load completes (or fails).
182    *
183    * @return                          The texture set containing the frame of animated image, or empty if still loading.
184    */
185
186   TextureSet LoadAnimatedImageTexture( Dali::AnimatedImageLoading animatedImageLoading,
187                                        uint32_t frameIndex,
188                                        Dali::SamplingMode::Type samplingMode,
189                                        bool synchronousLoading,
190                                        TextureManager::TextureId& textureId,
191                                        Dali::WrapMode::Type wrapModeU, Dali::WrapMode::Type wrapModeV,
192                                        TextureUploadObserver* textureObserver );
193
194   /**
195    * @brief Requests an image load of the given URL to get PixelBuffer.
196    *
197    * The parameters are used to specify how the image is loaded.
198    * The observer has the LoadComplete method called when the load is ready.
199    *
200    * @param[in] url                   The URL of the image to load
201    * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
202    * @param[in] fittingMode           The FittingMode to use
203    * @param[in] samplingMode          The SamplingMode to use
204    * @param[in] synchronousLoading    true if the URL should be loaded synchronously
205    * @param[in] textureObserver       The client object should inherit from this and provide the "UploadCompleted" virtual.
206    *                                  This is called when an image load completes (or fails).
207    * @param[in] orientationCorrection Whether to rotate image to match embedded orientation data
208    * @param[in,out] preMultiplyOnLoad True if the image color should be multiplied by it's alpha. Set to false if the
209    *                                  image has no alpha channel
210    *
211    * @return                          The pixel buffer containing the image, or empty if still loading.
212    */
213
214   Devel::PixelBuffer LoadPixelBuffer( const VisualUrl& url,
215                                       Dali::ImageDimensions desiredSize,
216                                       Dali::FittingMode::Type fittingMode,
217                                       Dali::SamplingMode::Type samplingMode,
218                                       bool synchronousLoading,
219                                       TextureUploadObserver* textureObserver,
220                                       bool orientationCorrection,
221                                       TextureManager::MultiplyOnLoad& preMultiplyOnLoad );
222
223
224   /**
225    * @brief Requests an image load of the given URL.
226    *
227    * The parameters are used to specify how the image is loaded.
228    * The observer has the UploadComplete method called when the load is ready.
229    *
230    * When the client has finished with the Texture, Remove() should be called.
231    *
232    * @param[in] url                   The URL of the image to load
233    * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
234    * @param[in] fittingMode           The FittingMode to use
235    * @param[in] samplingMode          The SamplingMode to use
236    * @param[in, out] maskInfo         Mask info structure
237    * @param[in] synchronousLoading    true if the URL should be loaded synchronously
238    * @param[out] textureId,           The textureId of the URL
239    * @param[out] textureRect          The rectangle within the texture atlas that this URL occupies,
240    *                                  this is the rectangle in normalized coordinates.
241    * @param[out] textureRectSize      The rectangle within the texture atlas that this URL occupies,
242    *                                  this is the same rectangle in pixels.
243    * @param[in,out] atlasingStatus    Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still
244    *                                  be loaded, and marked successful, but this will be set to false.
245    *                                  If atlasing succeeds, this will be set to true.
246    * @param[out] loadingStatus        The loading status of the texture
247    * @param[in] wrapModeU             Horizontal Wrap mode
248    * @param[in] wrapModeV             Vertical Wrap mode
249    * @param[in] textureObserver       The client object should inherit from this and provide the "UploadCompleted" virtual.
250    *                                  This is called when an image load completes (or fails).
251    * @param[in] atlasObserver         This is used if the texture is atlased, and will be called instead of
252    *                                  textureObserver.UploadCompleted
253    * @param[in] imageAtlasManager     The atlas manager to use for atlasing textures
254    * @param[in] orientationCorrection Whether to rotate image to match embedded orientation data
255    * @param[in] reloadPolicy          Forces a reload of the texture even if already cached
256    * @param[in,out] preMultiplyOnLoad True if the image color should be multiplied by it's alpha. Set to false if the
257    *                                  image has no alpha channel
258    *
259    * @return                          The texture set containing the image, or empty if still loading.
260    */
261
262   TextureSet LoadTexture( const VisualUrl&             url,
263                           Dali::ImageDimensions        desiredSize,
264                           Dali::FittingMode::Type      fittingMode,
265                           Dali::SamplingMode::Type     samplingMode,
266                           MaskingDataPointer&          maskInfo,
267                           bool                         synchronousLoading,
268                           TextureManager::TextureId&   textureId,
269                           Vector4&                     textureRect,
270                           Dali::ImageDimensions&       textureRectSize,
271                           bool&                        atlasingStatus,
272                           bool&                        loadingStatus,
273                           Dali::WrapMode::Type         wrapModeU,
274                           Dali::WrapMode::Type         wrapModeV,
275                           TextureUploadObserver*       textureObserver,
276                           AtlasUploadObserver*         atlasObserver,
277                           ImageAtlasManagerPtr         imageAtlasManager,
278                           bool                         orientationCorrection,
279                           TextureManager::ReloadPolicy reloadPolicy,
280                           MultiplyOnLoad&              preMultiplyOnLoad );
281
282   /**
283    * @brief Requests an image load of the given URL.
284    *
285    * The parameters are used to specify how the image is loaded.
286    * The observer has the UploadComplete method called when the load is ready.
287    *
288    * When the client has finished with the Texture, Remove() should be called.
289    *
290    * @param[in] url                   The URL of the image to load
291    * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
292    * @param[in] fittingMode           The FittingMode to use
293    * @param[in] samplingMode          The SamplingMode to use
294    * @param[in] useAtlasing           Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still be loaded, and marked successful,
295    *                                  but "useAtlasing" will be set to false in the "UploadCompleted" callback from the TextureManagerUploadObserver.
296    * @param[in] observer              The client object should inherit from this and provide the "UploadCompleted" virtual.
297    *                                  This is called when an image load completes (or fails).
298    * @param[in] orientationCorrection Whether to rotate image to match embedded orientation data
299    * @param[in] reloadPolicy          Forces a reload of the texture even if already cached
300    * @param[in,out] preMultiplyOnLoad     True if the image color should be multiplied by it's alpha. Set to false if the image has no alpha channel
301    * @return                          A TextureId to use as a handle to reference this Texture
302    */
303   TextureId RequestLoad( const VisualUrl&                   url,
304                          const ImageDimensions              desiredSize,
305                          FittingMode::Type                  fittingMode,
306                          Dali::SamplingMode::Type           samplingMode,
307                          const UseAtlas                     useAtlasing,
308                          TextureUploadObserver*             observer,
309                          bool                               orientationCorrection,
310                          TextureManager::ReloadPolicy       reloadPolicy,
311                          MultiplyOnLoad&                    preMultiplyOnLoad );
312
313   /**
314    * @brief Requests an image load of the given URL, when the texture has
315    * have loaded, it will perform a blend with the image mask, and upload
316    * the blended texture.
317    *
318    * The parameters are used to specify how the image is loaded.
319    * The observer has the UploadComplete method called when the load is ready.
320    *
321    * When the client has finished with the Texture, Remove() should be called.
322    *
323    * @param[in] url                   The URL of the image to load
324    * @param[in] maskTextureId         The texture id of an image to mask this with
325    *                                  (can be INVALID if no masking required)
326    * @param[in] contentScale          The scale factor to apply to the image before masking
327    * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
328    * @param[in] fittingMode           The FittingMode to use
329    * @param[in] samplingMode          The SamplingMode to use
330    * @param[in] useAtlasing           Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still
331    *                                  be loaded, and marked successful,
332    *                                  but "useAtlasing" will be set to false in the "UploadCompleted" callback from
333    *                                  the TextureManagerUploadObserver.
334    * @param[in] cropToMask            Only used with masking, this will crop the scaled image to the mask size.
335    *                                  If false, then the mask will be scaled to fit the image before being applied.
336    * @param[in] observer              The client object should inherit from this and provide the "UploadCompleted"
337    *                                  virtual.
338    *                                  This is called when an image load completes (or fails).
339    * @param[in] orientationCorrection Whether to rotate image to match embedded orientation data
340    * @param[in] reloadPolicy          Forces a reload of the texture even if already cached
341    * @param[in] preMultiplyOnLoad     True if the image color should be multiplied by it's alpha. Set to false if the
342    *                                  image has no alpha channel
343    * @return                          A TextureId to use as a handle to reference this Texture
344    */
345   TextureId RequestLoad( const VisualUrl&                   url,
346                          TextureId                          maskTextureId,
347                          float                              contentScale,
348                          const ImageDimensions              desiredSize,
349                          FittingMode::Type                  fittingMode,
350                          Dali::SamplingMode::Type           samplingMode,
351                          const UseAtlas                     useAtlasing,
352                          bool                               cropToMask,
353                          TextureUploadObserver*             observer,
354                          bool                               orientationCorrection,
355                          TextureManager::ReloadPolicy       reloadPolicy,
356                          MultiplyOnLoad&                    preMultiplyOnLoad );
357
358   /**
359    * Requests a masking image to be loaded. This mask is not uploaded to GL,
360    * instead, it is stored in CPU memory, and can be used for CPU blending.
361    */
362   TextureId RequestMaskLoad( const VisualUrl& maskUrl );
363
364   /**
365    * @brief Remove a Texture from the TextureManager.
366    *
367    * Textures are cached and therefore only the removal of the last
368    * occurrence of a Texture will cause its removal internally.
369    *
370    * @param[in] textureId The ID of the Texture to remove.
371    * @param[in] textureObserver The texture observer.
372    */
373   void Remove( const TextureManager::TextureId textureId, TextureUploadObserver* textureObserver );
374
375   /**
376    * @brief Get the visualUrl associated with the texture id.
377    * @param[in] textureId The texture Id to get
378    * @return The visual Url associated with the texture id.
379    */
380   VisualUrl GetVisualUrl( TextureId textureId );
381
382   /**
383    * @brief Get the current state of a texture
384    * @param[in] textureId The texture id to query
385    * @return The loading state if the texture is valid, or NOT_STARTED if the textureId
386    * is not valid.
387    */
388   LoadState GetTextureState( TextureId textureId );
389
390   /**
391    * @brief Get the associated texture set if the texture id is valid
392    * @param[in] textureId The texture Id to look up
393    * @return the associated texture set, or an empty handle if textureId is not valid
394    */
395   TextureSet GetTextureSet( TextureId textureId );
396
397   /**
398    * Adds an external texture to the texture manager
399    * @param[in] texture The texture to add
400    * @return string containing the URL for the texture
401    */
402   std::string AddExternalTexture( TextureSet& texture );
403
404   /**
405    * Removes an external texture from texture manager
406    * @param[in] url The string containing the texture to remove
407    * @return handle to the texture
408    */
409   TextureSet RemoveExternalTexture( const std::string& url );
410
411   /**
412    * Add an observer to the object.
413    * @param[in] observer The observer to add.
414    */
415   void AddObserver( TextureManager::LifecycleObserver& observer );
416
417   /**
418    * Remove an observer from the object
419    * @pre The observer has already been added.
420    * @param[in] observer The observer to remove.
421    */
422   void RemoveObserver( TextureManager::LifecycleObserver& observer );
423
424   /**
425    * @brief Set an image to be used when a visual has failed to correctly render
426    * @param[in] brokenImageUrl The broken image url.
427    */
428   void SetBrokenImageUrl(const std::string& brokenImageUrl);
429
430   /**
431    * @brief Returns the geometry associated with texture.
432    * @param[in] textureId Id of the texture
433    * @param[out] frontElements number of front elements
434    * @param[out] backElements number of back elements
435    * @return Returns valid geometry object
436    */
437   Geometry GetRenderGeometry(TextureId textureId, uint32_t& frontElements, uint32_t& backElements );
438
439 private:
440
441   /**
442    * @brief Requests an image load of the given URL, when the texture has
443    * have loaded, if there is a valid maskTextureId, it will perform a
444    * CPU blend with the mask, and upload the blend texture.
445    *
446    * The parameters are used to specify how the image is loaded.
447    * The observer has the UploadComplete method called when the load is ready.
448    *
449    * When the client has finished with the Texture, Remove() should be called.
450    *
451    * @param[in] url                   The URL of the image to load
452    * @param[in] maskTextureId         The texture id of an image to use as a mask. If no mask is required, then set
453    *                                  to INVALID_TEXTURE_ID
454    * @param[in] contentScale          The scaling factor to apply to the content when masking
455    * @param[in] desiredSize           The size the image is likely to appear at. This can be set to 0,0 for automatic
456    * @param[in] fittingMode           The FittingMode to use
457    * @param[in] samplingMode          The SamplingMode to use
458    * @param[in] useAtlasing           Set to USE_ATLAS to attempt atlasing. If atlasing fails, the image will still be
459    *                                  loaded, and marked successful, but "useAtlasing" will be set to false in the
460    *                                  "UploadCompleted" callback from the TextureManagerUploadObserver.
461    * @param[in] cropToMask            Whether to crop the target after masking, or scale the mask to the image before
462    *                                  masking.
463    * @param[in] storageType,          Whether the pixel data is stored in the cache or uploaded to the GPU
464    * @param[in] observer              The client object should inherit from this and provide the "UploadCompleted"
465    *                                  virtual.
466    *                                  This is called when an image load completes (or fails).
467    * @param[in] orientationCorrection Whether to rotate image to match embedded orientation data
468    * @param[in] reloadPolicy          Forces a reload of the texture even if already cached
469    * @param[in] preMultiplyOnLoad     True if the image color should be multiplied by it's alpha. Set to false if
470    *                                  there is no alpha
471    * @param[in] animatedImageLoading  The AnimatedImageLoading to load animated image
472    * @param[in] frameIndex            The frame index of a frame to be loaded frame
473    * @return                          A TextureId to use as a handle to reference this Texture
474    */
475   TextureId RequestLoadInternal(
476     const VisualUrl&                    url,
477     TextureId                           maskTextureId,
478     float                               contentScale,
479     const ImageDimensions               desiredSize,
480     FittingMode::Type                   fittingMode,
481     Dali::SamplingMode::Type            samplingMode,
482     UseAtlas                            useAtlas,
483     bool                                cropToMask,
484     StorageType                         storageType,
485     TextureUploadObserver*              observer,
486     bool                                orientationCorrection,
487     TextureManager::ReloadPolicy        reloadPolicy,
488     MultiplyOnLoad&                     preMultiplyOnLoad,
489     Dali::AnimatedImageLoading          animatedImageLoading,
490     uint32_t                            frameIndex );
491
492   /**
493    * @brief Get the current state of a texture
494    * @param[in] textureId The texture id to query
495    * @return The loading state if the texture is valid, or NOT_STARTED if the textureId
496    * is not valid.
497    */
498   LoadState GetTextureStateInternal( TextureId textureId );
499
500   typedef size_t TextureHash; ///< The type used to store the hash used for Texture caching.
501
502   // Structs:
503
504   /**
505    * @brief This struct is used to manage the life-cycle of Texture loading and caching.
506    */
507   struct TextureInfo
508   {
509     TextureInfo( TextureId textureId,
510                  TextureId maskTextureId,
511                  const VisualUrl& url,
512                  ImageDimensions desiredSize,
513                  float scaleFactor,
514                  FittingMode::Type fittingMode,
515                  Dali::SamplingMode::Type samplingMode,
516                  bool loadSynchronously,
517                  bool cropToMask,
518                  UseAtlas useAtlas,
519                  TextureManager::TextureHash hash,
520                  bool orientationCorrection,
521                  bool preMultiplyOnLoad,
522                  Dali::AnimatedImageLoading animatedImageLoading,
523                  uint32_t frameIndex )
524     : url( url ),
525       desiredSize( desiredSize ),
526       useSize( desiredSize ),
527       atlasRect( 0.0f, 0.0f, 1.0f, 1.0f ), // Full atlas rectangle
528       textureId( textureId ),
529       maskTextureId( maskTextureId ),
530       hash( hash ),
531       scaleFactor( scaleFactor ),
532       referenceCount( 1u ),
533       loadState( NOT_STARTED ),
534       fittingMode( fittingMode ),
535       samplingMode( samplingMode ),
536       storageType( UPLOAD_TO_TEXTURE ),
537       animatedImageLoading( animatedImageLoading ),
538       frameIndex( frameIndex ),
539       loadSynchronously( loadSynchronously ),
540       useAtlas( useAtlas ),
541       cropToMask( cropToMask ),
542       orientationCorrection( true ),
543       preMultiplyOnLoad( preMultiplyOnLoad ),
544       preMultiplied( false )
545     {
546     }
547
548     /**
549      * Container type used to store all observer clients of this Texture
550      */
551     typedef Dali::Vector< TextureUploadObserver* > ObserverListType;
552
553     ObserverListType observerList; ///< Container used to store all observer clients of this Texture
554     Toolkit::ImageAtlas atlas;     ///< The atlas this Texture lays within (if any)
555     Devel::PixelBuffer pixelBuffer;///< The PixelBuffer holding the image data (May be empty after upload)
556     TextureSet textureSet;         ///< The TextureSet holding the Texture
557     VisualUrl url;                 ///< The URL of the image
558     ImageDimensions desiredSize;   ///< The size requested
559     ImageDimensions useSize;       ///< The size used
560     Vector4 atlasRect;             ///< The atlas rect used if atlased
561     TextureId textureId;           ///< The TextureId associated with this Texture
562     TextureId maskTextureId;       ///< The mask TextureId to be applied on load
563     TextureManager::TextureHash hash; ///< The hash used to cache this Texture
564     float scaleFactor;             ///< The scale factor to apply to the Texture when masking
565     int16_t referenceCount;        ///< The reference count of clients using this Texture
566     LoadState loadState:4;         ///< The load state showing the load progress of the Texture
567     FittingMode::Type fittingMode:3; ///< The requested FittingMode
568     Dali::SamplingMode::Type samplingMode:3; ///< The requested SamplingMode
569     StorageType storageType:2;     ///< CPU storage / GPU upload;
570     Dali::AnimatedImageLoading animatedImageLoading; ///< AnimatedImageLoading that contains animated image information.
571     uint32_t frameIndex;           ///< frame index that be loaded, in case of animated image
572     bool loadSynchronously:1;      ///< True if synchronous loading was requested
573     UseAtlas useAtlas:2;           ///< USE_ATLAS if an atlas was requested.
574                                    ///< This is updated to false if atlas is not used
575     bool cropToMask:1;             ///< true if the image should be cropped to the mask size.
576     bool orientationCorrection:1;  ///< true if the image should be rotated to match exif orientation data
577     bool preMultiplyOnLoad:1;      ///< true if the image's color should be multiplied by it's alpha
578     bool preMultiplied:1;          ///< true if the image's color was multiplied by it's alpha
579   };
580
581   /**
582    * Structure to hold info about a texture load queued during NotifyObservers
583    */
584   struct LoadQueueElement
585   {
586     LoadQueueElement( TextureId textureId, TextureUploadObserver* observer )
587     : mTextureId( textureId ),
588       mObserver( observer )
589     {
590     }
591
592     TextureId mTextureId; ///< The texture id of the requested load.
593     TextureUploadObserver* mObserver; ///< Observer of texture load.
594   };
595
596   /**
597    * Struct to hold information about a requested Async load.
598    * This is used to look up a TextureManager::TextureId from the returned AsyncLoad Id.
599    */
600   struct AsyncLoadingInfo
601   {
602     AsyncLoadingInfo( TextureId textureId )
603     : textureId( textureId ),
604       loadId( 0 )
605     {
606     }
607
608     TextureId           textureId;   ///< The external Texture Id assigned to this load
609     uint32_t            loadId;      ///< The load Id used by the async loader to reference this load
610   };
611
612   // Private typedefs:
613
614   typedef std::deque<AsyncLoadingInfo>  AsyncLoadingInfoContainerType;  ///< The container type used to manage Asynchronous loads in progress
615   typedef std::vector<TextureInfo>      TextureInfoContainerType;       ///< The container type used to manage the life-cycle and caching of Textures
616
617   /**
618    * @brief Initiate a load or queue load if NotifyObservers is invoking callbacks
619    * @param[in] textureInfo The TextureInfo struct associated with the Texture
620    * @param[in] observer The observer wishing to observe the texture upload
621    */
622   void LoadOrQueueTexture( TextureInfo& textureInfo, TextureUploadObserver* observer );
623
624   /**
625    * @brief Queue a texture load to be subsequently handled by ProcessQueuedTextures.
626    * @param[in] textureInfo The TextureInfo struct associated with the Texture
627    * @param[in] observer The observer wishing to observe the texture upload
628    */
629   void QueueLoadTexture( TextureInfo& textureInfo, TextureUploadObserver* observer );
630
631   /**
632    * @brief Used internally to initiate a load.
633    * @param[in] textureInfo The TextureInfo struct associated with the Texture
634    * @param[in] observer The observer wishing to observe the texture upload
635    */
636   void LoadTexture( TextureInfo& textureInfo, TextureUploadObserver* observer );
637
638   /**
639    * @brief Initiate load of textures queued whilst NotifyObservers invoking callbacks.
640    */
641   void ProcessQueuedTextures();
642
643   /**
644    * Add the observer to the observer list
645    * @param[in] textureInfo The TextureInfo struct associated with the texture
646    * @param[in] observer The observer wishing to observe the texture upload
647    */
648   void ObserveTexture( TextureInfo & textureInfo, TextureUploadObserver* observer );
649
650   /**
651    * @brief This signal handler is called when the async local loader finishes loading.
652    * @param[in] id        This is the async image loaders Id
653    * @param[in] pixelBuffer The loaded image data
654    */
655   void AsyncLocalLoadComplete( uint32_t id, Devel::PixelBuffer pixelBuffer );
656
657   /**
658    * @brief This signal handler is called when the async local loader finishes loading.
659    * @param[in] id        This is the async image loaders Id
660    * @param[in] pixelBuffer The loaded image data
661    */
662   void AsyncRemoteLoadComplete( uint32_t id, Devel::PixelBuffer pixelBuffer );
663
664   /**
665    * Common method to handle loading completion
666    * @param[in] container The Async loading container
667    * @param[in] id        This is the async image loaders Id
668    * @param[in] pixelBuffer The loaded image data
669    */
670   void AsyncLoadComplete( AsyncLoadingInfoContainerType& container, uint32_t id, Devel::PixelBuffer pixelBuffer );
671
672   /**
673    * @brief Performs Post-Load steps including atlasing.
674    * @param[in] textureInfo The struct associated with this Texture
675    * @param[in] pixelBuffer The image pixelBuffer
676    * @return    True if successful
677    */
678   void PostLoad( TextureManager::TextureInfo& textureInfo, Devel::PixelBuffer& pixelBuffer );
679
680   /**
681    * Check if there is a texture waiting to be masked. If there
682    * is then apply this mask and upload it.
683    * @param[in] maskTextureInfo The texture info of the mask that has just loaded.
684    */
685   void CheckForWaitingTexture( TextureInfo& maskTextureInfo );
686
687   /**
688    * Apply the mask to the pixelBuffer.
689    * @param[in] textureInfo The information of texture to apply the mask to
690    * @param[in] maskTextureId The texture id of the mask.
691    */
692   void ApplyMask( TextureInfo& textureInfo, TextureId maskTextureId );
693
694   /**
695    * Upload the texture specified in pixelBuffer to the appropriate location
696    * @param[in] pixelBuffer The image data to upload
697    * @param[in] textureInfo The texture info containing the location to
698    * store the data to.
699    */
700   void UploadTexture( Devel::PixelBuffer& pixelBuffer, TextureInfo& textureInfo );
701
702   /**
703    * Creates tiled geometry of for the texture which separates fully-opaque
704    * tiles from ones which use transparency.
705    * @param pixelBuffer
706    * @param textureInfo
707    */
708   bool CreateTiledGeometry( const Devel::PixelBuffer& pixelBuffer, TextureInfo& textureInfo );
709
710   /**
711    * Mark the texture as complete, and inform observers
712    * @param[in] textureInfo The struct associated with this Texture
713    */
714   void UploadComplete( TextureInfo& textureInfo );
715
716   /**
717    * Notify the current observers that the texture upload is complete,
718    * then remove the observers from the list.
719    * @param[in] textureInfo The struct associated with this Texture
720    * @param[in] success If the pixel data was retrieved successfully and uploaded to GPU
721    */
722   void NotifyObservers( TextureInfo& textureInfo, bool success );
723
724   /**
725    * @brief Generates a new, unique TextureId
726    * @return A unique TextureId
727    */
728   TextureManager::TextureId GenerateUniqueTextureId();
729
730   /**
731    * @brief Used to lookup an index into the TextureInfoContainer from a TextureId
732    * @param[in] textureId The TextureId to look up
733    * @return              The cache index
734    */
735   int GetCacheIndexFromId( TextureId textureId );
736
737
738   /**
739    * @brief Generates a hash for caching based on the input parameters.
740    * Only applies size, fitting mode andsampling mode if the size is specified.
741    * Only applies maskTextureId if it isn't INVALID_TEXTURE_ID
742    * Always applies useAtlas.
743    * @param[in] url              The URL of the image to load
744    * @param[in] size             The image size
745    * @param[in] fittingMode      The FittingMode to use
746    * @param[in] samplingMode     The SamplingMode to use
747    * @param[in] useAtlas         True if atlased
748    * @param[in] maskTextureId    The masking texture id (or INVALID_TEXTURE_ID)
749    * @param[in] isAnimatedImage  The boolean value to know whether the request is for animated image or not
750    * @param[in] frameIndex       The frame index of a frame to be loaded frame
751    * @return                     A hash of the provided data for caching.
752    */
753   TextureHash GenerateHash( const std::string& url, const ImageDimensions size,
754                             const FittingMode::Type fittingMode,
755                             const Dali::SamplingMode::Type samplingMode, const UseAtlas useAtlas,
756                             TextureId maskTextureId, StorageType storageType, bool isAnimatedImage, uint32_t frameIndex );
757
758   /**
759    * @brief Looks up a cached texture by its hash.
760    * If found, the given parameters are used to check there is no hash-collision.
761    * @param[in] hash              The hash to look up
762    * @param[in] url               The URL of the image to load
763    * @param[in] size              The image size
764    * @param[in] fittingMode       The FittingMode to use
765    * @param[in] samplingMode      The SamplingMode to use
766    * @param[in] useAtlas          True if atlased
767    * @param[in] maskTextureId     Optional texture ID to use to mask this image
768    * @param[in] preMultiplyOnLoad if the image's color should be multiplied by it's alpha. Set to OFF if there is no alpha.
769    * @param[in] storageType       Whether the pixel data is stored in the cache, returned with PixelBuffer or uploaded to the GPU
770    * @param[in] isAnimatedImage   The boolean value to know whether the request is for animated image or not
771    * @param[in] frameIndex        The frame index of a frame to be loaded frame
772    * @return                      A TextureId of a cached Texture if found. Or INVALID_TEXTURE_ID if not found.
773    */
774   TextureManager::TextureId FindCachedTexture(
775     const TextureManager::TextureHash hash,
776     const std::string& url,
777     const ImageDimensions size,
778     const FittingMode::Type fittingMode,
779     const Dali::SamplingMode::Type samplingMode,
780     const bool useAtlas,
781     TextureId maskTextureId,
782     MultiplyOnLoad preMultiplyOnLoad,
783     StorageType storageType,
784     bool isAnimatedImage,
785     uint32_t frameIndex );
786
787 private:
788
789   /**
790    * @brief Helper class to keep the relation between AsyncImageLoader and corresponding LoadingInfo container
791    */
792   class AsyncLoadingHelper : public ConnectionTracker
793   {
794   public:
795     /**
796      * @brief Create an AsyncLoadingHelper.
797      * @param[in] textureManager Reference to the texture manager
798      */
799     AsyncLoadingHelper(TextureManager& textureManager);
800
801     /**
802      * @brief Load a new frame of animated image
803      * @param[in] textureId             TextureId to reference the texture that will be loaded
804      * @param[in] animatedImageLoading  The AnimatedImageLoading to load animated image
805      * @param[in] frameIndex            The frame index of a frame to be loaded frame
806      */
807     void LoadAnimatedImage( TextureId textureId,
808                             Dali::AnimatedImageLoading animatedImageLoading,
809                             uint32_t frameIndex);
810
811     /**
812      * @brief Load a new texture.
813      * @param[in] textureId             TextureId to reference the texture that will be loaded
814      * @param[in] url                   The URL of the image to load
815      * @param[in] desiredSize           The size the image is likely to appear at.
816      *                                  This can be set to 0,0 for automatic
817      * @param[in] fittingMode           The FittingMode to use
818      * @param[in] samplingMode          The SamplingMode to use
819      * @param[in] orientationCorrection Whether to use image metadata to rotate or flip the image,
820      *                                  e.g., from portrait to landscape
821      * @param[in] preMultiplyOnLoad     if the image's color should be multiplied by it's alpha. Set to OFF if there is no alpha or if the image need to be applied alpha mask.
822      */
823     void Load(TextureId textureId,
824               const VisualUrl& url,
825               ImageDimensions desiredSize,
826               FittingMode::Type fittingMode,
827               SamplingMode::Type samplingMode,
828               bool orientationCorrection,
829               DevelAsyncImageLoader::PreMultiplyOnLoad preMultiplyOnLoad);
830
831     /**
832      * @brief Apply mask
833      * @param [in] id of the texture
834      * @param [in] pixelBuffer of the to be masked image
835      * @param [in] maskPixelBuffer of the mask image
836      * @param [in] contentScale The factor to scale the content
837      * @param [in] cropToMask Whether to crop the content to the mask size
838      * @param [in] preMultiplyOnLoad if the image's color should be multiplied by it's alpha. Set to OFF if there is no alpha.
839      */
840     void ApplyMask( TextureId textureId,
841                     Devel::PixelBuffer pixelBuffer,
842                     Devel::PixelBuffer maskPixelBuffer,
843                     float contentScale,
844                     bool cropToMask,
845                     DevelAsyncImageLoader::PreMultiplyOnLoad preMultiplyOnLoad );
846
847   public:
848     AsyncLoadingHelper(const AsyncLoadingHelper&) = delete;
849     AsyncLoadingHelper& operator=(const AsyncLoadingHelper&) = delete;
850
851     AsyncLoadingHelper(AsyncLoadingHelper&& rhs);
852     AsyncLoadingHelper& operator=(AsyncLoadingHelper&&rhs) = delete;
853
854   private:
855     /**
856      * @brief Main constructor that used by all other constructors
857      */
858     AsyncLoadingHelper( Toolkit::AsyncImageLoader loader,
859                         TextureManager& textureManager,
860                         AsyncLoadingInfoContainerType&& loadingInfoContainer );
861
862     /**
863      * @brief Callback to be called when texture loading is complete, it passes the pixel buffer on to texture manager.
864      * @param[in] id          Loader id
865      * @param[in] pixelBuffer Image data
866      */
867     void AsyncLoadComplete( uint32_t id, Devel::PixelBuffer pixelBuffer );
868
869   private:
870     Toolkit::AsyncImageLoader     mLoader;
871     TextureManager&               mTextureManager;
872     AsyncLoadingInfoContainerType mLoadingInfoContainer;
873   };
874
875   struct ExternalTextureInfo
876   {
877     TextureId textureId;
878     TextureSet textureSet;
879   };
880
881 private:
882
883   /**
884    * Deleted copy constructor.
885    */
886   TextureManager( const TextureManager& ) = delete;
887
888   /**
889    * Deleted assignment operator.
890    */
891   TextureManager& operator=( const TextureManager& rhs ) = delete;
892
893   /**
894    * This is called by the TextureManagerUploadObserver when an observer is destroyed.
895    * We use the callback to know when to remove an observer from our notify list.
896    * @param[in] observer The observer that generated the callback
897    */
898   void ObserverDestroyed( TextureUploadObserver* observer );
899
900 private:  // Member Variables:
901
902   TextureInfoContainerType                      mTextureInfoContainer; ///< Used to manage the life-cycle and caching of Textures
903   RoundRobinContainerView< AsyncLoadingHelper > mAsyncLocalLoaders;    ///< The Asynchronous image loaders used to provide all local async loads
904   RoundRobinContainerView< AsyncLoadingHelper > mAsyncRemoteLoaders;   ///< The Asynchronous image loaders used to provide all remote async loads
905   std::vector< ExternalTextureInfo >            mExternalTextures;     ///< Externally provided textures
906   Dali::Vector<LifecycleObserver*>              mLifecycleObservers;   ///< Lifecycle observers of texture manager
907   Dali::Vector<LoadQueueElement>                mLoadQueue;            ///< Queue of textures to load after NotifyObservers
908   std::string                                   mBrokenImageUrl;       ///< Broken image url
909   TextureId                                     mCurrentTextureId;     ///< The current value used for the unique Texture Id generation
910   bool                                          mQueueLoadFlag;        ///< Flag that causes Load Textures to be queued.
911 };
912
913
914 } // name Internal
915
916 } // namespace Toolkit
917
918 } // namespace Dali
919
920 #endif // DALI_TOOLKIT_TEXTURE_MANAGER_IMPL_H