1 #ifndef DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
2 #define DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H
5 * Copyright (c) 2016 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/common/intrusive-ptr.h>
23 #include <dali/public-api/images/image.h>
24 #include <dali/public-api/images/image-operations.h>
25 #include <dali/public-api/images/resource-image.h>
26 #include <dali/devel-api/object/weak-handle.h>
29 #include <dali-toolkit/devel-api/image-loader/atlas-upload-observer.h>
30 #include <dali-toolkit/internal/visuals/texture-upload-observer.h>
31 #include <dali-toolkit/internal/visuals/visual-base-impl.h>
32 #include <dali-toolkit/internal/visuals/visual-url.h>
46 typedef IntrusivePtr< ImageVisual > ImageVisualPtr;
49 * The visual which renders an image to a quad geometry
51 * The following properties are optional
53 * | %Property Name | Type |
54 * |--------------------|-------------------|
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 |
66 * where pixelArea is a rectangular area.
67 * In its Vector4 value, the first two elements indicate the top-left position of the area,
68 * and the last two elements are the area width and height respectively.
69 * If not specified, the default value is [0.0, 0.0, 1.0, 1.0], i.e. the entire area of the image.
71 * 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.
72 * Its value should be one of the following wrap mode:
78 * where imageFittingMode should be one of the following fitting modes:
85 * where imageSamplingMode should be one of the following sampling modes:
96 * If the Visual is in a LayerUI it will pixel align the image, using a Layer3D will disable pixel alignment.
97 * Changing layer behaviour between LayerUI to Layer3D whilst the visual is already staged will not have an effect.
99 class ImageVisual: public Visual::Base, public ConnectionTracker, public AtlasUploadObserver, public TextureUploadObserver
104 * @brief Create a new image visual with a URL.
106 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
108 * @param[in] factoryCache The VisualFactoryCache object
109 * @param[in] imageUrl The URL of the image resource to use
110 * @param[in] properties A Property::Map containing settings for this visual
111 * @param[in] size The width and height to fit the loaded image to.
112 * @param[in] fittingMode The FittingMode of the resource to load
113 * @param[in] samplingMode The SamplingMode of the resource to load
114 * @return A smart-pointer to the newly allocated visual.
116 static ImageVisualPtr New( VisualFactoryCache& factoryCache,
117 const VisualUrl& imageUrl,
118 const Property::Map& properties,
119 ImageDimensions size = ImageDimensions(),
120 FittingMode::Type fittingMode = FittingMode::DEFAULT,
121 Dali::SamplingMode::Type samplingMode = SamplingMode::BOX_THEN_LINEAR );
124 * @brief Create a new image visual with a URL.
126 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
128 * @param[in] factoryCache The VisualFactoryCache object
129 * @param[in] imageUrl The URL of the image resource to use
130 * @param[in] size The width and height to fit the loaded image to.
131 * @param[in] fittingMode The FittingMode of the resource to load
132 * @param[in] samplingMode The SamplingMode of the resource to load
133 * @return A smart-pointer to the newly allocated visual.
135 static ImageVisualPtr New( VisualFactoryCache& factoryCache,
136 const VisualUrl& imageUrl,
137 ImageDimensions size = ImageDimensions(),
138 FittingMode::Type fittingMode = FittingMode::DEFAULT,
139 Dali::SamplingMode::Type samplingMode = SamplingMode::BOX_THEN_LINEAR );
142 * @brief Create a new image visual with an Image type.
144 * @param[in] factoryCache The VisualFactoryCache object
145 * @param[in] image The image to use
147 static ImageVisualPtr New( VisualFactoryCache& factoryCache, const Image& image );
149 public: // from Visual
152 * @copydoc Visual::Base::GetNaturalSize
154 virtual void GetNaturalSize( Vector2& naturalSize );
157 * @copydoc Visual::Base::CreatePropertyMap
159 virtual void DoCreatePropertyMap( Property::Map& map ) const;
162 * @copydoc Visual::Base::CreateInstancePropertyMap
164 virtual void DoCreateInstancePropertyMap( Property::Map& map ) const;
169 * @brief Constructor with a URL.
171 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
173 * @param[in] factoryCache The VisualFactoryCache object
174 * @param[in] imageUrl The URL of the image resource to use
175 * @param[in] size The width and height to fit the loaded image to.
176 * @param[in] fittingMode The FittingMode of the resource to load
177 * @param[in] samplingMode The SamplingMode of the resource to load
179 ImageVisual( VisualFactoryCache& factoryCache,
180 const VisualUrl& imageUrl,
181 ImageDimensions size,
182 FittingMode::Type fittingMode,
183 Dali::SamplingMode::Type samplingMode );
186 * @brief Constructor with an Image type.
188 * @param[in] factoryCache The VisualFactoryCache object
189 * @param[in] image The image to use
191 ImageVisual( VisualFactoryCache& factoryCache, const Image& image );
194 * @brief A reference counted object may only be deleted by calling Unreference().
196 virtual ~ImageVisual();
199 * @copydoc Visual::Base::DoSetProperties
201 virtual void DoSetProperties( const Property::Map& propertyMap );
204 * @copydoc Visual::Base::DoSetOnStage
206 virtual void DoSetOnStage( Actor& actor );
209 * @copydoc Visual::Base::DoSetOffStage
211 virtual void DoSetOffStage( Actor& actor );
214 * @copydoc Visual::Base::OnSetTransform
216 virtual void OnSetTransform();
221 * Get the standard image rendering shader.
222 * @param[in] factoryCache A pointer pointing to the VisualFactoryCache object
223 * @param[in] atlasing Whether texture atlasing is applied.
224 * @param[in] defaultTextureWrapping Whether the default texture wrap mode is applied.
226 static Shader GetImageShader( VisualFactoryCache& factoryCache, bool atlasing, bool defaultTextureWrapping );
229 * @copydoc AtlasUploadObserver::UploadCompleted
231 * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
232 * This callback is the place to add the renderer as it would be called once the loading is finished.
234 virtual void UploadCompleted();
237 * @copydoc TextureUploadObserver::UploadCompleted
239 * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
240 * This callback is the place to add the renderer as it would be called once the loading is finished.
242 virtual void UploadComplete( bool success, TextureSet textureSet, bool usingAtlas, const Vector4& atlasRectangle );
247 * @brief Applies the image to the texture set used for this renderer
249 * @param[in] image The Image to apply to the texture set used for this renderer
251 void ApplyImageToSampler( const Image& image );
254 * @brief Initializes the Dali::Renderer from the image url
256 void InitializeRenderer();
259 * @brief Initializes the Dali::Renderer from an image handle
261 * @param[in] image The image handle to intialize this ImageVisual from
263 void InitializeRenderer( const Image& image );
266 * @brief Creates the Dali::Renderer (potentially from the renderer cache), initializing it
267 * @param[in] textures to use
269 void CreateRenderer( TextureSet& textures );
272 * @brief Creates the Dali::Renderer for NativeImage with custom sampler type and prefix, initializing it
273 * @param NativeImageRenderer
275 void CreateNativeImageRenderer( NativeImage& nativeImage );
278 * @brief Query whether resources requires to be loaded synchronously.
279 * @return Returns true if synchronous resource loading is required, false otherwise.
281 bool IsSynchronousResourceLoading() const;
284 * @brief Load the resource synchronously
286 void LoadResourceSynchronously();
289 * Creates the texture set and adds the texture to it
290 * @param[out] textureRect The texture area of the texture in the atlas.
291 * @param[in] url The URL of the image resource to use.
292 * @param[in] synchronousLoading If true, the resource is loaded synchronously, otherwise asynchronously.
293 * @param[in] attemptAtlasing If true will attempt atlasing, otherwise create unique texture
294 * @return the texture set to use
296 TextureSet CreateTextureSet( Vector4& textureRect, bool synchronousLoading, bool attemptAtlasing );
299 * Set the value to the uTextureRect uniform
300 * @param[in] textureRect The texture rectangular area.
302 void SetTextureRectUniform( const Vector4& textureRect );
305 * Remove the texture if it is not used anymore.
307 void RemoveTexture(const std::string& url);
310 * Helper method to set individual values by index key.
311 * @param[in] index The index key of the value
312 * @param[in] value The value
314 void DoSetProperty( Property::Index index, const Property::Value& value );
321 WeakHandle<Actor> mPlacementActor;
323 VisualUrl mAlphaMaskUrl;
325 Dali::ImageDimensions mDesiredSize;
326 TextureManager::TextureId mTextureId;
327 TextureManager::TextureId mAlphaMaskId;
329 Dali::FittingMode::Type mFittingMode:3;
330 Dali::SamplingMode::Type mSamplingMode:4;
331 Dali::WrapMode::Type mWrapModeU:3;
332 Dali::WrapMode::Type mWrapModeV:3;
333 bool mAttemptAtlasing:1; ///< If true will attempt atlasing, otherwise create unique texture
334 bool mTextureLoading:1; ///< True if the texture is being loaded asynchronously, or false when it has loaded.
337 } // namespace Internal
339 } // namespace Toolkit
343 #endif /* DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H */