docs/content/programming-guide/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 texture to exist only when the control is on-stage.
  10 Additionally, they respond to actor size and color change, while also providing clipping at the renderer level.
  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  + [Text](@ref text-visual)
  20  + [Wireframe](@ref wireframe-visual)
  21
  22 Controls can provide properties that allow users to specify the visual type ( visualType ).
  23 Setting visual properties are done via a property map.
  24 The **visualType** field in the property map specifies the visual to use/create.
  25 This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents.
  26
  27 Visuals have a **transform** field in the property map to allow layouting within a control. If this field is not set, then the visual defaults to filling the control. The **transform** field has a property map with the following keys:
  28
  29 | Property                                                       | String       | Type              | Required | Description                                                                                 |
  30 |----------------------------------------------------------------|--------------|:-----------------:|:--------:|---------------------------------------------------------------------------------------------|
  31 | Dali::Toolkit::Visual::Transform::Property::OFFSET        | offset       | VECTOR2           | No       | The offset of the visual.                                                                   |
  32 | Dali::Toolkit::Visual::Transform::Property::SIZE          | size         | VECTOR2           | No       | The size of the visual.                                                                     |
  33 | Dali::Toolkit::Visual::Transform::Property::OFFSET_POLICY | offsetPolicy | VECTOR4           | No       | Whether the offset components are Relative or Absolute [More info](@ref offset-size-policy) |
  34 | Dali::Toolkit::Visual::Transform::Property::SIZE_POLICY   | sizePolicy   | VECTOR4           | No       | Whether the size components are Relative or Absolute [More info](@ref offset-size-policy)   |
  35 | Dali::Toolkit::Visual::Transform::Property::ORIGIN        | origin       | INTEGER or STRING | No       | The origin of the visual within the control's area. [More info](@ref align-type)            |
  36 | Dali::Toolkit::Visual::Transform::Property::ANCHOR_POINT  | anchorPoint  | INTEGER or STRING | No       | The anchor point of the visual. [More info](@ref align-type)                                |
  37
  38
  39 ## Offset & Size Policy  {#offset-size-policy}
  40
  41 The offset and size policies can be either Relative or Absolute.
  42
  43 | Enumeration                                             | String   | Description                                                                   |
  44 |---------------------------------------------------------|----------|-------------------------------------------------------------------------------|
  45 | Dali::Toolkit::Visual::Transform::Policy::RELATIVE | RELATIVE | *Default*. The size or offset value represents a ratio of the control's size  |
  46 | Dali::Toolkit::Visual::Transform::Policy::ABSOLUTE | ABSOLUTE | The size or offset value represents world units (pixels)                      |
  47
  48 For example, an offsetPolicy of [ RELATIVE, RELATIVE ], a sizePolicy of [ ABSOLUTE, ABSOLUTE ], an offset of ( 0, 0.25 ) and a size of ( 20, 20 ) means the visual will be 20 pixels by 20 pixels in size, positioned 25% above the center of the control.
  49
  50 ## Alignment  {#align-type}
  51 | Enumeration                                          | String  | Description                                                                                          |
  52 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
  53 | Dali::Toolkit::Align::TOP_BEGIN | TOP_BEGIN | Aligns to the top of the vertical axis and the beginning of the horizontal axis (The left or right edge in Left-To-Right or Right-to-Left layouts, respectively) |
  54 | Dali::Toolkit::Align::TOP_CENTER | TOP_CENTER | Aligns to the top of the vertical axis and the center of the horizontal axis |
  55 | Dali::Toolkit::Align::TOP_END | TOP_END | Aligns to the top of the vertical axis and end of the horizontal axis (The right or left edge in Left-To-Right or Right-to-Left layouts, respectively) |
  56 | Dali::Toolkit::Align::CENTER_BEGIN | CENTER_BEGIN | Aligns to the center of the vertical axis and the beginning of the horizontal axis|
  57 | Dali::Toolkit::Align::CENTER | CENTER | Aligns to the center of the control |
  58 | Dali::Toolkit::Align::CENTER_END | CENTER_END | Aligns to the center of the vertical axis and end of the horizontal axis |
  59 | Dali::Toolkit::Align::BOTTOM_BEGIN | BOTTOM_BEGIN | Aligns to the bottom of the vertical axis and the beginning of the horizontal axis|
  60 | Dali::Toolkit::Align::BOTTOM_CENTER | BOTTOM_CENTER | Aligns to the bottom of the vertical axis and the center of the horizontal axis
  61 | Dali::Toolkit::Align::BOTTOM_END | BOTTOM_END | Aligns to the bottom of the vertical axis and end of the horizontal axis |
  62
  63 Visuals also have a custom **shader** property. Whilst it's possible to change the shader, please note that some visuals rely on the vertex shader to perform certain functions. For example, the NPatch visual uses the vertex shader to perform the stretching. The **shader** property is a Property::Map with the following keys:
  64
  65
  66 | Property                                                  | String         | Type                       | Required | Description                                                                                |
  67 |-----------------------------------------------------------|----------------|:--------------------------:|:--------:|--------------------------------------------------------------------------------------------|
  68 | Dali::Toolkit::Visual::Shader::Property::VERTEX_SHADER    | vertexShader   | STRING or ARRAY of STRING  | No       | The vertex shader code. Can use an array of strings to split shader over multiple lines.   |
  69 | Dali::Toolkit::Visual::Shader::Property::FRAGMENT_SHADER  | fragmentShader | STRING or ARRAY of STRING  | No       | The fragment shader code. Can use an array of strings to split shader over multiple lines. |
  70 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_X | subdivideGridX | INTEGER                    | No       | How to subdivide the grid along the X-Axis. Defaults to 1.                                 |
  71 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_Y | subdivideGridY | INTEGER                    | No       | How to subdivide the grid along the Y-Axis. Defaults to 1.                                 |
  72 | Dali::Toolkit::Visual::Shader::Property::HINTS            | hints          | INTEGER or ARRAY of STRING | No       | Shader hints bitmask [More info](@ref shader-hints)                                        |
  73
  74 ## Shader hints {#shader-hints}
  75
  76 This is a bitmask giving hints to the renderer about what the shader does, in order to help the rendering system optimise it's rendering.
  77
  78 The bitmask can have the following values:
  79
  80 | Value | Description |
  81 |-------------------------------------------|----------------------------------------|
  82 | Dali::Shader::Hint::NONE | No hints |
  83 | Dali::Shader::Hint::OUTPUT_IS_TRANSPARENT | Might generate transparent alpha from opaque inputs |
  84 | Dali::Shader::Hint::MODIFIES_GEOMETRY | Might change the position of vertices - this disables culling optimizations |
  85
  86
  87 See also Dali::Shader::Hint::Value enumeration.
  88
  89 ___________________________________________________________________________________________________
  90
  91 ## Color Visual {#color-visual}
  92
  93 Renders a color to the visual's quad geometry.
  94
  95 ![ ](visuals/color-visual.png)
  96
  97 ### Properties Supported
  98
  99 **VisualType:** Dali::Toolkit::Visual::COLOR, "COLOR"
 100
 101 | Property                                        | String   | Type    | Required | Description               |
 102 |-------------------------------------------------|----------|:-------:|:--------:|---------------------------|
 103 | Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes      | The color required. |
 104
 105 ### Usage
 106
 107 ~~~{.cpp}
 108 // C++
 109 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 110
 111 Dali::Property::Map map;
 112 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::COLOR;
 113 map[ ColorVisual::Property::MIX_COLOR ] = Color::RED;
 114
 115 control.SetProperty( Control::Property::BACKGROUND, map );
 116 ~~~
 117 ___________________________________________________________________________________________________
 118
 119 ## Gradient Visual {#gradient-visual}
 120
 121 Renders a smooth transition of colors to the visual's quad geometry.
 122
 123 Both Linear and Radial gradients are supported.
 124
 125 | Linear | Radial |
 126 |--------|--------|
 127 | ![ ](visuals/linear-gradient-visual.png) | ![ ](visuals/radial-gradient-visual.png) |
 128
 129 ### Properties Supported
 130
 131 **VisualType:** Dali::Toolkit::Visual::GRADIENT, "GRADIENT"
 132
 133 | Property                                                | String        | Type              | Required   | Description                                                                                                      |
 134 |---------------------------------------------------------|---------------|:-----------------:|:----------:|------------------------------------------------------------------------------------------------------------------|
 135 | Dali::Toolkit::GradientVisual::Property::START_POSITION | startPosition | VECTOR2           | For Linear | The start position of the linear gradient.                                                                       |
 136 | Dali::Toolkit::GradientVisual::Property::END_POSITION   | endPosition   | VECTOR2           | For Linear | The end position of the linear gradient.                                                                         |
 137 | Dali::Toolkit::GradientVisual::Property::CENTER         | center        | VECTOR2           | For Radial | The center point of the gradient.                                                                                |
 138 | Dali::Toolkit::GradientVisual::Property::RADIUS         | radius        | FLOAT             | For Radial | The size of the radius.                                                                                          |
 139 | 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.                                                    |
 140 | 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.                                         |
 141 | Dali::Toolkit::GradientVisual::Property::UNITS          | units         | INTEGER or STRING | No         | Defines the coordinate system. [More info](@ref gradient-visual-units)                                           |
 142 | 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) |
 143
 144 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.
 145
 146 ### Units {#gradient-visual-units}
 147
 148 Defines the coordinate system for the attributes:
 149  + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
 150  + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
 151
 152 | Enumeration                                               | String              | Description                                                                                                                                    |
 153 |-----------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
 154 | 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).                  |
 155 | 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). |
 156
 157 ### Spread Method {#gradient-visual-spread-method}
 158
 159 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
 160
 161 | Enumeration                                          | String  | Description                                                                                          |
 162 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
 163 | Dali::Toolkit::GradientVisual::SpreadMethod::PAD     | PAD     | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad geometry.               |
 164 | Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad geometry is filled. |
 165 | Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT  | REPEAT  | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad geometry is filled.  |
 166
 167 ### Usage
 168
 169 **Linear:**
 170 ~~~{.cpp}
 171 // C++
 172 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 173
 174 Dali::Property::Map map;
 175 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
 176 map[ GradientVisual::Property::START_POSITION ] = Vector2( 0.5f, 0.5f );
 177 map[ GradientVisual::Property::END_POSITION ] = Vector2( -0.5f, -0.5f );
 178
 179 Dali::Property::Array stopOffsets;
 180 stopOffsets.PushBack( 0.0f );
 181 stopOffsets.PushBack( 0.3f );
 182 stopOffsets.PushBack( 0.6f );
 183 stopOffsets.PushBack( 0.8f );
 184 stopOffsets.PushBack( 1.f );
 185 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
 186
 187 Dali::Property::Array stopColors;
 188 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 189 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 190 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 191 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 192 stopColors.PushBack( Color::YELLOW );
 193 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
 194
 195 control.SetProperty( Control::Property::BACKGROUND, map );
 196 ~~~
 197
 198 **Radial:**
 199 ~~~{.cpp}
 200 // C++
 201 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 202
 203 Dali::Property::Map map;
 204 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
 205 map[ GradientVisual::Property::CENTER ] = Vector2( 0.5f, 0.5f );
 206 map[ GradientVisual::Property::RADIUS ] = 1.414f;
 207
 208 Dali::Property::Array stopOffsets;
 209 stopOffsets.PushBack( 0.0f );
 210 stopOffsets.PushBack( 0.3f );
 211 stopOffsets.PushBack( 0.6f );
 212 stopOffsets.PushBack( 0.8f );
 213 stopOffsets.PushBack( 1.f );
 214 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
 215
 216 Dali::Property::Array stopColors;
 217 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 218 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 219 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 220 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 221 stopColors.PushBack( Color::YELLOW );
 222 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
 223
 224 control.SetProperty( Control::Property::BACKGROUND, map );
 225 ~~~
 226 ___________________________________________________________________________________________________
 227
 228 ## Image Visual {#image-visuals}
 229
 230 Renders an image into the visual's geometry.
 231
 232 Depending on the extension of the image, a different visual is provided to render the image onto the screen.
 233
 234  + [Normal (Quad)](@ref image-visual)
 235  + [N-Patch](@ref n-patch-visual)
 236  + [SVG](@ref svg-visual)
 237  + [Animated Image]( @ref animated-image-visual )
 238
 239 ___________________________
 240
 241 ### Normal {#image-visual}
 242
 243 Renders a raster image ( jpg, png etc.) into the visual's quad geometry.
 244
 245 ![ ](visuals/image-visual.png)
 246
 247 #### Properties Supported
 248
 249 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 250
 251 | Property                                             | String        | Type              | Required | Description                                                                                                              |
 252 |------------------------------------------------------|---------------|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------|
 253 | Dali::Toolkit::ImageVisual::Property::URL            | url           | STRING            | Yes      | The URL of the image.                                                                                                    |
 254 | 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) |
 255 | 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)   |
 256 | Dali::Toolkit::ImageVisual::Property::DESIRED_WIDTH  | desiredWidth  | INT               | No       | The desired image width. Will use actual image width if not specified.                                                   |
 257 | Dali::Toolkit::ImageVisual::Property::DESIRED_HEIGHT | desiredHeight | INT               | No       | The desired image height. Will use actual image height if not specified.                                                 |
 258 | Dali::Toolkit::ImageVisual::Property::PIXEL_AREA     | pixelArea     | VECTOR4           | No       | The image area to be displayed, default value is [0.0, 0.0, 1.0, 1.0]                                                    |
 259 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_U    | wrapModeU     | INTEGER or STRING | No       | Wrap mode for u coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT                               |
 260 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_V    | wrapModeV     | INTEGER or STRING | No       | Wrap mode for v coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT                               |
 261
 262 #### Usage
 263
 264 ~~~{.cpp}
 265 // C++
 266 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 267
 268 Dali::Property::Map map;
 269 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 270 map[ ImageVisual::Property::URL ] = "path-to-image.jpg";
 271
 272 control.SetProperty( Control::Property::BACKGROUND, map );
 273 ~~~
 274 ___________________________________________________________________________________________________
 275
 276 ### N-Patch {#n-patch-visual}
 277
 278 Renders an n-patch or a 9-patch image. Uses non-quad geometry. Both geometry and texture are cached to reduce memory consumption if the same n-patch image is used elsewhere.
 279
 280 ![ ](visuals/n-patch-visual.png)
 281
 282 #### Properties Supported
 283
 284 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 285
 286 | Property                                          | String        | Type    | Required | Description                      |
 287 |---------------------------------------------------|---------------|:-------:|:--------:|----------------------------------|
 288 | Dali::Toolkit::ImageVisual::Property::URL         | url           | STRING  | Yes      | The URL of the n-patch image.    |
 289 | Dali::Toolkit::ImageVisual::Property::BORDER_ONLY | borderOnly    | BOOLEAN | No       | If true, only draws the borders. |
 290
 291 #### Usage
 292
 293 ~~~{.cpp}
 294 // C++
 295 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 296
 297 Dali::Property::Map map;
 298
 299 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 300 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.9.png";
 301
 302 control.SetProperty( Control::Property::BACKGROUND, map );
 303 ~~~
 304 ___________________________________________________________________________________________________
 305
 306 ### SVG {#svg-visual}
 307
 308 Renders a svg image into the visual's quad geometry.
 309
 310 #### Features: SVG Tiny 1.2 specification
 311
 312 **supported:**
 313
 314   * basic shapes
 315   * paths
 316   * solid color fill
 317   * gradient color fill
 318   * solid color stroke
 319
 320 **not supported:**
 321
 322   * gradient color stroke
 323   * dash array stroke
 324   * view box
 325   * text
 326   * clip path
 327
 328 <div style="width:300px">
 329
 330
 331 </div>
 332
 333 <div style="width:300px">
 334
 335 ![ ](visuals/svg-visual.svg)
 336
 337 </div>
 338
 339
 340 #### Properties Supported
 341
 342 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 343
 344 | Property                                  | String | Type    | Required | Description                      |
 345 |-------------------------------------------|--------|:-------:|:--------:|----------------------------------|
 346 | Dali::Toolkit::ImageVisual::Property::URL | url    | STRING  | Yes      | The URL of the SVG image.    |
 347
 348 #### Usage
 349
 350 ~~~{.cpp}
 351 // C++
 352 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 353
 354 Dali::Property::Map map;
 355
 356 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
 357 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.svg";
 358
 359 control.SetSize( 200.f, 200.f );
 360 control.SetProperty( Control::Property::BACKGROUND, map );
 361 ~~~
 362 ___________________________________________________________________________________________________
 363
 364 ## Animated Image Visual {#animated-image-visual}
 365
 366 Renders an animated image into the visual's quad geometry. Currently, only the GIF format is supported.
 367
 368 ![ ](animated-image-visual.gif)
 369
 370 #### Properties Supported
 371
 372 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
 373
 374 | Property                                          | String     | Type              | Required | Description                                                                                  |
 375 |---------------------------------------------------|------------|:-----------------:|:--------:|----------------------------------------------------------------------------------------------|
 376 | Dali::Toolkit::ImageVisual::Property::URL         | url        | STRING            | Yes      | The URL of the animated image.                                                               |
 377 | Dali::Toolkit::ImageVisual::Property::PIXEL_AREA  | pixelArea  | VECTOR4           | No       | The image area to be displayed, default value is [0.0, 0.0, 1.0, 1.0]                        |
 378 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_U | wrapModeU  | INTEGER or STRING | No       | Wrap mode for u coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT |
 379 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_V | wrapModeV  | INTEGER or STRING | No       | Wrap mode for v coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT |
 380
 381 #### Usage
 382
 383 ~~~{.cpp}
 384 // C++
 385 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 386
 387 control.SetProperty( Control::Property::BACKGROUND,
 388                      Property::Map().Add( Visual::Property::TYPE, Dali::Toolkit::Visual::IMAGE )
 389                                     .Add( Dali::Toolkit::ImageVisual::Property::URL, "path-to-image.gif" ) );
 390 ~~~
 391 ___________________________________________________________________________________________________
 392
 393 ## Border Visual {#border-visual}
 394
 395 Renders a color as an internal border to the visual's geometry.
 396
 397 ![ ](visuals/border-visual.png)
 398
 399 ### Properties Supported
 400
 401 **VisualType:** Dali::Toolkit::Visual::BORDER, "BORDER"
 402
 403 | Property                                             | String        | Type    | Required | Description                                      |
 404 |------------------------------------------------------|---------------|:-------:|:--------:|--------------------------------------------------|
 405 | Dali::Toolkit::BorderVisual::Property::COLOR         | borderColor   | VECTOR4 | Yes      | The color of the border.                         |
 406 | Dali::Toolkit::BorderVisual::Property::SIZE          | borderSize    | FLOAT   | Yes      | The width of the border (in pixels).             |
 407 | Dali::Toolkit::BorderVisual::Property::ANTI_ALIASING | antiAliasing  | BOOLEAN | No       | Whether anti-aliasing of the border is required. |
 408
 409 ### Usage
 410
 411 ~~~{.cpp}
 412 // C++
 413 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 414
 415 Dali::Property::Map map;
 416
 417 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::BORDER;
 418 map[ BorderVisual::Property::COLOR ] = Color::BLUE;
 419 map[ BorderVisual::Property::SIZE ] = 5.0f;
 420
 421 control.SetProperty( Control::Property::BACKGROUND, map );
 422 ~~~
 423 ___________________________________________________________________________________________________
 424
 425 ## Mesh Visual {#mesh-visual}
 426
 427 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
 428
 429 ![ ](visuals/mesh-visual.png)
 430
 431 ### Properties Supported
 432
 433 **VisualType:** Dali::Toolkit::Visual::MESH, "MESH"
 434
 435 | Property                                              | String         | Type               | Required          | Description                                                                                      |
 436 |-------------------------------------------------------|----------------|:------------------:|:-----------------:|--------------------------------------------------------------------------------------------------|
 437 | Dali::Toolkit::MeshVisual::Property::OBJECT_URL       | objectUrl      | STRING             | Yes               | The location of the ".obj" file.                                                                 |
 438 | Dali::Toolkit::MeshVisual::Property::MATERIAL_URL     | materialUrl    | STRING             | No                | The location of the ".mtl" file. Leave blank for a textureless object.                           |
 439 | Dali::Toolkit::MeshVisual::Property::TEXTURES_PATH    | texturesPath   | STRING             | If using material | Path to the directory the textures (including gloss and normal) are stored in.                   |
 440 | 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) |
 441 | Dali::Toolkit::MeshVisual::Property::USE_MIPMAPPING   | useMipmapping  | BOOLEAN            | No                | Flag for whether to use mipmaps for textures or not. Default true.                               |
 442 | 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.       |
 443 | Dali::Toolkit::MeshVisual::Property::LIGHT_POSITION   | lightPosition  | VECTOR3            | No                | The position, in stage space, of the point light that applies lighting to the model.             |
 444
 445 ### Shading Mode {#mesh-visual-shading-mode}
 446
 447 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.
 448
 449 **Possible values:**
 450
 451 | Enumeration                                                                     | String                                   | Description                                                                                                             |
 452 |---------------------------------------------------------------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
 453 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURELESS_WITH_DIFFUSE_LIGHTING        | TEXTURELESS_WITH_DIFFUSE_LIGHTING        | *Simplest*. One color that is lit by ambient and diffuse lighting.                                                      |
 454 | 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.        |
 455 | 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. |
 456
 457 ### Usage
 458
 459 ~~~{.cpp}
 460 // C++
 461 Dali::Stage stage = Dali::Stage::GetCurrent();
 462 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 463
 464 Dali::Property::Map map;
 465
 466 map[ Visual::Property::TYPE  ] = Dali::Toolkit::Visual::MESH;
 467 map[ MeshVisual::Property::OBJECT_URL ] = "home/models/Dino.obj";
 468 map[ MeshVisual::Property::MATERIAL_URL ] = "home/models/Dino.mtl";
 469 map[ MeshVisual::Property::TEXTURES_PATH ] = "home/images/";
 470
 471 control.SetProperty( Control::Property::BACKGROUND, map );
 472 ~~~
 473
 474 ___________________________________________________________________________________________________
 475
 476 ## Primitive Visual {#primitive-visual}
 477
 478 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
 479
 480 The shapes are generated with clockwise winding and back-face culling on by default.
 481
 482 ![ ](visuals/cube.png)
 483
 484 ### Properties Supported
 485
 486 **VisualType:** Dali::Toolkit::Visual::PRIMITIVE, "PRIMITIVE"
 487
 488 | Property                                                      | String            | Type               | Description                                                                                                     | Default Value                                           | Range                          |
 489 |---------------------------------------------------------------|-------------------|:------------------:|-----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------:|:------------------------------:|
 490 | 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) |
 491 | Dali::Toolkit::PrimitiveVisual::Property::MIX_COLOR           | mixColor          | VECTOR4            | The color of the shape.                                                                                         | (0.5, 0.5, 0.5, 1.0)                                    | 0.0 - 1.0 for each             |
 492 | 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                        |
 493 | 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                        |
 494 | 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                          |
 495 | 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                          |
 496 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_HEIGHT        | scaleHeight       | FLOAT              | The scale of the height of a conic.                                                                             | 3.0                                                     | > 0.0                          |
 497 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_RADIUS        | scaleRadius       | FLOAT              | The scale of the radius of a cylinder.                                                                          | 1.0                                                     | > 0.0                          |
 498 | 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                 |
 499 | 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                      |
 500 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_SMOOTHNESS    | bevelSmoothness   | FLOAT              | Defines how smooth the bevelled edges should be.                                                                | 0.0 (sharp edges)                                       | 0.0 - 1.0                      |
 501 | 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                      |
 502
 503 ### Shapes {#shape-details}
 504
 505 There are six shapes that can be chosen, some of which are simplified specialisations of another.
 506
 507 | Enumeration                                             | String           | Description                                                                       | Parameters                                                    |
 508 |---------------------------------------------------------|------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
 509 | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE           | SPHERE           | *Default*.                                                                        | color, slices, stacks                                         |
 510 | 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 |
 511 | Dali::Toolkit::PrimitiveVisual::Shape::CONE             | CONE             | Equivalent to a conical frustrum with top radius of zero.                         | color, scaleBottomRadius, scaleHeight, slices                 |
 512 | Dali::Toolkit::PrimitiveVisual::Shape::CYLINDER         | CYLINDER         | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices                       |
 513 | Dali::Toolkit::PrimitiveVisual::Shape::CUBE             | CUBE             | Equivalent to a bevelled cube with a bevel percentage of zero.                    | color, scaleDimensions                                        |
 514 | Dali::Toolkit::PrimitiveVisual::Shape::OCTAHEDRON       | OCTAHEDRON       | Equivalent to a bevelled cube with a bevel percentage of one.                     | color, scaleDimensions                                        |
 515 | Dali::Toolkit::PrimitiveVisual::Shape::BEVELLED_CUBE    | BEVELLED_CUBE    | A cube/cuboid with all edges flattened to some degree.                            | color, scaleDimensions, bevelPercentage, bevelSmoothness      |
 516
 517 #### Examples below:
 518
 519 **sphere:**
 520
 521 ![ ](visuals/sphere.png)
 522
 523 **conics:**
 524
 525 | Frustrum | Cone | Cylinder |
 526 |----------|------|----------|
 527 | ![ ](visuals/conical-frustrum.png) | ![ ](visuals/cone.png) | ![ ](visuals/cylinder.png) |
 528
 529 ### Bevel {#bevel-details}
 530
 531 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:
 532
 533 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
 534 |-------------|-----|-----|------------------|
 535 | ![ ](visuals/cube.png) | ![ ](visuals/bevelled-cube-low.png) | ![ ](visuals/bevelled-cube-high.png) | ![ ](visuals/octahedron.png) |
 536
 537 ### Slices {#slices-details}
 538
 539 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
 540
 541 ![ ](visuals/slices.png)
 542
 543 ### Stacks {#stacks-details}
 544
 545 For spheres, 'stacks' determines how many layers there are as you go down the object.
 546
 547 ![ ](visuals/stacks.png)
 548
 549 ### Usage
 550
 551 **sphere**
 552
 553 ~~~{.cpp}
 554 // C++
 555 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 556
 557 Dali::Property::Map map;
 558
 559 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 560 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::SPHERE;
 561 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 562
 563 control.SetProperty( Control::Property::BACKGROUND, map );
 564 ~~~
 565
 566 **conical frustrum**
 567
 568 ~~~{.cpp}
 569 // C++
 570 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 571
 572 Dali::Property::Map map;
 573
 574 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 575 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::CONICAL_FRUSTRUM;
 576 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 577 map[ PrimitiveVisual::Property::SCALE_TOP_RADIUS ] = 1.0f;
 578 map[ PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS ] = 1.5f;
 579 map[ PrimitiveVisual::Property::SCALE_HEIGHT ] = 3.0f;
 580
 581 control.SetProperty( Control::Property::BACKGROUND, map );
 582 ~~~
 583
 584 **bevelled cube**
 585
 586 ~~~{.cpp}
 587 // C++
 588 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 589
 590 Dali::Property::Map map;
 591
 592 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
 593 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::BEVELLED_CUBE;
 594 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
 595 map[ PrimitiveVisual::Property::BEVEL_PERCENTAGE ] = 0.4f;
 596
 597 control.SetProperty( Control::Property::BACKGROUND, map );
 598 ~~~
 599 ___________________________________________________________________________________________________
 600
 601 ## Text Visual {#text-visual}
 602
 603 Renders text within a control.
 604
 605 ![ ](visuals/HelloWorld.png)
 606
 607 ### Properties
 608
 609 **VisualType:** Dali::Toolkit::Visual::TEXT, "TEXT"
 610
 611 | Property                                                    | String              | Type          | Required | Description                                                                   | Default                |
 612 |-------------------------------------------------------------|---------------------|:-------------:|:--------:|-------------------------------------------------------------------------------|------------------------|
 613 | Dali::Toolkit::TextVisual::Property::TEXT                   | text                | STRING        | Yes      | The text to display in UTF-8 format                                           |                        |
 614 | Dali::Toolkit::TextVisual::Property::FONT_FAMILY            | fontFamily          | STRING        | No       | The requested font family to use                                              |                        |
 615 | Dali::Toolkit::TextVisual::Property::FONT_STYLE             | fontStyle           | MAP           | No       | The requested font style to use                                               |                        |
 616 | Dali::Toolkit::TextVisual::Property::POINT_SIZE             | pointSize           | FLOAT         | Yes      | The size of font in points                                                    |                        |
 617 | Dali::Toolkit::TextVisual::Property::MULTI_LINE             | multiLine           | BOOLEAN       | No       | The single-line or multi-line layout option                                   | false                  |
 618 | Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT   | horizontalAlignment | STRING        | No       | The line horizontal alignment: "BEGIN", "CENTER", "END"                       | "BEGIN"                |
 619 | Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT     | verticalAlignment   | STRING        | No       | The line vertical alignment: "TOP",   "CENTER", "BOTTOM"                      | "TOP"                  |
 620 | Dali::Toolkit::TextVisual::Property::TEXT_COLOR             | textColor           | VECTOR4       | No       | The color of the text                                                         | Color::BLACK           |
 621 | Dali::Toolkit::TextVisual::Property::ENABLE_MARKUP         | enableMarkup           | BOOL       | No       | If mark up should be enabled |                                                        |
 622
 623 ### Usage
 624
 625 ~~~{.cpp}
 626     // C++
 627     Dali::Stage stage = Dali::Stage::GetCurrent();
 628     stage.SetBackgroundColor( Dali::Color::WHITE );
 629
 630     Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 631     control.SetParentOrigin( ParentOrigin::CENTER );
 632
 633     Dali::Property::Map map;
 634     map[ Dali::Toolkit::Visual::Property::TYPE ] = Dali::Toolkit::Visual::TEXT;
 635     map[ Dali::Toolkit::TextVisual::Property::TEXT ] = "Hello world";
 636     map[ Dali::Toolkit::TextVisual::Property::TEXT_COLOR ] = Dali::Color::BLACK;
 637     map[ Dali::Toolkit::TextVisual::Property::FONT_FAMILY ] = "Sans";
 638     map[ Dali::Toolkit::TextVisual::Property::POINT_SIZE ] = 30.f;
 639     map[ Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT ] = "CENTER";
 640     map[ Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT ] = "CENTER";
 641
 642     control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 643
 644     stage.Add( control );
 645 ~~~
 646
 647 ## Wireframe Visual {#wireframe-visual}
 648
 649 Renders a wireframe around a quad geometry.
 650 Is mainly used for debugging and is the visual that replaces all other visuals when [Visual Debug Rendering](@ref debugrendering) is turned on.
 651
 652 ![ ](visuals/wireframe-visual.png)
 653
 654 ### Properties
 655
 656 **VisualType:** Dali::Toolkit::Visual::WIREFRAME, "WIREFRAME"
 657
 658 ### Usage
 659
 660 ~~~{.cpp}
 661 // C++
 662 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 663
 664 Dali::Property::Map map;
 665 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::WIREFRAME;
 666
 667 control.SetProperty( Control::Property::BACKGROUND, map );
 668 ~~~
 669
 670
 671
 672 */