[dali_2.0.15] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / visuals / image / image-visual.h
1 #ifndef DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
2 #define DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
3
4 /*
5  * Copyright (c) 2021 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 // EXTERNAL INCLUDES
22 #include <memory>
23
24 #include <dali/public-api/common/intrusive-ptr.h>
25 #include <dali/public-api/images/image-operations.h>
26 #include <dali/public-api/object/weak-handle.h>
27
28 // INTERNAL INCLUDES
29 #include <dali-toolkit/devel-api/image-loader/atlas-upload-observer.h>
30 #include <dali-toolkit/devel-api/visuals/image-visual-properties-devel.h>
31 #include <dali-toolkit/internal/visuals/texture-upload-observer.h>
32 #include <dali-toolkit/internal/visuals/visual-base-impl.h>
33 #include <dali-toolkit/internal/visuals/visual-url.h>
34 #include <dali-toolkit/public-api/visuals/image-visual-properties.h>
35
36 namespace Dali
37 {
38 class NativeImage;
39
40 namespace Toolkit
41 {
42 namespace Internal
43 {
44 class ImageVisualShaderFactory;
45 class ImageVisual;
46 typedef IntrusivePtr<ImageVisual> ImageVisualPtr;
47
48 /**
49  * The visual which renders an image to a quad geometry
50  *
51  * The following properties are optional
52  *
53  * | %Property Name        | Type              |
54  * |-----------------------|-------------------|
55  * | url                   | STRING            |
56  * | alphaMaskUrl          | STRING            |
57  * | fittingMode           | INTEGER OR STRING |
58  * | samplingMode          | INTEGER OR STRING |
59  * | desiredWidth          | INTEGER           |
60  * | desiredHeight         | INTEGER           |
61  * | synchronousLoading    | BOOLEAN           |
62  * | pixelArea             | VECTOR4           |
63  * | wrapModeU             | INTEGER OR STRING |
64  * | wrapModeV             | INTEGER OR STRING |
65  * | loadPolicy            | INTEGER OR STRING |
66  * | releasePolicy         | INTEGER OR STRING |
67  * | orientationCorrection | BOOLEAN           |
68  *
69  * where pixelArea is a rectangular area.
70  * In its Vector4 value, the first two elements indicate the top-left position of the area,
71  * and the last two elements are the area width and height respectively.
72  * If not specified, the default value is [0.0, 0.0, 1.0, 1.0], i.e. the entire area of the image.
73  *
74  * where wrapModeU and wrapModeV separately decide how the texture should be sampled when the u and v coordinate exceeds the range of 0.0 to 1.0.
75  * Its value should be one of the following wrap mode:
76  *   "DEFAULT"
77  *   "CLAMP_TO_EDGE"
78  *   "REPEAT"
79  *   "MIRRORED_REPEAT"
80  *
81  * where imageFittingMode should be one of the following fitting modes:
82  *   "SHRINK_TO_FIT"
83  *   "SCALE_TO_FILL"
84  *   "FIT_WIDTH"
85  *   "FIT_HEIGHT"
86  *   "DEFAULT"
87  *
88  * where imageSamplingMode should be one of the following sampling modes:
89  *   "BOX"
90  *   "NEAREST"
91  *   "LINEAR"
92  *   "BOX_THEN_NEAREST"
93  *   "BOX_THEN_LINEAR"
94  *   "NO_FILTER"
95  *   "DONT_CARE"
96  *   "DEFAULT"
97  *
98  * where loadPolicy should be one of the following image loading modes
99  *   "IMMEDIATE"   // Loads image even if visual not attached to stage yet
100  *   "ATTACHED"    // Only loads image once visual is attached to stage
101  *
102  * where releasePolicy should be one of the following policies for when to cache the image
103  *   "DETACHED"    //  Release image from cache when visual detached from stage
104  *   "DESTROYED"   //  Keep image in cache until the visual is destroyed
105  *   "NEVER"       //  Keep image in cache until application ends.
106  *
107  * If the Visual is in a LayerUI it will pixel align the image, using a Layer3D will disable pixel alignment.
108  * Changing layer behaviour between LayerUI to Layer3D whilst the visual is already staged will not have an effect.
109  */
110 class ImageVisual : public Visual::Base, public ConnectionTracker, public AtlasUploadObserver, public TextureUploadObserver
111 {
112 public:
113   /**
114    * @brief Create a new image visual with a URL.
115    *
116    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
117    *
118    * @param[in] factoryCache The VisualFactoryCache object
119    * @param[in] shaderFactory The ImageVisualShaderFactory object
120    * @param[in] imageUrl The URL of the image resource to use
121    * @param[in] properties A Property::Map containing settings for this visual
122    * @param[in] size The width and height to fit the loaded image to.
123    * @param[in] fittingMode The FittingMode of the resource to load
124    * @param[in] samplingMode The SamplingMode of the resource to load
125    * @return A smart-pointer to the newly allocated visual.
126    */
127   static ImageVisualPtr New(VisualFactoryCache&       factoryCache,
128                             ImageVisualShaderFactory& shaderFactory,
129                             const VisualUrl&          imageUrl,
130                             const Property::Map&      properties,
131                             ImageDimensions           size         = ImageDimensions(),
132                             FittingMode::Type         fittingMode  = FittingMode::DEFAULT,
133                             Dali::SamplingMode::Type  samplingMode = SamplingMode::BOX_THEN_LINEAR);
134
135   /**
136    * @brief Create a new image visual with a URL.
137    *
138    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
139    *
140    * @param[in] factoryCache The VisualFactoryCache object
141    * @param[in] shaderFactory The ImageVisualShaderFactory object
142    * @param[in] imageUrl The URL of the image resource to use
143    * @param[in] size The width and height to fit the loaded image to.
144    * @param[in] fittingMode The FittingMode of the resource to load
145    * @param[in] samplingMode The SamplingMode of the resource to load
146    * @return A smart-pointer to the newly allocated visual.
147    */
148   static ImageVisualPtr New(VisualFactoryCache&       factoryCache,
149                             ImageVisualShaderFactory& shaderFactory,
150                             const VisualUrl&          imageUrl,
151                             ImageDimensions           size         = ImageDimensions(),
152                             FittingMode::Type         fittingMode  = FittingMode::DEFAULT,
153                             Dali::SamplingMode::Type  samplingMode = SamplingMode::BOX_THEN_LINEAR);
154
155 public: // from Visual
156   /**
157    * @copydoc Visual::Base::GetNaturalSize
158    */
159   void GetNaturalSize(Vector2& naturalSize) override;
160
161   /**
162    * @copydoc Visual::Base::CreatePropertyMap
163    */
164   void DoCreatePropertyMap(Property::Map& map) const override;
165
166   /**
167    * @copydoc Visual::Base::CreateInstancePropertyMap
168    */
169   void DoCreateInstancePropertyMap(Property::Map& map) const override;
170
171   /**
172    * @copydoc Visual::Base::OnDoAction
173    */
174   void OnDoAction(const Dali::Property::Index actionName, const Dali::Property::Value& attributes) override;
175
176 protected:
177   /**
178    * @brief Constructor with a URL.
179    *
180    * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
181    *
182    * @param[in] factoryCache The VisualFactoryCache object
183    * @param[in] shaderFactory The ImageVisualShaderFactory object
184    * @param[in] imageUrl The URL of the image resource to use
185    * @param[in] size The width and height to fit the loaded image to.
186    * @param[in] fittingMode The FittingMode of the resource to load
187    * @param[in] samplingMode The SamplingMode of the resource to load
188    */
189   ImageVisual(VisualFactoryCache&       factoryCache,
190               ImageVisualShaderFactory& shaderFactory,
191               const VisualUrl&          imageUrl,
192               ImageDimensions           size,
193               FittingMode::Type         fittingMode,
194               Dali::SamplingMode::Type  samplingMode);
195
196   /**
197    * @brief A reference counted object may only be deleted by calling Unreference().
198    */
199   virtual ~ImageVisual();
200
201   /**
202    * @copydoc Visual::Base::OnInitialize
203    */
204   void OnInitialize() override;
205
206   /**
207    * @copydoc Visual::Base::DoSetProperties
208    */
209   void DoSetProperties(const Property::Map& propertyMap) override;
210
211   /**
212    * @copydoc Visual::Base::DoSetOnScene
213    */
214   void DoSetOnScene(Actor& actor) override;
215
216   /**
217    * @copydoc Visual::Base::DoSetOffScene
218    */
219   void DoSetOffScene(Actor& actor) override;
220
221   /**
222    * @copydoc Visual::Base::OnSetTransform
223    */
224   void OnSetTransform() override;
225
226   /**
227    * @copydoc Visual::Base::IsResourceReady
228    */
229   bool IsResourceReady() const override;
230
231   /**
232    * @copydoc Visual::Base::UpdateShader
233    */
234   void UpdateShader() override;
235
236 public:
237   /**
238    * @copydoc AtlasUploadObserver::UploadCompleted
239    *
240    * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
241    * This callback is the place to add the renderer as it would be called once the loading is finished.
242    */
243   void UploadCompleted() override;
244
245   /**
246    * @copydoc TextureUploadObserver::UploadCompleted
247    *
248    * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
249    * This callback is the place to add the renderer as it would be called once the loading is finished.
250    */
251   void UploadComplete(bool success, int32_t textureId, TextureSet textureSet, bool usingAtlas, const Vector4& atlasRectangle, bool preMultiplied) override;
252
253 private:
254   /**
255    * @copydoc TextureUploadObserver::LoadComplete
256    *
257    * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
258    * This callback is the place to add the renderer as it would be called once the PixelBuffer loading is finished.
259    */
260   void LoadComplete(bool loadSuccess, Devel::PixelBuffer pixelBuffer, const VisualUrl& url, bool preMultiplied) override
261   {
262   }
263
264   /**
265    * Allocate the mask data when a masking property is defined in the property map
266    */
267   void AllocateMaskData();
268
269   /**
270    * @brief Load the texture, will try to atlas unless unable or param set to false.
271    * @param[in, out] atlasing flag if the image has been put in a atlas (true), passing false will not atlas even if possible.
272    * @param[out] atlasRect if atlasing is used this the texture area of the image in the atlas.
273    * @param[out] textures resulting texture set from the image loading.
274    * @param[in] orientationCorrection flag determines if orientation correction should be performed
275    * @param[in] forceReload flag determines if the texture should be reloaded from its source or use the cached texture.
276    */
277   void LoadTexture(bool& atlasing, Vector4& atlasRect, TextureSet& textures, bool orientationCorrection, TextureManager::ReloadPolicy forceReload);
278
279   /**
280    * @brief Checks if atlasing should be attempted
281    * @return bool returns true if atlasing can be attempted.
282    */
283   bool AttemptAtlasing();
284
285   /**
286    * @brief Initializes the Dali::Renderer from the image url
287    */
288   void InitializeRenderer();
289
290   /**
291    * Creates the texture set and adds the texture to it
292    * @param[out] textureRect The texture area of the texture in the atlas.
293    * @param[in] url The URL of the image resource to use.
294    * @param[in] synchronousLoading If true, the resource is loaded synchronously, otherwise asynchronously.
295    * @param[in] attemptAtlasing If true will attempt atlasing, otherwise create unique texture
296    * @return the texture set to use
297    */
298   TextureSet CreateTextureSet(Vector4& textureRect, bool synchronousLoading, bool attemptAtlasing);
299
300   /**
301    * Set the value to the uTextureRect uniform
302    * @param[in] textureRect The texture rectangular area.
303    */
304   void SetTextureRectUniform(const Vector4& textureRect);
305
306   /**
307    * Remove texture with valid TextureId
308    */
309   void RemoveTexture();
310
311   /**
312    * Helper method to set individual values by index key.
313    * @param[in] index The index key of the value
314    * @param[in] value The value
315    */
316   void DoSetProperty(Property::Index index, const Property::Value& value);
317
318   /**
319    * @brief Get a shader for the current properties.
320    * @return The shader for the current properties.
321    */
322   Shader GetShader();
323
324 private:
325   Vector4                            mPixelArea;
326   WeakHandle<Actor>                  mPlacementActor;
327   VisualUrl                          mImageUrl;
328   TextureManager::MaskingDataPointer mMaskingData;
329
330   Dali::ImageDimensions     mDesiredSize;
331   TextureManager::TextureId mTextureId;
332   TextureSet                mTextures;
333
334   ImageVisualShaderFactory& mImageVisualShaderFactory;
335
336   Dali::FittingMode::Type                         mFittingMode : 3;
337   Dali::SamplingMode::Type                        mSamplingMode : 4;
338   Dali::WrapMode::Type                            mWrapModeU : 3;
339   Dali::WrapMode::Type                            mWrapModeV : 3;
340   Dali::Toolkit::ImageVisual::LoadPolicy::Type    mLoadPolicy;
341   Dali::Toolkit::ImageVisual::ReleasePolicy::Type mReleasePolicy;
342   Vector4                                         mAtlasRect;
343   Dali::ImageDimensions                           mAtlasRectSize;
344   TextureManager::LoadState                       mLoadState;             ///< The texture loading state
345   bool                                            mAttemptAtlasing;       ///< If true will attempt atlasing, otherwise create unique texture
346   bool                                            mOrientationCorrection; ///< true if the image will have it's orientation corrected.
347 };
348
349 } // namespace Internal
350
351 } // namespace Toolkit
352
353 } // namespace Dali
354
355 #endif /* DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H */