docs/content/shared-javascript-and-cpp-documentation/control-renderers.md

   1 <!--
   2 /**-->
   3
   4 # Control Renderers  {#control-renderers}
   5
   6 Control Renderers provide reusable renderering 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 renderers which increases performance as well.
   8
   9 Control Renderers reuse geometry, shader 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.
  11
  12 DALi provides the following renderers:
  13  + [Color](@ref color-renderer)
  14  + [Gradient](@ref gradient-renderer)
  15  + [Image](@ref image-renderers)
  16  + [Border](@ref border-renderer)
  17  + [Mesh](@ref mesh-renderer)
  18  + [Primitive](@ref primitive-renderer)
  19
  20 Controls can provide properties that allow users to specify the renderer type.
  21 Setting renderer properties are done via a property map.
  22 The **rendererType** field in the property map specifies the renderer to use/create.
  23 This is required to avoid ambiguity as multiple renderers may be capable of rendering the same contents.
  24 ___________________________________________________________________________________________________
  25
  26 ## Color Renderer {#color-renderer}
  27
  28 Renders a solid color to the control's quad.
  29
  30 ![ ](../assets/img/renderers/color-renderer.png)
  31 ![ ](renderers/color-renderer.png)
  32
  33 ### Properties Supported
  34
  35 **RendererType:** "COLOR"
  36
  37 | Property Name | Type    | Required | Description               |
  38 |---------------|:-------:|:--------:|---------------------------|
  39 | 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[ "rendererType" ] = "COLOR";
  49 map[ "mixColor" ] = Color::RED;
  50
  51 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
  52 ~~~
  53
  54 ~~~{.js}
  55 // JavaScript
  56 var control = new dali.Control( "Control" );
  57
  58 control.background =
  59 {
  60   rendererType : "COLOR",
  61   mixColor : dali.COLOR_RED
  62 };
  63 ~~~
  64 ___________________________________________________________________________________________________
  65
  66 ## Gradient Renderer {#gradient-renderer}
  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/renderers/linear-gradient-renderer.png) ![ ](renderers/linear-gradient-renderer.png) | ![ ](../assets/img/renderers/radial-gradient-renderer.png) ![ ](renderers/radial-gradient-renderer.png) |
  75
  76 ### Properties Supported
  77
  78 **RendererType:** "GRADIENT"
  79
  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-renderer-units)                | STRING           | No         | *OBJECT_BOUNDING_BOX* or *USER_SPACE*. Default: *OBJECT_BOUNDING_BOX*.   |
  89 | [spreadMethod](@ref gradient-renderer-spread-method) | STRING           | No         | *PAD*, *REFLECT* or *REPEAT*. Default: *PAD*.                            |
  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-renderer-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 | 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). |
 103
 104 ### Spread Method {#gradient-renderer-spread-method}
 105
 106 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
 107
 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.  |
 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[ "rendererType" ] = "GRADIENT";
 123 map[ "startPosition" ] = Vector2( 0.5f, 0.5f );
 124 map[ "endPosition" ] = 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[ "stopOffset" ] = 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[ "stopColor" ] = stopColors;
 141
 142 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 143 ~~~
 144
 145 ~~~{.js}
 146 // JavaScript
 147 var control = new dali.Control( "Control" );
 148
 149 control.background =
 150 {
 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 ],
 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[ "rendererType" ] = "GRADIENT";
 172 map[ "center" ] = Vector2( 0.5f, 0.5f );
 173 map[ "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[ "stopOffset" ] = 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[ "stopColor" ] = stopColors;
 190
 191 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 192 ~~~
 193
 194 ~~~{.js}
 195 // JavaScript
 196 var control = new dali.Control( "Control" );
 197
 198 control.background =
 199 {
 200   rendererType : "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 Renderers {#image-renderers}
 216
 217 Renders an image into the control's quad.
 218
 219 Depending on the extension of the image, different renderer is provided to render the image onto the screen.
 220
 221  + [Normal](@ref image-renderer)
 222  + [N-Patch](@ref n-patch-renderer)
 223  + [SVG](@ref svg-renderer)
 224
 225 ___________________________
 226
 227 ### Normal {#image-renderer}
 228
 229 Renders a raster image ( jpg, png etc.) into the control's quad.
 230
 231 ![ ](../assets/img/renderers/image-renderer.png)
 232 ![ ](renderers/image-renderer.png)
 233
 234 #### Properties Supported
 235
 236 **RendererType:** "IMAGE"
 237
 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.                                       |
 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[ "rendererType" ] = "IMAGE";
 254 map[ "url" ] = "path-to-image.jpg";
 255
 256 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 257 ~~~
 258
 259 ~~~{.js}
 260 // JavaScript
 261 var control = new dali.Control( "Control" );
 262
 263 control.background =
 264 {
 265   rendererType : "IMAGE",
 266   url : "path-to-image.jpg"
 267 };
 268 ~~~
 269 ___________________________________________________________________________________________________
 270
 271 ### N-Patch {#n-patch-renderer}
 272
 273 Renders an n-patch or a 9-patch image into the control's quad.
 274
 275 ![ ](../assets/img/renderers/n-patch-renderer.png)
 276 ![ ](renderers/n-patch-renderer.png)
 277
 278 #### Properties Supported
 279
 280 **RendererType:** "IMAGE"
 281
 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. |
 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[ "rendererType" ] = "IMAGE";
 296 map[ "url" ] = "path-to-image.9.png";
 297
 298 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 299 ~~~
 300
 301 ~~~{.js}
 302 // JavaScript
 303 var control = new dali.Control( "Control" );
 304
 305 control.background =
 306 {
 307   rendererType : "IMAGE",
 308   url : "path-to-image.9.png"
 309 };
 310 ~~~
 311
 312 ___________________________________________________________________________________________________
 313
 314 ### SVG {#svg-renderer}
 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/renderers/svg-renderer.svg)
 339
 340 </div>
 341
 342 <div style="width:300px">
 343
 344 ![ ](renderers/svg-renderer.svg)
 345
 346 </div>
 347
 348
 349 #### Properties Supported
 350
 351 **RendererType:** "IMAGE"
 352
 353 | Property Name | Type    | Required | Description                      |
 354 |---------------|:-------:|:--------:|----------------------------------|
 355 | 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[ "rendererType" ] = "IMAGE";
 366 map[ "url" ] = "path-to-image.svg";
 367
 368 control.SetSize( 200.f, 200.f );
 369 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 370 ~~~
 371
 372 ~~~{.js}
 373 // JavaScript
 374 var control = new dali.Control( "Control" );
 375
 376 control.background =
 377 {
 378   rendererType : "IMAGE",
 379   url : "path-to-image.svg"
 380 };
 381 ~~~
 382 ___________________________________________________________________________________________________
 383
 384 ## Border Renderer {#border-renderer}
 385
 386 Renders a solid color as an internal border to the control's quad.
 387
 388 ![ ](../assets/img/renderers/border-renderer.png)
 389 ![ ](renderers/border-renderer.png)
 390
 391 ### Properties Supported
 392
 393 **RendererType:** "BORDER"
 394
 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. |
 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[ "rendererType" ] = "BORDER";
 410 map[ "borderColor"  ] = Color::BLUE;
 411 map[ "borderSize"   ] = 5.0f;
 412
 413 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 414 ~~~
 415
 416 ~~~{.js}
 417 // JavaScript
 418 var control = new dali.Control( "Control" );
 419
 420 control.background =
 421 {
 422   rendererType : "BORDER",
 423   borderColor : dali.COLOR_BLUE,
 424   borderSize = 5
 425 };
 426 ~~~
 427
 428 ___________________________________________________________________________________________________
 429
 430 ## Mesh Renderer {#mesh-renderer}
 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/renderers/mesh-renderer.png)
 435 ![ ](renderers/mesh-renderer.png)
 436
 437 ### Properties Supported
 438
 439 **RendererType** "MESH"
 440
 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-renderer-shader-type) | STRING  | No                 | Sets the type of shader to be used with the mesh.                              |
 447
 448 ### Shader Type {#mesh-renderer-shader-type}
 449
 450 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.
 451
 452 **Possible values:**
 453
 454 | String Value    | Description                                    |
 455 |-----------------|------------------------------------------------|
 456 | TEXTURELESS     | *Simplest*. A flat color with shading is used. |
 457 | DIFFUSE_TEXTURE | Textured.                                      |
 458 | ALL_TEXTURES    | Has a gloss, normal map and texture map.       |
 459
 460 ### Usage
 461
 462 ~~~{.cpp}
 463 // C++
 464 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 465
 466 Dali::Property::Map map;
 467
 468 map[ "rendererType" ] = "MESH";
 469 map[ "objectUrl"    ] = "home/models/Dino.obj";
 470 map[ "materialUrl"  ] = "home/models/Dino.mtl";
 471 map[ "texturesPath" ] = "home/images/";
 472
 473 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 474 ~~~
 475
 476 ___________________________________________________________________________________________________
 477
 478 ## Primitive Renderer {#primitive-renderer}
 479
 480 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
 481
 482 ![ ](../assets/img/renderers/cube.png)
 483 ![ ](renderers/cube.png)
 484
 485 ### Properties Supported
 486
 487 **RendererType** "PRIMITIVE"
 488
 489 | Property Name                         | Type    | Description                                                                     | Default Value        | Range                          |
 490 |---------------------------------------|:-------:|---------------------------------------------------------------------------------|:--------------------:|:------------------------------:|
 491 | [shape](@ref shape-details)           | STRING  | The specific shape to render.                                                   | "SPHERE"             | [See list](@ref shape-details) |
 492 | color                                 | VECTOR4 | The color of the shape.                                                         | (0.5, 0.5, 0.5, 1.0) | 0.0 - 1.0 for each             |
 493 | [slices](@ref slices-details)         | INT     | The number of slices as you go around the shape.                                | 128                  | 1 - 255                        |
 494 | [stacks](@ref stacks-details)         | INT     | The number of stacks as you go down the shape.                                  | 128                  | 1 - 255                        |
 495 | scaleTopRadius                        | FLOAT   | The scale of the radius of the top circle of a conical frustrum.                | 1.0                  | ≥ 0.0                          |
 496 | scaleBottomRadius                     | FLOAT   | The scale of the radius of the bottom circle of a conical frustrum.             | 1.5                  | ≥ 0.0                          |
 497 | scaleHeight                           | FLOAT   | The scale of the height of a conic.                                             | 3.0                  | > 0.0                          |
 498 | scaleRadius                           | FLOAT   | The scale of the radius of a cylinder.                                          | 1.0                  | > 0.0                          |
 499 | 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                 |
 500 | [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                      |
 501 | bevelSmoothness                       | FLOAT   | Defines how smooth the bevelled edges should be.                                | 0.0 (sharp edges)    | 0.0 - 1.0                      |
 502 | uLightPosition                        | 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 upper left back corner. 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 |
 503
 504 ### Shapes {#shape-details}
 505
 506 There are six shapes that can be chosen, some of which are simplified specialisations of another.
 507
 508 | Value            | Description                                                                       | Parameters                                                    |
 509 |------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
 510 | SPHERE           | *Default*.                                                                        | color, slices, stacks                                         |
 511 | CONICAL_FRUSTRUM | The area bound between two circles, i.e. a cone with the tip removed.             | color, scaleTopRadius, scaleBottomRadius, scaleHeight, slices |
 512 | CONE             | Equivalent to a conical frustrum with top radius of zero.                         | color, scaleBottomRadius, scaleHeight, slices                 |
 513 | CYLINDER         | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices                       |
 514 | CUBE             | Equivalent to a bevelled cube with a bevel percentage of zero.                    | color, scaleDimensions                                        |
 515 | OCTAHEDRON       | Equivalent to a bevelled cube with a bevel percentage of one.                     | color, scaleDimensions                                        |
 516 | BEVELLED_CUBE    | A cube/cuboid with all edges flattened to some degree.                            | color, scaleDimensions, bevelPercentage, bevelSmoothness      |
 517
 518 Examples below:
 519
 520 **sphere:**
 521
 522 ![ ](../assets/img/renderers/sphere.png)
 523 ![ ](renderers/sphere.png)
 524
 525 **conics:**
 526
 527 | Frustrum | Cone | Cylinder |
 528 |----------|------|----------|
 529 | ![ ](../assets/img/renderers/conical-frustrum.png) ![ ](renderers/conical-frustrum.png) | ![ ](../assets/img/renderers/cone.png) ![ ](renderers/cone.png) | ![ ](../assets/img/renderers/cylinder.png) ![ ](renderers/cylinder.png) |
 530
 531 ### Bevel {#bevel-details}
 532
 533 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:
 534
 535 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
 536 |-------------|-----|-----|------------------|
 537 | ![ ](../assets/img/renderers/cube.png) ![ ](renderers/cube.png) | ![ ](../assets/img/renderers/bevelled-cube-low.png) ![ ](renderers/bevelled-cube-low.png) | ![ ](../assets/img/renderers/bevelled-cube-high.png) ![ ](renderers/bevelled-cube-high.png) | ![ ](../assets/img/renderers/octahedron.png) ![ ](renderers/octahedron.png) |
 538
 539 ### Slices {#slices-details}
 540
 541 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
 542
 543 ![ ](../assets/img/renderers/slices.png)
 544 ![ ](renderers/slices.png)
 545
 546 ### Stacks {#stacks-details}
 547
 548 For spheres, 'stacks' determines how many layers there are as you go down the object.
 549
 550 ![ ](../assets/img/renderers/stacks.png)
 551 ![ ](renderers/stacks.png)
 552
 553 ### Usage
 554
 555 **sphere**
 556
 557 ~~~{.cpp}
 558 // C++
 559 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 560
 561 Dali::Property::Map map;
 562
 563 map[ "rendererType" ] = "PRIMITIVE";
 564 map[ "shape"        ] = "SPHERE";
 565 map[ "color"        ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 566
 567 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 568 ~~~
 569
 570 **conical frustrum**
 571
 572 ~~~{.cpp}
 573 // C++
 574 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 575
 576 Dali::Property::Map map;
 577
 578 map[ "rendererType"      ] = "PRIMITIVE";
 579 map[ "shape"             ] = "CONICAL_FRUSTRUM";
 580 map[ "color"             ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 581 map[ "scaleTopRadius"    ] = 1.0f;
 582 map[ "scaleBottomRadius" ] = 1.5f;
 583 map[ "scaleHeight"       ] = 3.0f;
 584
 585 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 586 ~~~
 587
 588 **bevelled cube**
 589
 590 ~~~{.cpp}
 591 // C++
 592 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 593
 594 Dali::Property::Map map;
 595
 596 map[ "rendererType"    ] = "PRIMITIVE";
 597 map[ "shape"           ] = "BEVELLED_CUBE";
 598 map[ "color"           ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 599 map[ "bevelPercentage" ] = 0.4f;
 600
 601 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 602 ~~~
 603
 604 @class _Guide_Control_Renderers
 605
 606 */