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