docs/content/shared-javascript-and-cpp-documentation/visuals.md

   1 <!--
   2 /**-->
   3
   4 # Visuals {#visuals}
   5
   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.
   8
   9 Visuals reuse geometry, shaders etc. across controls and manages the renderer and material 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.
  11
  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  + [Wireframe](@ref wireframe-visual)
  20
  21 Controls can provide properties that allow users to specify the visual type ( visualType ).
  22 Setting visual properties are done via a property map.
  23 The **visualType** field in the property map specifies the visual to use/create.
  24 This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents.
  25 ___________________________________________________________________________________________________
  26
  27 ## Color Visual {#color-visual}
  28
  29 Renders a solid color to the control's quad.
  30
  31 ![ ](../assets/img/visuals/color-visual.png)
  32 ![ ](visuals/color-visual.png)
  33
  34 ### Properties Supported
  35
  36 **VisualType:** Dali::Toolkit::Visual::COLOR, "COLOR"
  37
  38 | Property                                        | String   | Type    | Required | Description               |
  39 |-------------------------------------------------|----------|:-------:|:--------:|---------------------------|
  40 | Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes      | The solid color required. |
  41
  42 ### Usage
  43
  44 ~~~{.cpp}
  45 // C++
  46 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
  47
  48 Dali::Property::Map map;
  49 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::COLOR;
  50 map[ ColorVisual::Property::MIX_COLOR ] = Color::RED;
  51
  52 control.SetProperty( Control::Property::BACKGROUND, map );
  53 ~~~
  54
  55 ~~~{.js}
  56 // JavaScript
  57 var control = new dali.Control( "Control" );
  58
  59 control.background =
  60 {
  61   visualType : "COLOR",
  62   mixColor : dali.COLOR_RED
  63 };
  64 ~~~
  65 ___________________________________________________________________________________________________
  66
  67 ## Gradient Visual {#gradient-visual}
  68
  69 Renders a smooth transition of colors to the control's quad.
  70
  71 Both Linear and Radial gradients are supported.
  72
  73 | Linear | Radial |
  74 |--------|--------|
  75 | ![ ](../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
  77 ### Properties Supported
  78
  79 **VisualType:** Dali::Toolkit::Visual::GRADIENT, "GRADIENT"
  80
  81 | Property                                                | String        | Type              | Required   | Description                                                                                                      |
  82 |---------------------------------------------------------|---------------|:-----------------:|:----------:|------------------------------------------------------------------------------------------------------------------|
  83 | Dali::Toolkit::GradientVisual::Property::START_POSITION | startPosition | VECTOR2           | For Linear | The start position of the linear gradient.                                                                       |
  84 | Dali::Toolkit::GradientVisual::Property::END_POSITION   | endPosition   | VECTOR2           | For Linear | The end position of the linear gradient.                                                                         |
  85 | Dali::Toolkit::GradientVisual::Property::CENTER         | center        | VECTOR2           | For Radial | The center point of the gradient.                                                                                |
  86 | Dali::Toolkit::GradientVisual::Property::RADIUS         | radius        | FLOAT             | For Radial | The size of the radius.                                                                                          |
  87 | 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.                                                    |
  88 | 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.                                         |
  89 | Dali::Toolkit::GradientVisual::Property::UNITS          | units         | INTEGER or STRING | No         | Defines the coordinate system. [More info](@ref gradient-visual-units)                                           |
  90 | 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) |
  91
  92 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
  94 ### Units {#gradient-visual-units}
  95
  96 Defines the coordinate system for the attributes:
  97  + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
  98  + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
  99
 100 | Enumeration                                               | String              | Description                                                                                                                                    |
 101 |-----------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
 102 | 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).                  |
 103 | 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). |
 104
 105 ### Spread Method {#gradient-visual-spread-method}
 106
 107 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
 108
 109 | Enumeration                                          | String  | Description                                                                                          |
 110 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
 111 | Dali::Toolkit::GradientVisual::SpreadMethod::PAD     | PAD     | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad.               |
 112 | Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad is filled. |
 113 | Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT  | REPEAT  | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad is filled.  |
 114
 115 ### Usage
 116
 117 **Linear:**
 118 ~~~{.cpp}
 119 // C++
 120 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 121
 122 Dali::Property::Map map;
 123 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
 124 map[ GradientVisual::Property::START_POSITION ] = Vector2( 0.5f, 0.5f );
 125 map[ GradientVisual::Property::END_POSITION ] = Vector2( -0.5f, -0.5f );
 126
 127 Dali::Property::Array stopOffsets;
 128 stopOffsets.PushBack( 0.0f );
 129 stopOffsets.PushBack( 0.3f );
 130 stopOffsets.PushBack( 0.6f );
 131 stopOffsets.PushBack( 0.8f );
 132 stopOffsets.PushBack( 1.f );
 133 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
 134
 135 Dali::Property::Array stopColors;
 136 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 137 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 138 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 139 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 140 stopColors.PushBack( Color::YELLOW );
 141 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
 142
 143 control.SetProperty( Control::Property::BACKGROUND, map );
 144 ~~~
 145
 146 ~~~{.js}
 147 // JavaScript
 148 var control = new dali.Control( "Control" );
 149
 150 control.background =
 151 {
 152   visualType : "GRADIENT",
 153   startPosition : [ 0.5, 0.5 ],
 154   endPosition : [ -0.5, -0.5 ],
 155   stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 156   stopColor : [
 157     [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
 158     [ 196 / 255, 198 / 255,  71 / 255, 122 / 255 ],
 159     [ 214 / 255,  37 / 255, 139 / 255, 191 / 255 ],
 160     [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
 161     dali.COLOR_YELLOW
 162   ]
 163 };
 164 ~~~
 165
 166 **Radial:**
 167 ~~~{.cpp}
 168 // C++
 169 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 170
 171 Dali::Property::Map map;
 172 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
 173 map[ GradientVisual::Property::CENTER ] = Vector2( 0.5f, 0.5f );
 174 map[ GradientVisual::Property::RADIUS ] = 1.414f;
 175
 176 Dali::Property::Array stopOffsets;
 177 stopOffsets.PushBack( 0.0f );
 178 stopOffsets.PushBack( 0.3f );
 179 stopOffsets.PushBack( 0.6f );
 180 stopOffsets.PushBack( 0.8f );
 181 stopOffsets.PushBack( 1.f );
 182 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
 183
 184 Dali::Property::Array stopColors;
 185 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 186 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 187 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 188 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 189 stopColors.PushBack( Color::YELLOW );
 190 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
 191
 192 control.SetProperty( Control::Property::BACKGROUND, map );
 193 ~~~
 194
 195 ~~~{.js}
 196 // JavaScript
 197 var control = new dali.Control( "Control" );
 198
 199 control.background =
 200 {
 201   visualType : "GRADIENT",
 202   center : [ 0.5, 0.5 ],
 203   radius : 1.414,
 204   stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 205   stopColor : [
 206     [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
 207     [ 196 / 255, 198 / 255,  71 / 255, 122 / 255 ],
 208     [ 214 / 255,  37 / 255, 139 / 255, 191 / 255 ],
 209     [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
 210     dali.COLOR_YELLOW
 211   ]
 212 };
 213 ~~~
 214 ___________________________________________________________________________________________________
 215
 216 ## Image Visual {#image-visuals}
 217
 218 Renders an image into the control's quad.
 219
 220 Depending on the extension of the image, a different visual is provided to render the image onto the screen.
 221
 222  + [Normal (Quad)](@ref image-visual)
 223  + [N-Patch](@ref n-patch-visual)
 224  + [SVG](@ref svg-visual)
 225
 226 ___________________________
 227
 228 ### Normal {#image-visual}
 229
 230 Renders a raster image ( jpg, png etc.) into the control's quad.
 231
 232 ![ ](../assets/img/visuals/image-visual.png)
 233 ![ ](visuals/image-visual.png)
 234
 235 #### Properties Supported
 236
 237 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 238
 239 | Property                                             | String        | Type              | Required | Description                                                                                                              |
 240 |------------------------------------------------------|---------------|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------|
 241 | Dali::Toolkit::ImageVisual::Property::URL            | url           | STRING            | Yes      | The URL of the image.                                                                                                    |
 242 | 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) |
 243 | 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)   |
 244 | Dali::Toolkit::ImageVisual::Property::DESIRED_WIDTH  | desiredWidth  | INT               | No       | The desired image width. Will use actual image width if not specified.                                                   |
 245 | Dali::Toolkit::ImageVisual::Property::DESIRED_HEIGHT | desiredHeight | INT               | No       | The desired image height. Will use actual image height if not specified.                                                 |
 246
 247 #### Usage
 248
 249 ~~~{.cpp}
 250 // C++
 251 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 252
 253 Dali::Property::Map map;
 254 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 255 map[ ImageVisual::Property::URL ] = "path-to-image.jpg";
 256
 257 control.SetProperty( Control::Property::BACKGROUND, map );
 258 ~~~
 259
 260 ~~~{.js}
 261 // JavaScript
 262 var control = new dali.Control( "Control" );
 263
 264 control.background =
 265 {
 266   visualType : "IMAGE",
 267   url : "path-to-image.jpg"
 268 };
 269 ~~~
 270 ___________________________________________________________________________________________________
 271
 272 ### N-Patch {#n-patch-visual}
 273
 274 Renders an n-patch or a 9-patch image into the control's quad.
 275
 276 ![ ](../assets/img/visuals/n-patch-visual.png)
 277 ![ ](visuals/n-patch-visual.png)
 278
 279 #### Properties Supported
 280
 281 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 282
 283 | Property                                          | String        | Type    | Required | Description                      |
 284 |---------------------------------------------------|---------------|:-------:|:--------:|----------------------------------|
 285 | Dali::Toolkit::ImageVisual::Property::URL         | url           | STRING  | Yes      | The URL of the n-patch image.    |
 286 | Dali::Toolkit::ImageVisual::Property::BORDER_ONLY | borderOnly    | BOOLEAN | No       | If true, only draws the borders. |
 287
 288 #### Usage
 289
 290 ~~~{.cpp}
 291 // C++
 292 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 293
 294 Dali::Property::Map map;
 295
 296 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 297 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.9.png";
 298
 299 control.SetProperty( Control::Property::BACKGROUND, map );
 300 ~~~
 301
 302 ~~~{.js}
 303 // JavaScript
 304 var control = new dali.Control( "Control" );
 305
 306 control.background =
 307 {
 308   visualType : "IMAGE",
 309   url : "path-to-image.9.png"
 310 };
 311 ~~~
 312
 313 ___________________________________________________________________________________________________
 314
 315 ### SVG {#svg-visual}
 316
 317 Renders a svg image into the control's quad.
 318
 319 #### Features: SVG Tiny 1.2 specification
 320
 321 **supported:**
 322
 323   * basic shapes
 324   * paths
 325   * solid color fill
 326   * gradient color fill
 327   * solid color stroke
 328
 329 **not supported:**
 330
 331   * gradient color stroke
 332   * dash array stroke
 333   * view box
 334   * text
 335   * clip path
 336
 337 <div style="width:300px">
 338
 339 ![ ](../assets/img/visuals/svg-visual.svg)
 340
 341 </div>
 342
 343 <div style="width:300px">
 344
 345 ![ ](visuals/svg-visual.svg)
 346
 347 </div>
 348
 349
 350 #### Properties Supported
 351
 352 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 353
 354 | Property                                  | String | Type    | Required | Description                      |
 355 |-------------------------------------------|--------|:-------:|:--------:|----------------------------------|
 356 | Dali::Toolkit::ImageVisual::Property::URL | url    | STRING  | Yes      | The URL of the SVG image.    |
 357
 358 #### Usage
 359
 360 ~~~{.cpp}
 361 // C++
 362 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 363
 364 Dali::Property::Map map;
 365
 366 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 367 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.svg";
 368
 369 control.SetSize( 200.f, 200.f );
 370 control.SetProperty( Control::Property::BACKGROUND, map );
 371 ~~~
 372
 373 ~~~{.js}
 374 // JavaScript
 375 var control = new dali.Control( "Control" );
 376
 377 control.background =
 378 {
 379   visualType : "IMAGE",
 380   url : "path-to-image.svg"
 381 };
 382 ~~~
 383 ___________________________________________________________________________________________________
 384
 385 ## Border Visual {#border-visual}
 386
 387 Renders a solid color as an internal border to the control's quad.
 388
 389 ![ ](../assets/img/visuals/border-visual.png)
 390 ![ ](visuals/border-visual.png)
 391
 392 ### Properties Supported
 393
 394 **VisualType:** Dali::Toolkit::Visual::BORDER, "BORDER"
 395
 396 | Property                                             | String        | Type    | Required | Description                                      |
 397 |------------------------------------------------------|---------------|:-------:|:--------:|--------------------------------------------------|
 398 | Dali::Toolkit::BorderVisual::Property::COLOR         | borderColor   | VECTOR4 | Yes      | The color of the border.                         |
 399 | Dali::Toolkit::BorderVisual::Property::SIZE          | borderSize    | FLOAT   | Yes      | The width of the border (in pixels).             |
 400 | Dali::Toolkit::BorderVisual::Property::ANTI_ALIASING | antiAliasing  | BOOLEAN | No       | Whether anti-aliasing of the border is required. |
 401
 402 ### Usage
 403
 404 ~~~{.cpp}
 405 // C++
 406 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 407
 408 Dali::Property::Map map;
 409
 410 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::BORDER;
 411 map[ BorderVisual::Property::COLOR ] = Color::BLUE;
 412 map[ BorderVisual::Property::SIZE ] = 5.0f;
 413
 414 control.SetProperty( Control::Property::BACKGROUND, map );
 415 ~~~
 416
 417 ~~~{.js}
 418 // JavaScript
 419 var control = new dali.Control( "Control" );
 420
 421 control.background =
 422 {
 423   visualType : "BORDER",
 424   borderColor : dali.COLOR_BLUE,
 425   borderSize = 5
 426 };
 427 ~~~
 428
 429 ___________________________________________________________________________________________________
 430
 431 ## Mesh Visual {#mesh-visual}
 432
 433 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
 434
 435 ![ ](../assets/img/visuals/mesh-visual.png)
 436 ![ ](visuals/mesh-visual.png)
 437
 438 ### Properties Supported
 439
 440 **VisualType:** Dali::Toolkit::Visual::MESH, "MESH"
 441
 442 | Property                                              | String         | Type               | Required          | Description                                                                                      |
 443 |-------------------------------------------------------|----------------|:------------------:|:-----------------:|--------------------------------------------------------------------------------------------------|
 444 | Dali::Toolkit::MeshVisual::Property::OBJECT_URL       | objectUrl      | STRING             | Yes               | The location of the ".obj" file.                                                                 |
 445 | Dali::Toolkit::MeshVisual::Property::MATERIAL_URL     | materialUrl    | STRING             | No                | The location of the ".mtl" file. Leave blank for a textureless object.                           |
 446 | Dali::Toolkit::MeshVisual::Property::TEXTURES_PATH    | texturesPath   | STRING             | If using material | Path to the directory the textures (including gloss and normal) are stored in.                   |
 447 | 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) |
 448 | Dali::Toolkit::MeshVisual::Property::USE_MIPMAPPING   | useMipmapping  | BOOLEAN            | No                | Flag for whether to use mipmaps for textures or not. Default true.                               |
 449 | 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.       |
 450 | Dali::Toolkit::MeshVisual::Property::LIGHT_POSITION   | lightPosition  | VECTOR3            | No                | The position, in stage space, of the point light that applies lighting to the model.             |
 451
 452 ### Shading Mode {#mesh-visual-shading-mode}
 453
 454 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.
 455
 456 **Possible values:**
 457
 458 | Enumeration                                                                     | String                                   | Description                                                                                                             |
 459 |---------------------------------------------------------------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
 460 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURELESS_WITH_DIFFUSE_LIGHTING        | TEXTURELESS_WITH_DIFFUSE_LIGHTING        | *Simplest*. One color that is lit by ambient and diffuse lighting.                                                      |
 461 | 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.        |
 462 | 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. |
 463
 464 ### Usage
 465
 466 ~~~{.cpp}
 467 // C++
 468 Dali::Stage stage = Dali::Stage::GetCurrent();
 469 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 470
 471 Dali::Property::Map map;
 472
 473 map[ Visual::Property::TYPE  ] = Dali::Toolkit::Visual::MESH;
 474 map[ MeshVisual::Property::OBJECT_URL ] = "home/models/Dino.obj";
 475 map[ MeshVisual::Property::MATERIAL_URL ] = "home/models/Dino.mtl";
 476 map[ MeshVisual::Property::TEXTURES_PATH ] = "home/images/";
 477
 478 control.SetProperty( Control::Property::BACKGROUND, map );
 479 ~~~
 480
 481 ___________________________________________________________________________________________________
 482
 483 ## Primitive Visual {#primitive-visual}
 484
 485 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
 486
 487 The shapes are generated with clockwise winding and back-face culling on by default.
 488
 489 ![ ](../assets/img/visuals/cube.png)
 490 ![ ](visuals/cube.png)
 491
 492 ### Properties Supported
 493
 494 **VisualType:** Dali::Toolkit::Visual::PRIMITIVE, "PRIMITIVE"
 495
 496 | Property                                                      | String            | Type               | Description                                                                                                     | Default Value                                           | Range                          |
 497 |---------------------------------------------------------------|-------------------|:------------------:|-----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------:|:------------------------------:|
 498 | 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) |
 499 | Dali::Toolkit::PrimitiveVisual::Property::COLOR               | shapeColor        | VECTOR4            | The color of the shape.                                                                                         | (0.5, 0.5, 0.5, 1.0)                                    | 0.0 - 1.0 for each             |
 500 | 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                        |
 501 | 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                        |
 502 | 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                          |
 503 | 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                          |
 504 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_HEIGHT        | scaleHeight       | FLOAT              | The scale of the height of a conic.                                                                             | 3.0                                                     | > 0.0                          |
 505 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_RADIUS        | scaleRadius       | FLOAT              | The scale of the radius of a cylinder.                                                                          | 1.0                                                     | > 0.0                          |
 506 | 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                 |
 507 | 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                      |
 508 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_SMOOTHNESS    | bevelSmoothness   | FLOAT              | Defines how smooth the bevelled edges should be.                                                                | 0.0 (sharp edges)                                       | 0.0 - 1.0                      |
 509 | 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                      |
 510
 511 ### Shapes {#shape-details}
 512
 513 There are six shapes that can be chosen, some of which are simplified specialisations of another.
 514
 515 | Enumeration                                             | String           | Description                                                                       | Parameters                                                    |
 516 |---------------------------------------------------------|------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
 517 | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE           | SPHERE           | *Default*.                                                                        | color, slices, stacks                                         |
 518 | 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 |
 519 | Dali::Toolkit::PrimitiveVisual::Shape::CONE             | CONE             | Equivalent to a conical frustrum with top radius of zero.                         | color, scaleBottomRadius, scaleHeight, slices                 |
 520 | Dali::Toolkit::PrimitiveVisual::Shape::CYLINDER         | CYLINDER         | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices                       |
 521 | Dali::Toolkit::PrimitiveVisual::Shape::CUBE             | CUBE             | Equivalent to a bevelled cube with a bevel percentage of zero.                    | color, scaleDimensions                                        |
 522 | Dali::Toolkit::PrimitiveVisual::Shape::OCTAHEDRON       | OCTAHEDRON       | Equivalent to a bevelled cube with a bevel percentage of one.                     | color, scaleDimensions                                        |
 523 | Dali::Toolkit::PrimitiveVisual::Shape::BEVELLED_CUBE    | BEVELLED_CUBE    | A cube/cuboid with all edges flattened to some degree.                            | color, scaleDimensions, bevelPercentage, bevelSmoothness      |
 524
 525 #### Examples below:
 526
 527 **sphere:**
 528
 529 ![ ](../assets/img/visuals/sphere.png)
 530 ![ ](visuals/sphere.png)
 531
 532 **conics:**
 533
 534 | Frustrum | Cone | Cylinder |
 535 |----------|------|----------|
 536 | ![ ](../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) |
 537
 538 ### Bevel {#bevel-details}
 539
 540 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:
 541
 542 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
 543 |-------------|-----|-----|------------------|
 544 | ![ ](../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) |
 545
 546 ### Slices {#slices-details}
 547
 548 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
 549
 550 ![ ](../assets/img/visuals/slices.png)
 551 ![ ](visuals/slices.png)
 552
 553 ### Stacks {#stacks-details}
 554
 555 For spheres, 'stacks' determines how many layers there are as you go down the object.
 556
 557 ![ ](../assets/img/visuals/stacks.png)
 558 ![ ](visuals/stacks.png)
 559
 560 ### Usage
 561
 562 **sphere**
 563
 564 ~~~{.cpp}
 565 // C++
 566 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 567
 568 Dali::Property::Map map;
 569
 570 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 571 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::SPHERE;
 572 map[ PrimitiveVisual::Property::COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 573
 574 control.SetProperty( Control::Property::BACKGROUND, map );
 575 ~~~
 576
 577 **conical frustrum**
 578
 579 ~~~{.cpp}
 580 // C++
 581 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 582
 583 Dali::Property::Map map;
 584
 585 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 586 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::CONICAL_FRUSTRUM;
 587 map[ PrimitiveVisual::Property::COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 588 map[ PrimitiveVisual::Property::SCALE_TOP_RADIUS ] = 1.0f;
 589 map[ PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS ] = 1.5f;
 590 map[ PrimitiveVisual::Property::SCALE_HEIGHT ] = 3.0f;
 591
 592 control.SetProperty( Control::Property::BACKGROUND, map );
 593 ~~~
 594
 595 **bevelled cube**
 596
 597 ~~~{.cpp}
 598 // C++
 599 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 600
 601 Dali::Property::Map map;
 602
 603 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 604 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::BEVELLED_CUBE;
 605 map[ PrimitiveVisual::Property::COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 606 map[ PrimitiveVisual::Property::BEVEL_PERCENTAGE ] = 0.4f;
 607
 608 control.SetProperty( Control::Property::BACKGROUND, map );
 609 ~~~
 610 ___________________________________________________________________________________________________
 611
 612 ## Wireframe Visual {#wireframe-visual}
 613
 614 Renders a wireframe around a control's quad.
 615 Is mainly used for debugging and is the visual that replaces all other visuals when [Visual Debug Rendering](@ref debugrendering) is turned on.
 616
 617 ![ ](../assets/img/visuals/wireframe-visual.png)
 618 ![ ](visuals/wireframe-visual.png)
 619
 620 ### Properties
 621
 622 **VisualType:** Dali::Toolkit::Visual::WIREFRAME, "WIREFRAME"
 623
 624 ### Usage
 625
 626 ~~~{.cpp}
 627 // C++
 628 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 629
 630 Dali::Property::Map map;
 631 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::WIREFRAME;
 632
 633 control.SetProperty( Control::Property::BACKGROUND, map );
 634 ~~~
 635
 636 ~~~{.js}
 637 // JavaScript
 638 var control = new dali.Control( "Control" );
 639
 640 control.background =
 641 {
 642   visualType : "WIREFRAME"
 643 };
 644 ~~~
 645
 646
 647 @class _Guide_Control_Visuals
 648
 649 */