# Visuals {#visuals} Visuals provide reusable rendering logic which can be used by all controls. This means that custom controls do not have to create actors, they can just reuse the existing visuals which increases performance. Visuals reuse geometry, shaders etc. across controls and manages the renderer and texture to exist only when the control is on-stage. Additionally, they respond to actor size and color change, while also providing clipping at the renderer level. DALi provides the following visuals: + [Color](@ref color-visual) + [Gradient](@ref gradient-visual) + [Image](@ref image-visuals) + [Border](@ref border-visual) + [Mesh](@ref mesh-visual) + [Primitive](@ref primitive-visual) + [Text](@ref text-visual) + [Wireframe](@ref wireframe-visual) Controls can provide properties that allow users to specify the visual type ( visualType ). Setting visual properties are done via a property map. The **visualType** field in the property map specifies the visual to use/create. This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents. Visuals have a **transform** field in the property map to allow layouting within a control. If this field is not set, then the visual defaults to filling the control. The **transform** field has a property map with the following keys: | Property | String | Type | Required | Description | |----------------------------------------------------------------|--------------|:-----------------:|:--------:|---------------------------------------------------------------------------------------------| | Dali::Toolkit::Visual::Transform::Property::OFFSET | offset | VECTOR2 | No | The offset of the visual. | | Dali::Toolkit::Visual::Transform::Property::SIZE | size | VECTOR2 | No | The size of the visual. | | Dali::Toolkit::Visual::Transform::Property::OFFSET_POLICY | offsetPolicy | VECTOR4 | No | Whether the offset components are Relative or Absolute [More info](@ref offset-size-policy) | | Dali::Toolkit::Visual::Transform::Property::SIZE_POLICY | sizePolicy | VECTOR4 | No | Whether the size components are Relative or Absolute [More info](@ref offset-size-policy) | | Dali::Toolkit::Visual::Transform::Property::ORIGIN | origin | INTEGER or STRING | No | The origin of the visual within the control's area. [More info](@ref align-type) | | Dali::Toolkit::Visual::Transform::Property::ANCHOR_POINT | anchorPoint | INTEGER or STRING | No | The anchor point of the visual. [More info](@ref align-type) | ## Offset & Size Policy {#offset-size-policy} The offset and size policies can be either Relative or Absolute. | Enumeration | String | Description | |---------------------------------------------------------|----------|-------------------------------------------------------------------------------| | Dali::Toolkit::Visual::Transform::Policy::RELATIVE | RELATIVE | *Default*. The size or offset value represents a ratio of the control's size | | Dali::Toolkit::Visual::Transform::Policy::ABSOLUTE | ABSOLUTE | The size or offset value represents world units (pixels) | For example, an offsetPolicy of [ RELATIVE, RELATIVE ], a sizePolicy of [ ABSOLUTE, ABSOLUTE ], an offset of ( 0, 0.25 ) and a size of ( 20, 20 ) means the visual will be 20 pixels by 20 pixels in size, positioned 25% above the center of the control. ## Alignment {#align-type} | Enumeration | String | Description | |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------| | Dali::Toolkit::Align::TOP_BEGIN | TOP_BEGIN | Aligns to the top of the vertical axis and the beginning of the horizontal axis (The left or right edge in Left-To-Right or Right-to-Left layouts, respectively) | | Dali::Toolkit::Align::TOP_CENTER | TOP_CENTER | Aligns to the top of the vertical axis and the center of the horizontal axis | | Dali::Toolkit::Align::TOP_END | TOP_END | Aligns to the top of the vertical axis and end of the horizontal axis (The right or left edge in Left-To-Right or Right-to-Left layouts, respectively) | | Dali::Toolkit::Align::CENTER_BEGIN | CENTER_BEGIN | Aligns to the center of the vertical axis and the beginning of the horizontal axis| | Dali::Toolkit::Align::CENTER | CENTER | Aligns to the center of the control | | Dali::Toolkit::Align::CENTER_END | CENTER_END | Aligns to the center of the vertical axis and end of the horizontal axis | | Dali::Toolkit::Align::BOTTOM_BEGIN | BOTTOM_BEGIN | Aligns to the bottom of the vertical axis and the beginning of the horizontal axis| | Dali::Toolkit::Align::BOTTOM_CENTER | BOTTOM_CENTER | Aligns to the bottom of the vertical axis and the center of the horizontal axis | Dali::Toolkit::Align::BOTTOM_END | BOTTOM_END | Aligns to the bottom of the vertical axis and end of the horizontal axis | Visuals also have a custom **shader** property. Whilst it's possible to change the shader, please note that some visuals rely on the vertex shader to perform certain functions. For example, the NPatch visual uses the vertex shader to perform the stretching. The **shader** property is a Property::Map with the following keys: | Property | String | Type | Required | Description | |-----------------------------------------------------------|----------------|:--------------------------:|:--------:|--------------------------------------------------------------------------------------------| | Dali::Toolkit::Visual::Shader::Property::VERTEX_SHADER | vertexShader | STRING or ARRAY of STRING | No | The vertex shader code. Can use an array of strings to split shader over multiple lines. | | Dali::Toolkit::Visual::Shader::Property::FRAGMENT_SHADER | fragmentShader | STRING or ARRAY of STRING | No | The fragment shader code. Can use an array of strings to split shader over multiple lines. | | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_X | subdivideGridX | INTEGER | No | How to subdivide the grid along the X-Axis. Defaults to 1. | | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_Y | subdivideGridY | INTEGER | No | How to subdivide the grid along the Y-Axis. Defaults to 1. | | Dali::Toolkit::Visual::Shader::Property::HINTS | hints | INTEGER or ARRAY of STRING | No | Shader hints bitmask [More info](@ref shader-hints) | ## Shader hints {#shader-hints} This is a bitmask giving hints to the renderer about what the shader does, in order to help the rendering system optimise it's rendering. The bitmask can have the following values: | Value | Description | |-------------------------------------------|----------------------------------------| | Dali::Shader::Hint::NONE | No hints | | Dali::Shader::Hint::OUTPUT_IS_TRANSPARENT | Might generate transparent alpha from opaque inputs | | Dali::Shader::Hint::MODIFIES_GEOMETRY | Might change the position of vertices - this disables culling optimizations | See also Dali::Shader::Hint::Value enumeration. ___________________________________________________________________________________________________ ## Color Visual {#color-visual} Renders a color to the visual's quad geometry. ![ ](visuals/color-visual.png) ### Properties Supported **VisualType:** Dali::Toolkit::Visual::COLOR, "COLOR" | Property | String | Type | Required | Description | |-------------------------------------------------|----------|:-------:|:--------:|---------------------------| | Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes | The color required. | ### Usage ~~~{.cpp} // C++ Dali::Toolkit::Control control = Dali::Toolkit::Control::New(); Dali::Property::Map map; map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::COLOR; map[ ColorVisual::Property::MIX_COLOR ] = Color::RED; control.SetProperty( Control::Property::BACKGROUND, map ); ~~~ ___________________________________________________________________________________________________ ## Gradient Visual {#gradient-visual} Renders a smooth transition of colors to the visual's quad geometry. Both Linear and Radial gradients are supported. | Linear | Radial | |--------|--------| | ![ ](visuals/linear-gradient-visual.png) | ![ ](visuals/radial-gradient-visual.png) | ### Properties Supported **VisualType:** Dali::Toolkit::Visual::GRADIENT, "GRADIENT" | Property | String | Type | Required | Description | |---------------------------------------------------------|---------------|:-----------------:|:----------:|------------------------------------------------------------------------------------------------------------------| | Dali::Toolkit::GradientVisual::Property::START_POSITION | startPosition | VECTOR2 | For Linear | The start position of the linear gradient. | | Dali::Toolkit::GradientVisual::Property::END_POSITION | endPosition | VECTOR2 | For Linear | The end position of the linear gradient. | | Dali::Toolkit::GradientVisual::Property::CENTER | center | VECTOR2 | For Radial | The center point of the gradient. | | Dali::Toolkit::GradientVisual::Property::RADIUS | radius | FLOAT | For Radial | The size of the radius. | | Dali::Toolkit::GradientVisual::Property::STOP_OFFSET | stopOffset | ARRAY of FLOAT | No | All the stop offsets. If not supplied default is 0.0 and 1.0. | | Dali::Toolkit::GradientVisual::Property::STOP_COLOR | stopColor | ARRAY of VECTOR4 | Yes | The color at those stop offsets. At least 2 required to show a gradient. | | Dali::Toolkit::GradientVisual::Property::UNITS | units | INTEGER or STRING | No | Defines the coordinate system. [More info](@ref gradient-visual-units) | | Dali::Toolkit::GradientVisual::Property::SPREAD_METHOD | spreadMethod | INTEGER or STRING | No | Indicates what happens if gradient starts or ends inside bounds. [More info](@ref gradient-visual-spread-method) | If the *stopOffset* and *stopColor* arrays do not have the same number of elements, then the minimum of the two is used as the stop points. ### Units {#gradient-visual-units} Defines the coordinate system for the attributes: + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient. + Center point (cx, cy) and radius (r) of a circle if using a radial gradient. | Enumeration | String | Description | |-----------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | Dali::Toolkit::GradientVisual::Units::OBJECT_BOUNDING_BOX | OBJECT_BOUNDING_BOX | *Default*. Uses the normals for the start, end & center points, i.e. top-left is (-0.5, -0.5) and bottom-right is (0.5, 0.5). | | Dali::Toolkit::GradientVisual::Units::USER_SPACE | USER_SPACE | Uses the user coordinates for the start, end & center points, i.e. in a 200 by 200 control, top-left is (0, 0) and bottom-right is (200, 200). | ### Spread Method {#gradient-visual-spread-method} Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle. | Enumeration | String | Description | |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------| | Dali::Toolkit::GradientVisual::SpreadMethod::PAD | PAD | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad geometry. | | Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad geometry is filled. | | Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT | REPEAT | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad geometry is filled. | ### Usage **Linear:** ~~~{.cpp} // C++ Dali::Toolkit::Control control = Dali::Toolkit::Control::New(); Dali::Property::Map map; map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT; map[ GradientVisual::Property::START_POSITION ] = Vector2( 0.5f, 0.5f ); map[ GradientVisual::Property::END_POSITION ] = Vector2( -0.5f, -0.5f ); Dali::Property::Array stopOffsets; stopOffsets.PushBack( 0.0f ); stopOffsets.PushBack( 0.3f ); stopOffsets.PushBack( 0.6f ); stopOffsets.PushBack( 0.8f ); stopOffsets.PushBack( 1.f ); map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets; Dali::Property::Array stopColors; stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f ); stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f ); stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f ); stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f ); stopColors.PushBack( Color::YELLOW ); map[ GradientVisual::Property::STOP_COLOR ] = stopColors; control.SetProperty( Control::Property::BACKGROUND, map ); ~~~ **Radial:** ~~~{.cpp} // C++ Dali::Toolkit::Control control = Dali::Toolkit::Control::New(); Dali::Property::Map map; map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT; map[ GradientVisual::Property::CENTER ] = Vector2( 0.5f, 0.5f ); map[ GradientVisual::Property::RADIUS ] = 1.414f; Dali::Property::Array stopOffsets; stopOffsets.PushBack( 0.0f ); stopOffsets.PushBack( 0.3f ); stopOffsets.PushBack( 0.6f ); stopOffsets.PushBack( 0.8f ); stopOffsets.PushBack( 1.f ); map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets; Dali::Property::Array stopColors; stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f ); stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f ); stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f ); stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f ); stopColors.PushBack( Color::YELLOW ); map[ GradientVisual::Property::STOP_COLOR ] = stopColors; control.SetProperty( Control::Property::BACKGROUND, map ); ~~~ ___________________________________________________________________________________________________ ## Image Visual {#image-visuals} Renders an image into the visual's geometry. Depending on the extension of the image, a different visual is provided to render the image onto the screen. + [Normal (Quad)](@ref image-visual) + [N-Patch](@ref n-patch-visual) + [SVG](@ref svg-visual) + [Animated Image]( @ref animated-image-visual ) ___________________________ ### Normal {#image-visual} Renders a raster image ( jpg, png etc.) into the visual's quad geometry. ![ ](visuals/image-visual.png) #### Properties Supported **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE" | Property | String | Type | Required | Description | |------------------------------------------------------|---------------|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------| | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the image. | | Dali::Toolkit::ImageVisual::Property::FITTING_MODE | fittingMode | INTEGER or STRING | No | Fitting options, used when resizing images to fit desired dimensions. [More info](@ref resourceimagescaling-fittingmode) | | Dali::Toolkit::ImageVisual::Property::SAMPLING_MODE | samplingMode | INTEGER or STRING | No | Filtering options, used when resizing images to sample original pixels. [More info](@ref resourceimagescaling-scaling) | | Dali::Toolkit::ImageVisual::Property::DESIRED_WIDTH | desiredWidth | INT | No | The desired image width. Will use actual image width if not specified. | | Dali::Toolkit::ImageVisual::Property::DESIRED_HEIGHT | desiredHeight | INT | No | The desired image height. Will use actual image height if not specified. | | Dali::Toolkit::ImageVisual::Property::PIXEL_AREA | pixelArea | VECTOR4 | No | The image area to be displayed, default value is [0.0, 0.0, 1.0, 1.0] | | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_U | wrapModeU | INTEGER or STRING | No | Wrap mode for u coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT | | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_V | wrapModeV | INTEGER or STRING | No | Wrap mode for v coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT | #### Usage ~~~{.cpp} // C++ Dali::Toolkit::Control control = Dali::Toolkit::Control::New(); Dali::Property::Map map; map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE; map[ ImageVisual::Property::URL ] = "path-to-image.jpg"; control.SetProperty( Control::Property::BACKGROUND, map ); ~~~ ___________________________________________________________________________________________________ ### N-Patch {#n-patch-visual} Renders an n-patch or a 9-patch image. Uses non-quad geometry. Both geometry and texture are cached to reduce memory consumption if the same n-patch image is used elsewhere. ![ ](visuals/n-patch-visual.png) #### Properties Supported **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE" | Property | String | Type | Required | Description | |---------------------------------------------------|---------------|:-------:|:--------:|----------------------------------| | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the n-patch image. | | Dali::Toolkit::ImageVisual::Property::BORDER_ONLY | borderOnly | BOOLEAN | No | If true, only draws the borders. | #### Usage ~~~{.cpp} // C++ Dali::Toolkit::Control control = Dali::Toolkit::Control::New(); Dali::Property::Map map; map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE; map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.9.png"; control.SetProperty( Control::Property::BACKGROUND, map ); ~~~ ___________________________________________________________________________________________________ ### SVG {#svg-visual} Renders a svg image into the visual's quad geometry. #### Features: SVG Tiny 1.2 specification **supported:** * basic shapes * paths * solid color fill * gradient color fill * solid color stroke **not supported:** * gradient color stroke * dash array stroke * view box * text * clip path