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 the control's quad
51 * The following properties are optional
53 * | %Property Name | Type |
54 * |--------------------|-------------------|
56 * | fittingMode | INTEGER OR STRING |
57 * | samplingMode | INTEGER OR STRING |
58 * | desiredWidth | INTEGER |
59 * | desiredHeight | INTEGER |
60 * | synchronousLoading | BOOLEAN |
61 * | pixelArea | VECTOR4 |
62 * | wrapModeU | INTEGER OR STRING |
63 * | wrapModeV | INTEGER OR STRING |
65 * where pixelArea is a rectangular area.
66 * In its Vector4 value, the first two elements indicate the top-left position of the area,
67 * and the last two elements are the area width and height respectively.
68 * If not specified, the default value is [0.0, 0.0, 1.0, 1.0], i.e. the entire area of the image.
70 * 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.
71 * Its value should be one of the following wrap mode:
77 * where imageFittingMode should be one of the following fitting modes:
84 * where imageSamplingMode should be one of the following sampling modes:
95 * If the Visual is in a LayerUI it will pixel align the image, using a Layer3D will disable pixel alignment.
96 * Changing layer behaviour between LayerUI to Layer3D whilst the visual is already staged will not have an effect.
98 class ImageVisual: public Visual::Base, public ConnectionTracker, public AtlasUploadObserver, public TextureUploadObserver
103 * @brief Create a new image visual with a URL.
105 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
107 * @param[in] factoryCache The VisualFactoryCache object
108 * @param[in] imageUrl The URL of the image resource to use
109 * @param[in] properties A Property::Map containing settings for this visual
110 * @param[in] size The width and height to fit the loaded image to.
111 * @param[in] fittingMode The FittingMode of the resource to load
112 * @param[in] samplingMode The SamplingMode of the resource to load
113 * @return A smart-pointer to the newly allocated visual.
115 static ImageVisualPtr New( VisualFactoryCache& factoryCache,
116 const VisualUrl& imageUrl,
117 const Property::Map& properties,
118 ImageDimensions size = ImageDimensions(),
119 FittingMode::Type fittingMode = FittingMode::DEFAULT,
120 Dali::SamplingMode::Type samplingMode = SamplingMode::BOX_THEN_LINEAR );
123 * @brief Create a new image visual with a URL.
125 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
127 * @param[in] factoryCache The VisualFactoryCache object
128 * @param[in] imageUrl The URL of the image resource to use
129 * @param[in] size The width and height to fit the loaded image to.
130 * @param[in] fittingMode The FittingMode of the resource to load
131 * @param[in] samplingMode The SamplingMode of the resource to load
132 * @return A smart-pointer to the newly allocated visual.
134 static ImageVisualPtr New( VisualFactoryCache& factoryCache,
135 const VisualUrl& imageUrl,
136 ImageDimensions size = ImageDimensions(),
137 FittingMode::Type fittingMode = FittingMode::DEFAULT,
138 Dali::SamplingMode::Type samplingMode = SamplingMode::BOX_THEN_LINEAR );
141 * @brief Create a new image visual with an Image type.
143 * @param[in] factoryCache The VisualFactoryCache object
144 * @param[in] image The image to use
146 static ImageVisualPtr New( VisualFactoryCache& factoryCache, const Image& image );
148 public: // from Visual
151 * @copydoc Visual::Base::GetNaturalSize
153 virtual void GetNaturalSize( Vector2& naturalSize );
156 * @copydoc Visual::Base::CreatePropertyMap
158 virtual void DoCreatePropertyMap( Property::Map& map ) const;
161 * @copydoc Visual::Base::CreateInstancePropertyMap
163 virtual void DoCreateInstancePropertyMap( Property::Map& map ) const;
168 * @brief Constructor with a URL.
170 * The visual will load the Image asynchronously when the associated actor is put on stage, and destroy the image when it is off stage
172 * @param[in] factoryCache The VisualFactoryCache object
173 * @param[in] imageUrl The URL of the image resource to use
174 * @param[in] size The width and height to fit the loaded image to.
175 * @param[in] fittingMode The FittingMode of the resource to load
176 * @param[in] samplingMode The SamplingMode of the resource to load
178 ImageVisual( VisualFactoryCache& factoryCache,
179 const VisualUrl& imageUrl,
180 ImageDimensions size,
181 FittingMode::Type fittingMode,
182 Dali::SamplingMode::Type samplingMode );
185 * @brief Constructor with an Image type.
187 * @param[in] factoryCache The VisualFactoryCache object
188 * @param[in] image The image to use
190 ImageVisual( VisualFactoryCache& factoryCache, const Image& image );
193 * @brief A reference counted object may only be deleted by calling Unreference().
195 virtual ~ImageVisual();
198 * @copydoc Visual::Base::DoSetProperties
200 virtual void DoSetProperties( const Property::Map& propertyMap );
203 * @copydoc Visual::Base::DoSetOnStage
205 virtual void DoSetOnStage( Actor& actor );
208 * @copydoc Visual::Base::DoSetOffStage
210 virtual void DoSetOffStage( Actor& actor );
213 * @copydoc Visual::Base::OnSetTransform
215 virtual void OnSetTransform();
220 * Get the standard image rendering shader.
221 * @param[in] factoryCache A pointer pointing to the VisualFactoryCache object
222 * @param[in] atlasing Whether texture atlasing is applied.
223 * @param[in] defaultTextureWrapping Whether the default texture wrap mode is applied.
225 static Shader GetImageShader( VisualFactoryCache& factoryCache, bool atlasing, bool defaultTextureWrapping );
228 * @copydoc AtlasUploadObserver::UploadCompleted
230 * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
231 * This callback is the place to add the renderer as it would be called once the loading is finished.
233 virtual void UploadCompleted();
236 * @copydoc TextureUploadObserver::UploadCompleted
238 * To avoid rendering garbage pixels, renderer should be added to actor after the resources are ready.
239 * This callback is the place to add the renderer as it would be called once the loading is finished.
241 virtual void UploadComplete( bool success, TextureSet textureSet, bool usingAtlas, const Vector4& atlasRectangle );
246 * @brief Applies the image to the texture set used for this renderer
248 * @param[in] image The Image to apply to the texture set used for this renderer
250 void ApplyImageToSampler( const Image& image );
253 * @brief Initializes the Dali::Renderer from the image url
255 void InitializeRenderer();
258 * @brief Initializes the Dali::Renderer from an image handle
260 * @param[in] image The image handle to intialize this ImageVisual from
262 void InitializeRenderer( const Image& image );
265 * @brief Creates the Dali::Renderer (potentially from the renderer cache), initializing it
266 * @param[in] textures to use
268 void CreateRenderer( TextureSet& textures );
271 * @brief Creates the Dali::Renderer for NativeImage with custom sampler type and prefix, initializing it
272 * @param NativeImageRenderer
274 void CreateNativeImageRenderer( NativeImage& nativeImage );
277 * @brief Query whether resources requires to be loaded synchronously.
278 * @return Returns true if synchronous resource loading is required, false otherwise.
280 bool IsSynchronousResourceLoading() const;
283 * @brief Load the resource synchronously
285 void LoadResourceSynchronously();
288 * Creates the texture set and adds the texture to it
289 * @param[out] textureRect The texture area of the texture in the atlas.
290 * @param[in] url The URL of the image resource to use.
291 * @param[in] synchronousLoading If true, the resource is loaded synchronously, otherwise asynchronously.
292 * @param[in] attemptAtlasing If true will attempt atlasing, otherwise create unique texture
293 * @return the texture set to use
295 TextureSet CreateTextureSet( Vector4& textureRect, bool synchronousLoading, bool attemptAtlasing );
298 * Set the value to the uTextureRect uniform
299 * @param[in] textureRect The texture rectangular area.
301 void SetTextureRectUniform( const Vector4& textureRect );
304 * Remove the texture if it is not used anymore.
306 void RemoveTexture(const std::string& url);
309 * Helper method to set individual values by index key.
310 * @param[in] index The index key of the value
311 * @param[in] value The value
313 void DoSetProperty( Property::Index index, const Property::Value& value );
320 WeakHandle<Actor> mPlacementActor;
323 Dali::ImageDimensions mDesiredSize;
324 TextureManager::TextureId mTextureId;
326 Dali::FittingMode::Type mFittingMode:3;
327 Dali::SamplingMode::Type mSamplingMode:4;
328 Dali::WrapMode::Type mWrapModeU:3;
329 Dali::WrapMode::Type mWrapModeV:3;
330 bool mAttemptAtlasing:1; ///< If true will attempt atlasing, otherwise create unique texture
331 bool mTextureLoading:1; ///< True if the texture is being loaded asynchronously, or false when it has loaded.
334 } // namespace Internal
336 } // namespace Toolkit
340 #endif /* DALI_TOOLKIT_INTERNAL_IMAGE_VISUAL_H */