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 material to exist only when the control is on-stage.
10 Additionaly, 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)
20 Controls can provide properties that allow users to specify the visual type ( rendererType ).
21 Setting visual properties are done via a property map.
22 The **rendererType** field in the property map specifies the visual to use/create.
23 This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents.
24 ___________________________________________________________________________________________________
26 ## Color Visual {#color-visual}
28 Renders a solid color to the control's quad.
30 ![ ](../assets/img/visuals/color-visual.png)
31 ![ ](visuals/color-visual.png)
33 ### Properties Supported
35 **RendererType:** "COLOR"
37 | Property Name | Type | Required | Description |
38 |---------------|:-------:|:--------:|---------------------------|
39 | mixColor | VECTOR4 | Yes | The solid color required. |
45 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
47 Dali::Property::Map map;
48 map[ "rendererType" ] = "COLOR";
49 map[ "mixColor" ] = Color::RED;
51 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
56 var control = new dali.Control( "Control" );
60 rendererType : "COLOR",
61 mixColor : dali.COLOR_RED
64 ___________________________________________________________________________________________________
66 ## Gradient Visual {#gradient-visual}
68 Renders a smooth transition of colors to the control's quad.
70 Both Linear and Radial gradients are supported.
74 | ![ ](../assets/img/visuals/linear-gradient-visual.png) ![ ](visuals/linear-gradient-visual.png) | ![ ](../assets/img/visuals/radial-gradient-visual.png) ![ ](visuals/radial-gradient-visual.png) |
76 ### Properties Supported
78 **RendererType:** "GRADIENT"
80 | Property Name | Type | Required | Description |
81 |------------------------------------------------------|:----------------:|:----------:|--------------------------------------------------------------------------|
82 | startPosition | VECTOR2 | For Linear | The start position of the linear gradient. |
83 | endPosition | VECTOR2 | For Linear | The end position of the linear gradient. |
84 | center | VECTOR2 | For Radial | The center point of the gradient. |
85 | radius | FLOAT | For Radial | The size of the radius. |
86 | stopOffset | ARRAY of FLOAT | No | All the stop offsets. If not supplied default is 0.0 and 1.0. |
87 | stopColor | ARRAY of VECTOR4 | Yes | The color at those stop offsets. At least 2 required to show a gradient. |
88 | [units](@ref gradient-visual-units) | STRING | No | *OBJECT_BOUNDING_BOX* or *USER_SPACE*. Default: *OBJECT_BOUNDING_BOX*. |
89 | [spreadMethod](@ref gradient-visual-spread-method) | STRING | No | *PAD*, *REFLECT* or *REPEAT*. Default: *PAD*. |
91 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.
93 ### Units {#gradient-visual-units}
95 Defines the coordinate system for the attributes:
96 + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
97 + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
99 | Value | Description |
100 |---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
101 | 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). |
102 | 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). |
104 ### Spread Method {#gradient-visual-spread-method}
106 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
108 | Value | Description |
109 |---------|------------------------------------------------------------------------------------------------------|
110 | PAD | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad. |
111 | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad is filled. |
112 | REPEAT | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad is filled. |
119 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
121 Dali::Property::Map map;
122 map[ "rendererType" ] = "GRADIENT";
123 map[ "startPosition" ] = Vector2( 0.5f, 0.5f );
124 map[ "endPosition" ] = Vector2( -0.5f, -0.5f );
126 Dali::Property::Array stopOffsets;
127 stopOffsets.PushBack( 0.0f );
128 stopOffsets.PushBack( 0.3f );
129 stopOffsets.PushBack( 0.6f );
130 stopOffsets.PushBack( 0.8f );
131 stopOffsets.PushBack( 1.f );
132 map[ "stopOffset" ] = stopOffsets;
134 Dali::Property::Array stopColors;
135 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
136 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
137 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
138 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
139 stopColors.PushBack( Color::YELLOW );
140 map[ "stopColor" ] = stopColors;
142 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
147 var control = new dali.Control( "Control" );
151 rendererType : "GRADIENT",
152 startPosition : [ 0.5, 0.5 ],
153 endPosition : [ -0.5, -0.5 ],
154 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
156 [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
157 [ 196 / 255, 198 / 255, 71 / 255, 122 / 255 ],
158 [ 214 / 255, 37 / 255, 139 / 255, 191 / 255 ],
159 [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
168 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
170 Dali::Property::Map map;
171 map[ "rendererType" ] = "GRADIENT";
172 map[ "center" ] = Vector2( 0.5f, 0.5f );
173 map[ "radius" ] = 1.414f;
175 Dali::Property::Array stopOffsets;
176 stopOffsets.PushBack( 0.0f );
177 stopOffsets.PushBack( 0.3f );
178 stopOffsets.PushBack( 0.6f );
179 stopOffsets.PushBack( 0.8f );
180 stopOffsets.PushBack( 1.f );
181 map[ "stopOffset" ] = stopOffsets;
183 Dali::Property::Array stopColors;
184 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
185 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
186 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
187 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
188 stopColors.PushBack( Color::YELLOW );
189 map[ "stopColor" ] = stopColors;
191 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
196 var control = new dali.Control( "Control" );
200 rendererType : "GRADIENT",
201 center : [ 0.5, 0.5 ],
203 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
205 [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
206 [ 196 / 255, 198 / 255, 71 / 255, 122 / 255 ],
207 [ 214 / 255, 37 / 255, 139 / 255, 191 / 255 ],
208 [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
213 ___________________________________________________________________________________________________
215 ## Image Visual {#image-visuals}
217 Renders an image into the control's quad.
219 Depending on the extension of the image, a different visual is provided to render the image onto the screen.
221 + [Normal](@ref image-visual)
222 + [N-Patch](@ref n-patch-visual)
223 + [SVG](@ref svg-visual)
225 ___________________________
227 ### Normal {#image-visual}
229 Renders a raster image ( jpg, png etc.) into the control's quad.
231 ![ ](../assets/img/visuals/image-visual.png)
232 ![ ](visuals/image-visual.png)
234 #### Properties Supported
236 **RendererType:** "IMAGE"
238 | Property Name | Type | Required | Description |
239 |------------------------------------------------------|:--------:|:--------:|----------------------------------------------------------------------------------------------------------------|
240 | url | STRING | Yes | The URL of the image. |
241 | [fittingMode](@ref resourceimagescaling-fittingmode) | STRING | No | *SHRINK_TO_FIT*, *SCALE_TO_FILL*, *FIT_WIDTH* or *FIT_HEIGHT*. Default: *SHRINK_TO_FIT*. |
242 | [samplingMode](@ref resourceimagescaling-scaling) | STRING | No | *BOX*, *NEAREST*, *LINEAR*, *BOX_THEN_NEAREST*, *BOX_THEN_LINEAR*, *NO_FILTER* or *DONT_CARE*. Default: *BOX*. |
243 | desiredWidth | INT | No | The desired image width. Will use actual image width if not specified. |
244 | desiredHeight | INT | No | The desired image height. Will use actual image height if not specified. |
250 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
252 Dali::Property::Map map;
253 map[ "rendererType" ] = "IMAGE";
254 map[ "url" ] = "path-to-image.jpg";
256 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
261 var control = new dali.Control( "Control" );
265 rendererType : "IMAGE",
266 url : "path-to-image.jpg"
269 ___________________________________________________________________________________________________
271 ### N-Patch {#n-patch-visual}
273 Renders an n-patch or a 9-patch image into the control's quad.
275 ![ ](../assets/img/visuals/n-patch-visual.png)
276 ![ ](visuals/n-patch-visual.png)
278 #### Properties Supported
280 **RendererType:** "IMAGE"
282 | Property Name | Type | Required | Description |
283 |---------------|:-------:|:--------:|----------------------------------|
284 | url | STRING | Yes | The URL of the n-patch image. |
285 | borderOnly | BOOLEAN | No | If true, only draws the borders. |
291 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
293 Dali::Property::Map map;
295 map[ "rendererType" ] = "IMAGE";
296 map[ "url" ] = "path-to-image.9.png";
298 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
303 var control = new dali.Control( "Control" );
307 rendererType : "IMAGE",
308 url : "path-to-image.9.png"
312 ___________________________________________________________________________________________________
314 ### SVG {#svg-visual}
316 Renders a svg image into the control's quad.
318 #### Features: SVG Tiny 1.2 specification
325 * gradient color fill
330 * gradient color stroke
336 <div style="width:300px">
338 ![ ](../assets/img/visuals/svg-visual.svg)
342 <div style="width:300px">
344 ![ ](visuals/svg-visual.svg)
349 #### Properties Supported
351 **RendererType:** "IMAGE"
353 | Property Name | Type | Required | Description |
354 |---------------|:-------:|:--------:|----------------------------------|
355 | url | STRING | Yes | The URL of the SVG image. |
361 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
363 Dali::Property::Map map;
365 map[ "rendererType" ] = "IMAGE";
366 map[ "url" ] = "path-to-image.svg";
368 control.SetSize( 200.f, 200.f );
369 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
374 var control = new dali.Control( "Control" );
378 rendererType : "IMAGE",
379 url : "path-to-image.svg"
382 ___________________________________________________________________________________________________
384 ## Border Visual {#border-visual}
386 Renders a solid color as an internal border to the control's quad.
388 ![ ](../assets/img/visuals/border-visual.png)
389 ![ ](visuals/border-visual.png)
391 ### Properties Supported
393 **RendererType:** "BORDER"
395 | Property Name | Type | Required | Description |
396 |---------------|:-------:|:--------:|--------------------------------------------------|
397 | borderColor | VECTOR4 | Yes | The color of the border. |
398 | borderSize | FLOAT | Yes | The width of the border (in pixels). |
399 | antiAliasing | BOOLEAN | No | Whether anti-aliasing of the border is required. |
405 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
407 Dali::Property::Map map;
409 map[ "rendererType" ] = "BORDER";
410 map[ "borderColor" ] = Color::BLUE;
411 map[ "borderSize" ] = 5.0f;
413 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
418 var control = new dali.Control( "Control" );
422 rendererType : "BORDER",
423 borderColor : dali.COLOR_BLUE,
428 ___________________________________________________________________________________________________
430 ## Mesh Visual {#mesh-visual}
432 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
434 ![ ](../assets/img/visuals/mesh-visual.png)
435 ![ ](visuals/mesh-visual.png)
437 ### Properties Supported
439 **RendererType** "MESH"
441 | Property Name | Type | Required | Description |
442 |----------------------------------------------|:-------:|:------------------:|--------------------------------------------------------------------------------------------|
443 | objectUrl | STRING | Yes | The location of the ".obj" file. |
444 | materialUrl | STRING | No | The location of the ".mtl" file. Leave blank for a textureless object. |
445 | texturesPath | STRING | If using material | Path to the directory the textures (including gloss and normal) are stored in. |
446 | [shaderType](@ref mesh-visual-shader-type) | STRING | No | Sets the type of shader to be used with the mesh. |
447 | useMipmapping | BOOLEAN | No | Flag for whether to use mipmaps for textures or not. Default true. |
448 | useSoftNormals | BOOLEAN | No | Flag for whether to average normals at each point to smooth textures or not. Default true. |
449 | lightPosition | VECTOR3 | No | The position, in stage space, of the point light that applies lighting to the model. This is based off the stage's dimensions, so using the width and height of the stage halved will correspond to the center, and using all zeroes will place the light at the top left. Note that this corresponds to a shader property, so it can be registered and set in the actor as well. |
452 ### Shader Type {#mesh-visual-shader-type}
454 When specifying the shader type, if anything the shader requires is missing, a simpler type that can be handled with what has been supplied will be used instead.
458 | String Value | Description |
459 |-----------------|------------------------------------------------|
460 | TEXTURELESS | *Simplest*. A flat color with shading is used. |
461 | DIFFUSE_TEXTURE | Textured. |
462 | ALL_TEXTURES | Has a gloss, normal map and texture map. |
468 Dali::Stage stage = Dali::Stage::GetCurrent();
469 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
471 Dali::Property::Map map;
473 map[ "rendererType" ] = "MESH";
474 map[ "objectUrl" ] = "home/models/Dino.obj";
475 map[ "materialUrl" ] = "home/models/Dino.mtl";
476 map[ "texturesPath" ] = "home/images/";
478 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
481 ___________________________________________________________________________________________________
483 ## Primitive Visual {#primitive-visual}
485 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
487 ![ ](../assets/img/visuals/cube.png)
488 ![ ](visuals/cube.png)
490 ### Properties Supported
492 **RendererType** "PRIMITIVE"
494 | Property Name | Type | Description | Default Value | Range |
495 |---------------------------------------|:-------:|---------------------------------------------------------------------------------|:--------------------:|:------------------------------:|
496 | [shape](@ref shape-details) | STRING | The specific shape to render. | "SPHERE" | [See list](@ref shape-details) |
497 | shapeColor | VECTOR4 | The color of the shape. | (0.5, 0.5, 0.5, 1.0) | 0.0 - 1.0 for each |
498 | [slices](@ref slices-details) | INT | The number of slices as you go around the shape. | 128 | 1 - 255 |
499 | [stacks](@ref stacks-details) | INT | The number of stacks as you go down the shape. | 128 | 1 - 255 |
500 | scaleTopRadius | FLOAT | The scale of the radius of the top circle of a conical frustrum. | 1.0 | ≥ 0.0 |
501 | scaleBottomRadius | FLOAT | The scale of the radius of the bottom circle of a conical frustrum. | 1.5 | ≥ 0.0 |
502 | scaleHeight | FLOAT | The scale of the height of a conic. | 3.0 | > 0.0 |
503 | scaleRadius | FLOAT | The scale of the radius of a cylinder. | 1.0 | > 0.0 |
504 | scaleDimensions | VECTOR3 | The dimensions of a cuboid. Scales in the same fashion as a 9-patch image. | (1.0, 1.0, 1.0) | > 0.0 for each |
505 | [bevelPercentage](@ref bevel-details) | FLOAT | Determines how bevelled the cuboid should be, based off the smallest dimension. | 0.0 (no bevel) | 0.0 - 1.0 |
506 | bevelSmoothness | FLOAT | Defines how smooth the bevelled edges should be. | 0.0 (sharp edges) | 0.0 - 1.0 |
507 | lightPosition | VECTOR3 | The position, in stage space, of the point light that applies lighting to the model. This is based off the stage's dimensions, so using the width and height of the stage halved will correspond to the center, and using all zeroes will place the light at the top left. Note that this corresponds to a shader property, so it can be registered and set in the actor as well. | (Offset outwards from the center of the screen.) | Unlimited |
509 ### Shapes {#shape-details}
511 There are six shapes that can be chosen, some of which are simplified specialisations of another.
513 | Value | Description | Parameters |
514 |------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
515 | SPHERE | *Default*. | color, slices, stacks |
516 | CONICAL_FRUSTRUM | The area bound between two circles, i.e. a cone with the tip removed. | color, scaleTopRadius, scaleBottomRadius, scaleHeight, slices |
517 | CONE | Equivalent to a conical frustrum with top radius of zero. | color, scaleBottomRadius, scaleHeight, slices |
518 | CYLINDER | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices |
519 | CUBE | Equivalent to a bevelled cube with a bevel percentage of zero. | color, scaleDimensions |
520 | OCTAHEDRON | Equivalent to a bevelled cube with a bevel percentage of one. | color, scaleDimensions |
521 | BEVELLED_CUBE | A cube/cuboid with all edges flattened to some degree. | color, scaleDimensions, bevelPercentage, bevelSmoothness |
527 ![ ](../assets/img/visuals/sphere.png)
528 ![ ](visuals/sphere.png)
532 | Frustrum | Cone | Cylinder |
533 |----------|------|----------|
534 | ![ ](../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) |
536 ### Bevel {#bevel-details}
538 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:
540 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
541 |-------------|-----|-----|------------------|
542 | ![ ](../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) |
544 ### Slices {#slices-details}
546 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
548 ![ ](../assets/img/visuals/slices.png)
549 ![ ](visuals/slices.png)
551 ### Stacks {#stacks-details}
553 For spheres, 'stacks' determines how many layers there are as you go down the object.
555 ![ ](../assets/img/visuals/stacks.png)
556 ![ ](visuals/stacks.png)
564 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
566 Dali::Property::Map map;
568 map[ "rendererType" ] = "PRIMITIVE";
569 map[ "shape" ] = "SPHERE";
570 map[ "shapeColor" ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
572 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
579 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
581 Dali::Property::Map map;
583 map[ "rendererType" ] = "PRIMITIVE";
584 map[ "shape" ] = "CONICAL_FRUSTRUM";
585 map[ "shapeColor" ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
586 map[ "scaleTopRadius" ] = 1.0f;
587 map[ "scaleBottomRadius" ] = 1.5f;
588 map[ "scaleHeight" ] = 3.0f;
590 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
597 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
599 Dali::Property::Map map;
601 map[ "rendererType" ] = "PRIMITIVE";
602 map[ "shape" ] = "BEVELLED_CUBE";
603 map[ "shapeColor" ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
604 map[ "bevelPercentage" ] = 0.4f;
606 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
609 @class _Guide_Control_Visuals