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