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