6 Visuals provide reusable rendering logic which can be used by all controls.
7 This means that custom controls do not have to create actors, they can just reuse the existing visuals which increases performance.
9 Visuals reuse geometry, shaders etc. across controls and manages the renderer and texture to exist only when the control is on-stage.
10 Additionally, they respond to actor size and color change, while also providing clipping at the renderer level.
12 DALi provides the following visuals:
13 + [Color](@ref color-visual)
14 + [Gradient](@ref gradient-visual)
15 + [Image](@ref image-visuals)
16 + [Border](@ref border-visual)
17 + [Mesh](@ref mesh-visual)
18 + [Primitive](@ref primitive-visual)
19 + [Text](@ref text-visual)
20 + [Wireframe](@ref wireframe-visual)
22 Controls can provide properties that allow users to specify the visual type ( visualType ).
23 Setting visual properties are done via a property map.
24 The **visualType** field in the property map specifies the visual to use/create.
25 This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents.
27 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:
29 | Property | String | Type | Required | Description |
30 |----------------------------------------------------------------|--------------|:-----------------:|:--------:|---------------------------------------------------------------------------------------------|
31 | Dali::Toolkit::Visual::Transform::Property::OFFSET | offset | VECTOR2 | No | The offset of the visual. |
32 | Dali::Toolkit::Visual::Transform::Property::SIZE | size | VECTOR2 | No | The size of the visual. |
33 | Dali::Toolkit::Visual::Transform::Property::OFFSET_POLICY | offsetPolicy | VECTOR4 | No | Whether the offset components are Relative or Absolute [More info](@ref offset-size-policy) |
34 | Dali::Toolkit::Visual::Transform::Property::SIZE_POLICY | sizePolicy | VECTOR4 | No | Whether the size components are Relative or Absolute [More info](@ref offset-size-policy) |
35 | 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) |
36 | Dali::Toolkit::Visual::Transform::Property::ANCHOR_POINT | anchorPoint | INTEGER or STRING | No | The anchor point of the visual. [More info](@ref align-type) |
39 ## Offset & Size Policy {#offset-size-policy}
41 The offset and size policies can be either Relative or Absolute.
43 | Enumeration | String | Description |
44 |---------------------------------------------------------|----------|-------------------------------------------------------------------------------|
45 | Dali::Toolkit::Visual::Transform::Policy::RELATIVE | RELATIVE | *Default*. The size or offset value represents a ratio of the control's size |
46 | Dali::Toolkit::Visual::Transform::Policy::ABSOLUTE | ABSOLUTE | The size or offset value represents world units (pixels) |
48 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.
50 ## Alignment {#align-type}
51 | Enumeration | String | Description |
52 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
53 | 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) |
54 | Dali::Toolkit::Align::TOP_CENTER | TOP_CENTER | Aligns to the top of the vertical axis and the center of the horizontal axis |
55 | 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) |
56 | Dali::Toolkit::Align::CENTER_BEGIN | CENTER_BEGIN | Aligns to the center of the vertical axis and the beginning of the horizontal axis|
57 | Dali::Toolkit::Align::CENTER | CENTER | Aligns to the center of the control |
58 | Dali::Toolkit::Align::CENTER_END | CENTER_END | Aligns to the center of the vertical axis and end of the horizontal axis |
59 | Dali::Toolkit::Align::BOTTOM_BEGIN | BOTTOM_BEGIN | Aligns to the bottom of the vertical axis and the beginning of the horizontal axis|
60 | Dali::Toolkit::Align::BOTTOM_CENTER | BOTTOM_CENTER | Aligns to the bottom of the vertical axis and the center of the horizontal axis
61 | Dali::Toolkit::Align::BOTTOM_END | BOTTOM_END | Aligns to the bottom of the vertical axis and end of the horizontal axis |
63 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:
66 | Property | String | Type | Required | Description |
67 |-----------------------------------------------------------|----------------|:--------------------------:|:--------:|--------------------------------------------------------------------------------------------|
68 | 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. |
69 | 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. |
70 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_X | subdivideGridX | INTEGER | No | How to subdivide the grid along the X-Axis. Defaults to 1. |
71 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_Y | subdivideGridY | INTEGER | No | How to subdivide the grid along the Y-Axis. Defaults to 1. |
72 | Dali::Toolkit::Visual::Shader::Property::HINTS | hints | INTEGER or ARRAY of STRING | No | Shader hints bitmask [More info](@ref shader-hints) |
74 ## Shader hints {#shader-hints}
76 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.
78 The bitmask can have the following values:
80 | Value | Description |
81 |-------------------------------------------|----------------------------------------|
82 | Dali::Shader::Hint::NONE | No hints |
83 | Dali::Shader::Hint::OUTPUT_IS_TRANSPARENT | Might generate transparent alpha from opaque inputs |
84 | Dali::Shader::Hint::MODIFIES_GEOMETRY | Might change the position of vertices - this disables culling optimizations |
87 See also Dali::Shader::Hint::Value enumeration.
89 ___________________________________________________________________________________________________
91 ## Color Visual {#color-visual}
93 Renders a color to the visual's quad geometry.
95 ![ ](../assets/img/visuals/color-visual.png)
96 ![ ](visuals/color-visual.png)
98 ### Properties Supported
100 **VisualType:** Dali::Toolkit::Visual::COLOR, "COLOR"
102 | Property | String | Type | Required | Description |
103 |-------------------------------------------------|----------|:-------:|:--------:|---------------------------|
104 | Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes | The color required. |
110 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
112 Dali::Property::Map map;
113 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::COLOR;
114 map[ ColorVisual::Property::MIX_COLOR ] = Color::RED;
116 control.SetProperty( Control::Property::BACKGROUND, map );
121 var control = new dali.Control( "Control" );
125 visualType : "COLOR",
126 mixColor : dali.COLOR_RED
129 ___________________________________________________________________________________________________
131 ## Gradient Visual {#gradient-visual}
133 Renders a smooth transition of colors to the visual's quad geometry.
135 Both Linear and Radial gradients are supported.
139 | ![ ](../assets/img/visuals/linear-gradient-visual.png) ![ ](visuals/linear-gradient-visual.png) | ![ ](../assets/img/visuals/radial-gradient-visual.png) ![ ](visuals/radial-gradient-visual.png) |
141 ### Properties Supported
143 **VisualType:** Dali::Toolkit::Visual::GRADIENT, "GRADIENT"
145 | Property | String | Type | Required | Description |
146 |---------------------------------------------------------|---------------|:-----------------:|:----------:|------------------------------------------------------------------------------------------------------------------|
147 | Dali::Toolkit::GradientVisual::Property::START_POSITION | startPosition | VECTOR2 | For Linear | The start position of the linear gradient. |
148 | Dali::Toolkit::GradientVisual::Property::END_POSITION | endPosition | VECTOR2 | For Linear | The end position of the linear gradient. |
149 | Dali::Toolkit::GradientVisual::Property::CENTER | center | VECTOR2 | For Radial | The center point of the gradient. |
150 | Dali::Toolkit::GradientVisual::Property::RADIUS | radius | FLOAT | For Radial | The size of the radius. |
151 | 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. |
152 | 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. |
153 | Dali::Toolkit::GradientVisual::Property::UNITS | units | INTEGER or STRING | No | Defines the coordinate system. [More info](@ref gradient-visual-units) |
154 | 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) |
156 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.
158 ### Units {#gradient-visual-units}
160 Defines the coordinate system for the attributes:
161 + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
162 + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
164 | Enumeration | String | Description |
165 |-----------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
166 | 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). |
167 | 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). |
169 ### Spread Method {#gradient-visual-spread-method}
171 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
173 | Enumeration | String | Description |
174 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
175 | Dali::Toolkit::GradientVisual::SpreadMethod::PAD | PAD | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad geometry. |
176 | 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. |
177 | 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. |
184 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
186 Dali::Property::Map map;
187 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
188 map[ GradientVisual::Property::START_POSITION ] = Vector2( 0.5f, 0.5f );
189 map[ GradientVisual::Property::END_POSITION ] = Vector2( -0.5f, -0.5f );
191 Dali::Property::Array stopOffsets;
192 stopOffsets.PushBack( 0.0f );
193 stopOffsets.PushBack( 0.3f );
194 stopOffsets.PushBack( 0.6f );
195 stopOffsets.PushBack( 0.8f );
196 stopOffsets.PushBack( 1.f );
197 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
199 Dali::Property::Array stopColors;
200 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
201 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
202 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
203 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
204 stopColors.PushBack( Color::YELLOW );
205 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
207 control.SetProperty( Control::Property::BACKGROUND, map );
212 var control = new dali.Control( "Control" );
216 visualType : "GRADIENT",
217 startPosition : [ 0.5, 0.5 ],
218 endPosition : [ -0.5, -0.5 ],
219 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
221 [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
222 [ 196 / 255, 198 / 255, 71 / 255, 122 / 255 ],
223 [ 214 / 255, 37 / 255, 139 / 255, 191 / 255 ],
224 [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
233 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
235 Dali::Property::Map map;
236 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
237 map[ GradientVisual::Property::CENTER ] = Vector2( 0.5f, 0.5f );
238 map[ GradientVisual::Property::RADIUS ] = 1.414f;
240 Dali::Property::Array stopOffsets;
241 stopOffsets.PushBack( 0.0f );
242 stopOffsets.PushBack( 0.3f );
243 stopOffsets.PushBack( 0.6f );
244 stopOffsets.PushBack( 0.8f );
245 stopOffsets.PushBack( 1.f );
246 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
248 Dali::Property::Array stopColors;
249 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
250 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
251 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
252 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
253 stopColors.PushBack( Color::YELLOW );
254 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
256 control.SetProperty( Control::Property::BACKGROUND, map );
261 var control = new dali.Control( "Control" );
265 visualType : "GRADIENT",
266 center : [ 0.5, 0.5 ],
268 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
270 [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
271 [ 196 / 255, 198 / 255, 71 / 255, 122 / 255 ],
272 [ 214 / 255, 37 / 255, 139 / 255, 191 / 255 ],
273 [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
278 ___________________________________________________________________________________________________
280 ## Image Visual {#image-visuals}
282 Renders an image into the visual's geometry.
284 Depending on the extension of the image, a different visual is provided to render the image onto the screen.
286 + [Normal (Quad)](@ref image-visual)
287 + [N-Patch](@ref n-patch-visual)
288 + [SVG](@ref svg-visual)
289 + [Animated Image]( @ref animated-image-visual )
291 ___________________________
293 ### Normal {#image-visual}
295 Renders a raster image ( jpg, png etc.) into the visual's quad geometry.
297 ![ ](../assets/img/visuals/image-visual.png)
298 ![ ](visuals/image-visual.png)
300 #### Properties Supported
302 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
304 | Property | String | Type | Required | Description |
305 |------------------------------------------------------|---------------|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------|
306 | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the image. |
307 | 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) |
308 | 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) |
309 | Dali::Toolkit::ImageVisual::Property::DESIRED_WIDTH | desiredWidth | INT | No | The desired image width. Will use actual image width if not specified. |
310 | Dali::Toolkit::ImageVisual::Property::DESIRED_HEIGHT | desiredHeight | INT | No | The desired image height. Will use actual image height if not specified. |
311 | 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] |
312 | 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 |
313 | 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 |
319 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
321 Dali::Property::Map map;
322 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
323 map[ ImageVisual::Property::URL ] = "path-to-image.jpg";
325 control.SetProperty( Control::Property::BACKGROUND, map );
330 var control = new dali.Control( "Control" );
334 visualType : "IMAGE",
335 url : "path-to-image.jpg"
338 ___________________________________________________________________________________________________
340 ### N-Patch {#n-patch-visual}
342 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.
344 ![ ](../assets/img/visuals/n-patch-visual.png)
345 ![ ](visuals/n-patch-visual.png)
347 #### Properties Supported
349 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
351 | Property | String | Type | Required | Description |
352 |---------------------------------------------------|---------------|:-------:|:--------:|----------------------------------|
353 | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the n-patch image. |
354 | Dali::Toolkit::ImageVisual::Property::BORDER_ONLY | borderOnly | BOOLEAN | No | If true, only draws the borders. |
360 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
362 Dali::Property::Map map;
364 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
365 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.9.png";
367 control.SetProperty( Control::Property::BACKGROUND, map );
372 var control = new dali.Control( "Control" );
376 visualType : "IMAGE",
377 url : "path-to-image.9.png"
381 ___________________________________________________________________________________________________
383 ### SVG {#svg-visual}
385 Renders a svg image into the visual's quad geometry.
387 #### Features: SVG Tiny 1.2 specification
394 * gradient color fill
399 * gradient color stroke
405 <div style="width:300px">
407 ![ ](../assets/img/visuals/svg-visual.svg)
411 <div style="width:300px">
413 ![ ](visuals/svg-visual.svg)
418 #### Properties Supported
420 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
422 | Property | String | Type | Required | Description |
423 |-------------------------------------------|--------|:-------:|:--------:|----------------------------------|
424 | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the SVG image. |
430 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
432 Dali::Property::Map map;
434 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
435 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.svg";
437 control.SetSize( 200.f, 200.f );
438 control.SetProperty( Control::Property::BACKGROUND, map );
443 var control = new dali.Control( "Control" );
447 visualType : "IMAGE",
448 url : "path-to-image.svg"
452 ___________________________________________________________________________________________________
454 ## Animated Image Visual {#animated-image-visual}
456 Renders an animated image into the visual's quad geometry. Currently, only the GIF format is supported.
458 ![ ](../assets/img/visuals/animated-image-visual.gif)
459 ![ ](animated-image-visual.gif)
461 #### Properties Supported
463 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
465 | Property | String | Type | Required | Description |
466 |---------------------------------------------------|------------|:-----------------:|:--------:|----------------------------------------------------------------------------------------------|
467 | Dali::Toolkit::ImageVisual::Property::URL | url | STRING | Yes | The URL of the animated image. |
468 | 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] |
469 | 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 |
470 | 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 |
476 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
478 control.SetProperty( Control::Property::BACKGROUND,
479 Property::Map().Add( Visual::Property::TYPE, Dali::Toolkit::Visual::IMAGE )
480 .Add( Dali::Toolkit::ImageVisual::Property::URL, "path-to-image.gif" ) );
485 var control = new dali.Control( "Control" );
489 visualType : "IMAGE",
490 url : "path-to-image.gif"
493 ___________________________________________________________________________________________________
495 ## Border Visual {#border-visual}
497 Renders a color as an internal border to the visual's geometry.
499 ![ ](../assets/img/visuals/border-visual.png)
500 ![ ](visuals/border-visual.png)
502 ### Properties Supported
504 **VisualType:** Dali::Toolkit::Visual::BORDER, "BORDER"
506 | Property | String | Type | Required | Description |
507 |------------------------------------------------------|---------------|:-------:|:--------:|--------------------------------------------------|
508 | Dali::Toolkit::BorderVisual::Property::COLOR | borderColor | VECTOR4 | Yes | The color of the border. |
509 | Dali::Toolkit::BorderVisual::Property::SIZE | borderSize | FLOAT | Yes | The width of the border (in pixels). |
510 | Dali::Toolkit::BorderVisual::Property::ANTI_ALIASING | antiAliasing | BOOLEAN | No | Whether anti-aliasing of the border is required. |
516 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
518 Dali::Property::Map map;
520 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::BORDER;
521 map[ BorderVisual::Property::COLOR ] = Color::BLUE;
522 map[ BorderVisual::Property::SIZE ] = 5.0f;
524 control.SetProperty( Control::Property::BACKGROUND, map );
529 var control = new dali.Control( "Control" );
533 visualType : "BORDER",
534 borderColor : dali.COLOR_BLUE,
539 ___________________________________________________________________________________________________
541 ## Mesh Visual {#mesh-visual}
543 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
545 ![ ](../assets/img/visuals/mesh-visual.png)
546 ![ ](visuals/mesh-visual.png)
548 ### Properties Supported
550 **VisualType:** Dali::Toolkit::Visual::MESH, "MESH"
552 | Property | String | Type | Required | Description |
553 |-------------------------------------------------------|----------------|:------------------:|:-----------------:|--------------------------------------------------------------------------------------------------|
554 | Dali::Toolkit::MeshVisual::Property::OBJECT_URL | objectUrl | STRING | Yes | The location of the ".obj" file. |
555 | Dali::Toolkit::MeshVisual::Property::MATERIAL_URL | materialUrl | STRING | No | The location of the ".mtl" file. Leave blank for a textureless object. |
556 | Dali::Toolkit::MeshVisual::Property::TEXTURES_PATH | texturesPath | STRING | If using material | Path to the directory the textures (including gloss and normal) are stored in. |
557 | Dali::Toolkit::MeshVisual::Property::SHADING_MODE | shadingMode | INTEGER or STRING | No | Sets the type of shading mode that the mesh will use. [More info](@ref mesh-visual-shading-mode) |
558 | Dali::Toolkit::MeshVisual::Property::USE_MIPMAPPING | useMipmapping | BOOLEAN | No | Flag for whether to use mipmaps for textures or not. Default true. |
559 | Dali::Toolkit::MeshVisual::Property::USE_SOFT_NORMALS | useSoftNormals | BOOLEAN | No | Flag for whether to average normals at each point to smooth textures or not. Default true. |
560 | Dali::Toolkit::MeshVisual::Property::LIGHT_POSITION | lightPosition | VECTOR3 | No | The position, in stage space, of the point light that applies lighting to the model. |
562 ### Shading Mode {#mesh-visual-shading-mode}
564 When specifying the shading mode, if anything the mode requires is missing, a simpler mode that can be handled with what has been supplied will be used instead.
568 | Enumeration | String | Description |
569 |---------------------------------------------------------------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
570 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURELESS_WITH_DIFFUSE_LIGHTING | TEXTURELESS_WITH_DIFFUSE_LIGHTING | *Simplest*. One color that is lit by ambient and diffuse lighting. |
571 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURED_WITH_SPECULAR_LIGHTING | TEXTURED_WITH_SPECULAR_LIGHTING | Uses only the visual image textures provided with specular lighting in addition to ambient and diffuse lighting. |
572 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURED_WITH_DETAILED_SPECULAR_LIGHTING | TEXTURED_WITH_DETAILED_SPECULAR_LIGHTING | Uses all textures provided including a gloss, normal and texture map along with specular, ambient and diffuse lighting. |
578 Dali::Stage stage = Dali::Stage::GetCurrent();
579 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
581 Dali::Property::Map map;
583 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::MESH;
584 map[ MeshVisual::Property::OBJECT_URL ] = "home/models/Dino.obj";
585 map[ MeshVisual::Property::MATERIAL_URL ] = "home/models/Dino.mtl";
586 map[ MeshVisual::Property::TEXTURES_PATH ] = "home/images/";
588 control.SetProperty( Control::Property::BACKGROUND, map );
591 ___________________________________________________________________________________________________
593 ## Primitive Visual {#primitive-visual}
595 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
597 The shapes are generated with clockwise winding and back-face culling on by default.
599 ![ ](../assets/img/visuals/cube.png)
600 ![ ](visuals/cube.png)
602 ### Properties Supported
604 **VisualType:** Dali::Toolkit::Visual::PRIMITIVE, "PRIMITIVE"
606 | Property | String | Type | Description | Default Value | Range |
607 |---------------------------------------------------------------|-------------------|:------------------:|-----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------:|:------------------------------:|
608 | Dali::Toolkit::PrimitiveVisual::Property::SHAPE | shape | INTEGER or STRING | The specific shape to render. [More info](@ref shape-details) | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE, "SPHERE" | [See list](@ref shape-details) |
609 | Dali::Toolkit::PrimitiveVisual::Property::MIX_COLOR | mixColor | VECTOR4 | The color of the shape. | (0.5, 0.5, 0.5, 1.0) | 0.0 - 1.0 for each |
610 | Dali::Toolkit::PrimitiveVisual::Property::SLICES | slices | INTEGER | The number of slices as you go around the shape. [More info](@ref slices-details) | 128 | 1 - 255 |
611 | Dali::Toolkit::PrimitiveVisual::Property::STACKS | stacks | INTEGER | The number of stacks as you go down the shape. [More info](@ref stacks-details) | 128 | 1 - 255 |
612 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_TOP_RADIUS | scaleTopRadius | FLOAT | The scale of the radius of the top circle of a conical frustrum. | 1.0 | ≥ 0.0 |
613 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS | scaleBottomRadius | FLOAT | The scale of the radius of the bottom circle of a conical frustrum. | 1.5 | ≥ 0.0 |
614 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_HEIGHT | scaleHeight | FLOAT | The scale of the height of a conic. | 3.0 | > 0.0 |
615 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_RADIUS | scaleRadius | FLOAT | The scale of the radius of a cylinder. | 1.0 | > 0.0 |
616 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_DIMENSIONS | scaleDimensions | VECTOR3 | The dimensions of a cuboid. Scales in the same fashion as a 9-patch image. | Vector3::ONE | > 0.0 for each |
617 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_PERCENTAGE | bevelPercentage | FLOAT | Determines how bevelled the cuboid should be, based off the smallest dimension. [More info](@ref bevel-details) | 0.0 (no bevel) | 0.0 - 1.0 |
618 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_SMOOTHNESS | bevelSmoothness | FLOAT | Defines how smooth the bevelled edges should be. | 0.0 (sharp edges) | 0.0 - 1.0 |
619 | Dali::Toolkit::PrimitiveVisual::Property::LIGHT_POSITION | lightPosition | VECTOR3 | The position, in stage space, of the point light that applies lighting to the model. | (Offset outwards from the center of the screen.) | Unlimited |
621 ### Shapes {#shape-details}
623 There are six shapes that can be chosen, some of which are simplified specialisations of another.
625 | Enumeration | String | Description | Parameters |
626 |---------------------------------------------------------|------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
627 | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE | SPHERE | *Default*. | color, slices, stacks |
628 | Dali::Toolkit::PrimitiveVisual::Shape::CONICAL_FRUSTRUM | CONICAL_FRUSTRUM | The area bound between two circles, i.e. a cone with the tip removed. | color, scaleTopRadius, scaleBottomRadius, scaleHeight, slices |
629 | Dali::Toolkit::PrimitiveVisual::Shape::CONE | CONE | Equivalent to a conical frustrum with top radius of zero. | color, scaleBottomRadius, scaleHeight, slices |
630 | Dali::Toolkit::PrimitiveVisual::Shape::CYLINDER | CYLINDER | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices |
631 | Dali::Toolkit::PrimitiveVisual::Shape::CUBE | CUBE | Equivalent to a bevelled cube with a bevel percentage of zero. | color, scaleDimensions |
632 | Dali::Toolkit::PrimitiveVisual::Shape::OCTAHEDRON | OCTAHEDRON | Equivalent to a bevelled cube with a bevel percentage of one. | color, scaleDimensions |
633 | Dali::Toolkit::PrimitiveVisual::Shape::BEVELLED_CUBE | BEVELLED_CUBE | A cube/cuboid with all edges flattened to some degree. | color, scaleDimensions, bevelPercentage, bevelSmoothness |
639 ![ ](../assets/img/visuals/sphere.png)
640 ![ ](visuals/sphere.png)
644 | Frustrum | Cone | Cylinder |
645 |----------|------|----------|
646 | ![ ](../assets/img/visuals/conical-frustrum.png) ![ ](visuals/conical-frustrum.png) | ![ ](../assets/img/visuals/cone.png) ![ ](visuals/cone.png) | ![ ](../assets/img/visuals/cylinder.png) ![ ](visuals/cylinder.png) |
648 ### Bevel {#bevel-details}
650 Bevel percentage ranges from 0.0 to 1.0. It affects the ratio of the outer face widths to the width of the overall cube, as shown:
652 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
653 |-------------|-----|-----|------------------|
654 | ![ ](../assets/img/visuals/cube.png) ![ ](visuals/cube.png) | ![ ](../assets/img/visuals/bevelled-cube-low.png) ![ ](visuals/bevelled-cube-low.png) | ![ ](../assets/img/visuals/bevelled-cube-high.png) ![ ](visuals/bevelled-cube-high.png) | ![ ](../assets/img/visuals/octahedron.png) ![ ](visuals/octahedron.png) |
656 ### Slices {#slices-details}
658 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
660 ![ ](../assets/img/visuals/slices.png)
661 ![ ](visuals/slices.png)
663 ### Stacks {#stacks-details}
665 For spheres, 'stacks' determines how many layers there are as you go down the object.
667 ![ ](../assets/img/visuals/stacks.png)
668 ![ ](visuals/stacks.png)
676 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
678 Dali::Property::Map map;
680 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
681 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::SPHERE;
682 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
684 control.SetProperty( Control::Property::BACKGROUND, map );
691 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
693 Dali::Property::Map map;
695 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
696 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::CONICAL_FRUSTRUM;
697 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
698 map[ PrimitiveVisual::Property::SCALE_TOP_RADIUS ] = 1.0f;
699 map[ PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS ] = 1.5f;
700 map[ PrimitiveVisual::Property::SCALE_HEIGHT ] = 3.0f;
702 control.SetProperty( Control::Property::BACKGROUND, map );
709 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
711 Dali::Property::Map map;
713 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
714 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::BEVELLED_CUBE;
715 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
716 map[ PrimitiveVisual::Property::BEVEL_PERCENTAGE ] = 0.4f;
718 control.SetProperty( Control::Property::BACKGROUND, map );
720 ___________________________________________________________________________________________________
722 ## Text Visual {#text-visual}
724 Renders text within a control.
726 ![ ](../assets/img/visuals/HelloWorld.png)
727 ![ ](visuals/HelloWorld.png)
731 **VisualType:** Dali::Toolkit::Visual::TEXT, "TEXT"
733 | Property | String | Type | Required | Description | Default |
734 |-------------------------------------------------------------|---------------------|:-------------:|:--------:|-------------------------------------------------------------------------------|------------------------|
735 | Dali::Toolkit::TextVisual::Property::TEXT | text | STRING | Yes | The text to display in UTF-8 format | |
736 | Dali::Toolkit::TextVisual::Property::FONT_FAMILY | fontFamily | STRING | No | The requested font family to use | |
737 | Dali::Toolkit::TextVisual::Property::FONT_STYLE | fontStyle | MAP | No | The requested font style to use | |
738 | Dali::Toolkit::TextVisual::Property::POINT_SIZE | pointSize | FLOAT | Yes | The size of font in points | |
739 | Dali::Toolkit::TextVisual::Property::MULTI_LINE | multiLine | BOOLEAN | No | The single-line or multi-line layout option | false |
740 | Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT | horizontalAlignment | STRING | No | The line horizontal alignment: "BEGIN", "CENTER", "END" | "BEGIN" |
741 | Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT | verticalAlignment | STRING | No | The line vertical alignment: "TOP", "CENTER", "BOTTOM" | "TOP" |
742 | Dali::Toolkit::TextVisual::Property::TEXT_COLOR | textColor | VECTOR4 | No | The color of the text | Color::BLACK |
743 | Dali::Toolkit::TextVisual::Property::ENABLE_MARKUP | enableMarkup | BOOL | No | If mark up should be enabled | |
749 Dali::Stage stage = Dali::Stage::GetCurrent();
750 stage.SetBackgroundColor( Dali::Color::WHITE );
752 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
753 control.SetParentOrigin( ParentOrigin::CENTER );
755 Dali::Property::Map map;
756 map[ Dali::Toolkit::Visual::Property::TYPE ] = Dali::Toolkit::Visual::TEXT;
757 map[ Dali::Toolkit::TextVisual::Property::TEXT ] = "Hello world";
758 map[ Dali::Toolkit::TextVisual::Property::TEXT_COLOR ] = Dali::Color::BLACK;
759 map[ Dali::Toolkit::TextVisual::Property::FONT_FAMILY ] = "Sans";
760 map[ Dali::Toolkit::TextVisual::Property::POINT_SIZE ] = 30.f;
761 map[ Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT ] = "CENTER";
762 map[ Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT ] = "CENTER";
764 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
766 stage.Add( control );
769 ## Wireframe Visual {#wireframe-visual}
771 Renders a wireframe around a quad geometry.
772 Is mainly used for debugging and is the visual that replaces all other visuals when [Visual Debug Rendering](@ref debugrendering) is turned on.
774 ![ ](../assets/img/visuals/wireframe-visual.png)
775 ![ ](visuals/wireframe-visual.png)
779 **VisualType:** Dali::Toolkit::Visual::WIREFRAME, "WIREFRAME"
785 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
787 Dali::Property::Map map;
788 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::WIREFRAME;
790 control.SetProperty( Control::Property::BACKGROUND, map );
795 var control = new dali.Control( "Control" );
799 visualType : "WIREFRAME"
804 @class _Guide_Control_Visuals