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