1 #ifndef __DALI_IMAGE_ACTOR_H__
2 #define __DALI_IMAGE_ACTOR_H__
5 * Copyright (c) 2015 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.
25 #include <dali/public-api/actors/renderable-actor.h>
26 #include <dali/public-api/math/rect.h>
27 #include <dali/public-api/images/image.h>
32 namespace Internal DALI_INTERNAL
38 * @brief An actor for displaying images.
40 * Allows the developer to add an actor to stage which displays the content of an Image object.
42 * By default CullFaceMode is set to CullNone to enable the ImageActor to be viewed from all angles.
44 * If an ImageActor is created without setting size, then the actor takes the size of the image -
45 * this is the natural size.
46 * Setting a size on the ImageActor, e.g through the SetSize api or through an animation will
47 * stop the natural size being used.
49 * If a pixel area is set on an ImageActor with natural size, the actor size will change
50 * to match the pixel area. If a pixel area is set on an ImageActor that has had it's size set,
51 * then the size doesn't change, and the partial image will be stretched to fill the set size.
53 * Clearing the pixel area on an Image actor with natural size will cause the actor to show the
54 * whole image again, and will change size back to that of the image.
56 * Clearing the pixel area on an Image actor with a set size will cause the actor to show the
57 * whole image again, but will not change the image size.
59 class DALI_IMPORT_API ImageActor : public RenderableActor
64 * @brief An enumeration of properties belonging to the ImageActor class.
65 * Properties additional to RenderableActor.
71 PIXEL_AREA = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "pixel-area", type Rect<int>
72 STYLE, ///< name "style", type std::string
73 BORDER, ///< name "border", type Vector4
74 IMAGE, ///< name "image", type Map {"filename":"", "load-policy":...}
79 * @brief Style determines how the Image is rendered.
84 * 0---------2 0-----------------2
88 * | / | SCALE (X) | / |
89 * | / | --------> | / |
94 * 1---------3 1-----------------3
96 * Image is rendered as a textured rectangle. The texture
97 * is scaled uniformly as the quad is resized.
101 * |---|---------------|---| |---|-----------------------------|---|
102 * | 1 | 2 | 3 | | 1 | 2 | 3 |
103 * |---|---------------|---| |---|-----------------------------|---|
106 * | 4 | 5 | 6 | SCALE | | | |
107 * | | | | ----> | | | |
108 * | | | | | 4 | 5 | 6 |
109 * |-------------------|---| | | | |
110 * | 7 | 8 | 9 | | | | |
111 * |---|---------------|---| | | | |
112 * |---------------------------------|---|
114 * |---|-----------------------------|---|
116 * Image is rendered as a textured rectangle. The texture
117 * is scaled differently over each of the 9 sections.
119 * STYLE_NINE_PATCH_NO_CENTER:
121 * Image is rendered in the same way as STYLE_NINE_PATCH,
122 * but the Center Section (5) is not rendered.
125 * Visualise a Picture Frame:
127 * - Corner sections (1,3,7,9) are not scaled, regardless
128 * of how big the Image is.
129 * - Horizontal edge sections (2,8) are scaled only in the
130 * X axis as the image increases in width.
131 * - Vertical edge sections (4,6) are scaled only in the
132 * Y axis as the image increases in height.
133 * - Center section (5) is scaled in both X and Y axes as
134 * the image increases in width and/or height.
136 * Note: If GRID hints are enabled (via a Shader that requires it),
137 * the above geometry will be further subdivided into rectangles of
138 * approx. 40x40 in size. STYLE_NINE_PATCH_NO_CENTER is not supported
139 * yet when GRID hints are enabled.
143 STYLE_QUAD, ///< As a simple quad.
144 STYLE_NINE_PATCH, ///< As a nine-patch.
145 STYLE_NINE_PATCH_NO_CENTER ///< As a nine-patch without center section being rendered.
149 * @brief Pixel area is relative to the top-left (0,0) of the image.
151 typedef Rect<int> PixelArea;
154 * @brief Create an uninitialized ImageActor handle.
156 * This can be initialized with ImageActor::New(...)
157 * Calling member functions with an uninitialized Dali::Object is not allowed.
162 * @brief Create an empty image actor object.
164 * @return A handle to a newly allocated actor.
166 static ImageActor New();
169 * @brief Create a image actor object.
171 * The actor will take the image's natural size unless a custom size
172 * is chosen, e.g. via Actor:SetSize().
173 * If the handle is empty, ImageActor will display nothing
174 * @pre ImageActor must be initialized.
175 * @param[in] image The image to display.
176 * @return A handle to a newly allocated actor.
178 static ImageActor New(Image image);
181 * @brief Create a image actor object.
183 * The actor will take the image's natural size unless a custom size
184 * is chosen, e.g. via Actor:SetSize()
185 * If the handle is empty, ImageActor will display nothing
186 * @pre ImageActor must be initialized.
187 * @param [in] image The image to display.
188 * @param [in] pixelArea The area of the image to display.
189 * This in pixels, relative to the top-left (0,0) of the image.
190 * @return A handle to a newly allocated actor.
192 static ImageActor New(Image image, PixelArea pixelArea);
195 * @brief Downcast an Object handle to ImageActor.
198 * If handle points to a ImageActor the downcast produces valid
199 * handle. If not the returned handle is left uninitialized.
201 * @param[in] handle to An object
202 * @return handle to a ImageActor or an uninitialized handle
204 static ImageActor DownCast( BaseHandle handle );
209 * This is non-virtual since derived Handle types must not contain data or virtual methods.
214 * @brief Copy constructor
216 * @param [in] copy The actor to copy.
218 ImageActor(const ImageActor& copy);
221 * @brief Assignment operator
223 * @param [in] rhs The actor to copy.
225 ImageActor& operator=(const ImageActor& rhs);
228 * @brief Set the image rendered by the actor.
229 * Set the image rendered by the actor.
230 * If actor was already displaying a different image, the old image is dropped and actor may
231 * temporarily display nothing. Setting an empty image (handle) causes the current image to be
232 * dropped and actor displays nothing.
233 * The actor will take the image's natural size unless a custom size
234 * is chosen, e.g. via Actor:SetSize()
236 * @pre ImageActor must be initialized.
237 * @param [in] image The image to display.
239 void SetImage(Image image);
242 * @brief Retrieve the image rendered by the actor.
244 * If no image is assigned, an empty handle is returned
250 * @brief Set a region of the image to display, in pixels.
252 * When the image is loaded the actor's size will be reset to the pixelArea,
253 * unless a custom size was chosen, e.g. via Actor:SetSize().
254 * Note! PixelArea should be inside the image data size. It gets clamped by GL
255 * @pre image must be initialized.
256 * @param [in] pixelArea The area of the image to display.
257 * This in pixels, relative to the top-left (0,0) of the image.
259 void SetPixelArea(const PixelArea& pixelArea);
262 * @brief Retrieve the region of the image to display, in pixels.
264 * @pre image must be initialized.
265 * @return The pixel area, or a default-constructed area if none was set.
267 PixelArea GetPixelArea() const;
270 * @brief Set how the image is rendered; the default is STYLE_QUAD.
272 * @pre image must be initialized.
273 * @param [in] style The new style.
275 void SetStyle(Style style);
278 * @brief Query how the image is rendered.
280 * @pre image must be initialized.
281 * @return The rendering style.
283 Style GetStyle() const;
286 * @brief Set the border used with STYLE_NINE_PATCH.
288 * The values are in pixels from the left, top, right, and bottom of the image respectively.
289 * i.e. SetNinePatchBorder( Vector4(1,2,3,4) ) sets the left-border to 1, top-border to 2, right-border to 3, and bottom-border to 4 pixels.
290 * @param [in] border The new nine-patch border.
292 void SetNinePatchBorder(const Vector4& border);
295 * @brief Retrieve the border used with STYLE_NINE_PATCH.
297 * @return The nine-patch border.
299 Vector4 GetNinePatchBorder() const;
303 * @brief Allows modification of an actors position in the depth sort algorithm.
305 * The offset can be altered for each coplanar actor hence allowing an order of painting.
306 * @pre The Actor has been initialized.
307 * @param [in] depthOffset the offset to be given to the actor. Positive values pushing it further back.
309 void SetSortModifier(float depthOffset);
312 * @brief Retrieves the offset used to modify an actors position in the depth sort algorithm.
314 * The offset can be altered for each coplanar actor hence allowing an order of painting.
315 * @pre The Actor has been initialized.
316 * @return the offset that has been given to the actor. Positive values pushing it further back.
318 float GetSortModifier() const;
321 * @brief Set the face-culling mode for this actor.
323 * @param[in] mode The culling mode.
325 void SetCullFace(CullFaceMode mode);
328 * @brief Retrieve the face-culling mode for this actor.
330 * @return mode The culling mode.
332 CullFaceMode GetCullFace() const;
335 * @brief Sets the blending mode.
337 * Possible values are: BlendingMode::OFF, BlendingMode::AUTO and BlendingMode::ON. Default is BlendingMode::AUTO.
339 * If blending is disabled (BlendingMode::OFF) fade in and fade out animations do not work.
342 * <li> \e OFF Blending is disabled.
343 * <li> \e AUTO Blending is enabled only if the renderable actor has alpha channel.
344 * <li> \e ON Blending is enabled.
347 * @param[in] mode The blending mode.
349 void SetBlendMode( BlendingMode::Type mode );
352 * @brief Retrieves the blending mode.
354 * @return The blending mode, one of BlendingMode::OFF, BlendingMode::AUTO or BlendingMode::ON.
356 BlendingMode::Type GetBlendMode() const;
359 * @brief Specify the pixel arithmetic used when the actor is blended.
361 * @param[in] srcFactorRgba Specifies how the red, green, blue, and alpha source blending factors are computed.
362 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
363 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
364 * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
366 * @param[in] destFactorRgba Specifies how the red, green, blue, and alpha destination blending factors are computed.
367 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
368 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
369 * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
371 void SetBlendFunc( BlendingFactor::Type srcFactorRgba, BlendingFactor::Type destFactorRgba );
374 * @brief Specify the pixel arithmetic used when the actor is blended.
376 * @param[in] srcFactorRgb Specifies how the red, green, and blue source blending factors are computed.
377 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
378 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
379 * GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA, and GL_SRC_ALPHA_SATURATE.
381 * @param[in] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
382 * The options are BlendingFactor::ZERO, ONE, SRC_COLOR, ONE_MINUS_SRC_COLOR, DST_COLOR, ONE_MINUS_DST_COLOR,
383 * SRC_ALPHA, ONE_MINUS_SRC_ALPHA, DST_ALPHA, ONE_MINUS_DST_ALPHA, CONSTANT_COLOR, ONE_MINUS_CONSTANT_COLOR,
384 * GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA.
386 * @param[in] srcFactorAlpha Specifies how the alpha source blending factor is computed.
387 * The options are the same as for srcFactorRgb.
389 * @param[in] destFactorAlpha Specifies how the alpha source blending factor is computed.
390 * The options are the same as for destFactorRgb.
392 void SetBlendFunc( BlendingFactor::Type srcFactorRgb, BlendingFactor::Type destFactorRgb,
393 BlendingFactor::Type srcFactorAlpha, BlendingFactor::Type destFactorAlpha );
396 * @brief Query the pixel arithmetic used when the actor is blended.
398 * @param[out] srcFactorRgb Specifies how the red, green, blue, and alpha source blending factors are computed.
399 * @param[out] destFactorRgb Specifies how the red, green, blue, and alpha destination blending factors are computed.
400 * @param[out] srcFactorAlpha Specifies how the red, green, blue, and alpha source blending factors are computed.
401 * @param[out] destFactorAlpha Specifies how the red, green, blue, and alpha destination blending factors are computed.
403 void GetBlendFunc( BlendingFactor::Type& srcFactorRgb, BlendingFactor::Type& destFactorRgb,
404 BlendingFactor::Type& srcFactorAlpha, BlendingFactor::Type& destFactorAlpha ) const;
407 * @brief Specify the equation used when the actor is blended.
409 * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
410 * @param[in] equationRgba The equation used for combining red, green, blue, and alpha components.
412 void SetBlendEquation( BlendingEquation::Type equationRgba );
415 * @brief Specify the equation used when the actor is blended.
417 * @param[in] equationRgb The equation used for combining red, green, and blue components.
418 * @param[in] equationAlpha The equation used for combining the alpha component.
419 * The options are BlendingEquation::ADD, SUBTRACT, or REVERSE_SUBTRACT.
421 void SetBlendEquation( BlendingEquation::Type equationRgb, BlendingEquation::Type equationAlpha );
424 * @brief Query the equation used when the actor is blended.
426 * @param[out] equationRgb The equation used for combining red, green, and blue components.
427 * @param[out] equationAlpha The equation used for combining the alpha component.
429 void GetBlendEquation( BlendingEquation::Type& equationRgb, BlendingEquation::Type& equationAlpha ) const;
432 * @brief Specify the color used when the actor is blended; the default is Vector4::ZERO.
434 * @param[in] color The blend color.
436 void SetBlendColor( const Vector4& color );
439 * @brief Query the color used when the actor is blended.
441 * @return The blend color.
443 const Vector4& GetBlendColor() const;
446 * @brief Sets the filtering mode.
448 * Possible values are: FilterMode::NEAREST and FilterMode::LINEAR. Default is FilterMode::LINEAR.
451 * <li> \e NEAREST Use nearest filtering
452 * <li> \e LINEAR Use linear filtering
455 * @param[in] minFilter The minification filtering mode.
456 * @param[in] magFilter The magnification filtering mode.
458 void SetFilterMode( FilterMode::Type minFilter, FilterMode::Type magFilter );
461 * @brief Retrieves the filtering mode.
463 * @param[out] minFilter The return minification value
464 * @param[out] magFilter The return magnification value
466 void GetFilterMode( FilterMode::Type& minFilter, FilterMode::Type& magFilter) const;
469 * @brief Sets the shader effect for the RenderableActor.
471 * Shader effects provide special effects like ripple and bend.
472 * Setting a shader effect removes any shader effect previously set by SetShaderEffect.
473 * @pre The actor has been initialized.
474 * @pre effect has been initialized.
475 * @param [in] effect The shader effect.
477 void SetShaderEffect( ShaderEffect effect );
480 * @brief Retrieve the custom shader effect for the RenderableActor.
481 * If default shader is used an empty handle is returned.
483 * @pre The Actor has been initialized.
484 * @return The shader effect
486 ShaderEffect GetShaderEffect() const;
489 * @brief Removes the current shader effect.
491 * @pre The Actor has been initialized.
493 void RemoveShaderEffect();
496 public: // Not intended for application developers
498 explicit DALI_INTERNAL ImageActor(Internal::ImageActor*);
503 * @brief Sets the shader effect for all ImageActors in a tree of Actors.
505 * @see ImageActor::SetShaderEffect
507 * @param [in] actor root of a tree of actors.
508 * @param [in] effect The shader effect.
510 DALI_IMPORT_API void SetShaderEffectRecursively( Actor actor, ShaderEffect effect );
513 * @brief Removes the shader effect from all ImageActors in a tree of Actors.
515 * @see ImageActor::RemoveShaderEffect
517 * @param [in] actor root of a tree of actors.
519 DALI_IMPORT_API void RemoveShaderEffectRecursively( Actor actor );
523 #endif // __DALI_IMAGE_ACTOR_H__