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

   1 <!--
   2 /**-->
   3
   4 # Control Renderers  {#control-renderers}
   5
   6 Control Renderers provide reusable renderering logic which can be used by all controls.
   7 This means that custom controls do not have to create actors, they can just reuse the existing renderers which increases performance as well.
   8
   9 Control Renderers reuse geometry, shader etc. across controls and manages the renderer and material to exist only when the control is on-stage.
  10 Additionaly, they respond to actor size and color change, while also providing clipping at the renderer level.
  11
  12 DALi provides the following renderers:
  13  + [Color](@ref color-renderer)
  14  + [Gradient](@ref gradient-renderer)
  15  + [Image](@ref image-renderers)
  16  + [Border](@ref border-renderer)
  17  + [Mesh](@ref mesh-renderer)
  18
  19 Controls can provide properties that allow users to specify the renderer type.
  20 Setting renderer properties are done via a property map.
  21 The **rendererType** field in the property map specifies the renderer to use/create.
  22 This is required to avoid ambiguity as multiple renderers may be capable of rendering the same contents.
  23 ___________________________________________________________________________________________________
  24
  25 ## Color Renderer {#color-renderer}
  26
  27 Renders a solid color to the control's quad.
  28
  29 ![ ](../assets/img/renderers/color-renderer.png)
  30 ![ ](renderers/color-renderer.png)
  31
  32 ### Properties Supported
  33
  34 **RendererType:** "color"
  35
  36 | Property Name | Type    | Required | Description               |
  37 |---------------|:-------:|:--------:|---------------------------|
  38 | mixColor      | VECTOR4 | Yes      | The solid color required. |
  39
  40 ### Usage
  41
  42 ~~~{.cpp}
  43 // C++
  44 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
  45
  46 Dali::Property::Map map;
  47 map[ "rendererType" ] = "color";
  48 map[ "mixColor" ] = Color::RED;
  49
  50 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
  51 ~~~
  52
  53 ~~~{.js}
  54 // JavaScript
  55 var control = new dali.Control( "Control" );
  56
  57 control.background =
  58 {
  59   rendererType : "color",
  60   mixColor : dali.COLOR_RED
  61 };
  62 ~~~
  63 ___________________________________________________________________________________________________
  64
  65 ## Gradient Renderer {#gradient-renderer}
  66
  67 Renders a smooth transition of colors to the control's quad.
  68
  69 Both Linear and Radial gradients are supported.
  70
  71 | Linear | Radial |
  72 |--------|--------|
  73 | ![ ](../assets/img/renderers/linear-gradient-renderer.png) ![ ](renderers/linear-gradient-renderer.png) | ![ ](../assets/img/renderers/radial-gradient-renderer.png) ![ ](renderers/radial-gradient-renderer.png) |
  74
  75 ### Properties Supported
  76
  77 **RendererType:** "gradient"
  78
  79 | Property Name                                                | Type             | Required   | Description                                                             |
  80 |--------------------------------------------------------------|:----------------:|:----------:|-------------------------------------------------------------------------|
  81 | startPosition                                                | VECTOR2          | For Linear | The start position of the linear gradient.                              |
  82 | endPosition                                                  | VECTOR2          | For Linear | The end position of the linear gradient.                                |
  83 | center                                                       | VECTOR2          | For Radial | The center point of the gradient.                                       |
  84 | radius                                                       | FLOAT            | For Radial | The size of the radius.                                                 |
  85 | stopOffset                                                   | ARRAY of FLOAT   | No         | All the stop offsets. If not supplied default is 0.0 and 1.0            |
  86 | stopColor                                                    | ARRAY of VECTOR4 | Yes        | The color at those stop offsets. At least 2 required to show a gradient |
  87 | [gradientUnits](@ref gradient-renderer-units)                | STRING           | No         | *objectBoundingBox* or *userSpace*. Default: *objectBoundingBox*.       |
  88 | [gradientSpreadMethod](@ref gradient-renderer-spread-method) | STRING           | No         | *pad*, *repeat* or *reflect*. Default: *pad*                            |
  89
  90 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.
  91
  92 ### Units {#gradient-renderer-units}
  93
  94 Defines the coordinate system for the attributes:
  95  + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
  96  + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
  97
  98 | Value             | Description                                                                                                                                    |
  99 |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
 100 | objectBoundingBox | *Default*. Uses the normals for the start, end & center points, i.e. top-left is (-0.5, -0.5) and bottom-right it (0.5, 0.5).                  |
 101 | userSpace         | 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). |
 102
 103 ### Spread Method {#gradient-renderer-spread-method}
 104
 105 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
 106
 107 | Value   | Description                                                                                          |
 108 |---------|------------------------------------------------------------------------------------------------------|
 109 | pad     | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad.               |
 110 | reflect | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad is filled. |
 111 | repeat  | Repeat the gradient pattern start-to-end, start-to-end, start-to-end until the quad is filled.       |
 112
 113 ### Usage
 114
 115 **Linear:**
 116 ~~~{.cpp}
 117 // C++
 118 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 119
 120 Dali::Property::Map map;
 121 map[ "rendererType" ] = "gradient";
 122 map[ "startPosition" ] = Vector2( 0.5f, 0.5f );
 123 map[ "endPosition" ] = Vector2( -0.5f, -0.5f );
 124
 125 Dali::Property::Array stopOffsets;
 126 stopOffsets.PushBack( 0.0f );
 127 stopOffsets.PushBack( 0.3f );
 128 stopOffsets.PushBack( 0.6f );
 129 stopOffsets.PushBack( 0.8f );
 130 stopOffsets.PushBack( 1.f );
 131 map[ "stopOffset" ] = stopOffsets;
 132
 133 Dali::Property::Array stopColors;
 134 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 135 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 136 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 137 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 138 stopColors.PushBack( Color::YELLOW );
 139 map[ "stopColor" ] = stopColors;
 140
 141 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 142 ~~~
 143
 144 ~~~{.js}
 145 // JavaScript
 146 var control = new dali.Control( "Control" );
 147
 148 control.background =
 149 {
 150   rendererType : "gradient",
 151   startPosition : [ 0.5, 0.5 ],
 152   endPosition : [ -0.5, -0.5 ],
 153   stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 154   stopColor : [
 155     [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
 156     [ 196 / 255, 198 / 255,  71 / 255, 122 / 255 ],
 157     [ 214 / 255,  37 / 255, 139 / 255, 191 / 255 ],
 158     [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
 159     dali.COLOR_YELLOW
 160   ]
 161 };
 162 ~~~
 163
 164 **Radial:**
 165 ~~~{.cpp}
 166 // C++
 167 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 168
 169 Dali::Property::Map map;
 170 map[ "rendererType" ] = "gradient";
 171 map[ "center" ] = Vector2( 0.5f, 0.5f );
 172 map[ "radius" ] = 1.414f;
 173
 174 Dali::Property::Array stopOffsets;
 175 stopOffsets.PushBack( 0.0f );
 176 stopOffsets.PushBack( 0.3f );
 177 stopOffsets.PushBack( 0.6f );
 178 stopOffsets.PushBack( 0.8f );
 179 stopOffsets.PushBack( 1.f );
 180 map[ "stopOffset" ] = stopOffsets;
 181
 182 Dali::Property::Array stopColors;
 183 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
 184 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
 185 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
 186 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
 187 stopColors.PushBack( Color::YELLOW );
 188 map[ "stopColor" ] = stopColors;
 189
 190 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 191 ~~~
 192
 193 ~~~{.js}
 194 // JavaScript
 195 var control = new dali.Control( "Control" );
 196
 197 control.background =
 198 {
 199   rendererType : "gradient",
 200   center : [ 0.5, 0.5 ],
 201   radius : 1.414,
 202   stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 203   stopColor : [
 204     [ 129 / 255, 198 / 255, 193 / 255, 255 / 255 ],
 205     [ 196 / 255, 198 / 255,  71 / 255, 122 / 255 ],
 206     [ 214 / 255,  37 / 255, 139 / 255, 191 / 255 ],
 207     [ 129 / 255, 198 / 255, 193 / 255, 150 / 255 ],
 208     dali.COLOR_YELLOW
 209   ]
 210 };
 211 ~~~
 212 ___________________________________________________________________________________________________
 213
 214 ## Image Renderers {#image-renderers}
 215
 216 Renders an image into the control's quad.
 217
 218 Depending on the extension of the image, different renderer is provided to render the image onto the screen.
 219
 220  + [Normal](@ref image-renderer)
 221  + [N-Patch](@ref n-patch-renderer)
 222  + [SVG](@ref svg-renderer)
 223
 224 ___________________________
 225
 226 ### Normal {#image-renderer}
 227
 228 Renders a raster image ( jpg, png etc.) into the control's quad.
 229
 230 ![ ](../assets/img/renderers/image-renderer.png)
 231 ![ ](renderers/image-renderer.png)
 232
 233 #### Properties Supported
 234
 235 **RendererType:** "image"
 236
 237 | Property Name      | Type     | Required | Description                                                                                                                                     |
 238 |--------------------|:--------:|:--------:|-------------------------------------------------------------------------------------------------------------------------------------------------|
 239 | url           | STRING   | Yes      | The URL of the image.                                                                                                                           |
 240 | [fittingMode](@ref resourceimagescaling-fittingmode) | STRING   | No       | *SHRINK_TO_FIT*, *SCALE_TO_FILL*, *FIT_WIDTH* or *FIT_HEIGHT*. Default: *SHRINK_TO_FIT*.                         |
 241 | [samplingMode](@ref resourceimagescaling-scaling)    | STRING   | No       | *BOX*, *NEAREST*, *LINEAR*, *BOX_THEN_NEAREST*, *BOX_THEN_LINEAR*, *NO_FILTERr* or *DONT_CARE*. Default: *BOX*. |
 242 | desiredWidth  | INT      | No       | The desired image width. Will use actual image width if not specified.                                                                          |
 243 | desiredHeight | INT      | No       | The desired image height. Will use actual image height if not specified.                                                                        |
 244
 245 #### Usage
 246
 247 ~~~{.cpp}
 248 // C++
 249 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 250
 251 Dali::Property::Map map;
 252 map[ "rendererType" ] = "image";
 253 map[ "url" ] = "path-to-image.jpg";
 254
 255 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 256 ~~~
 257
 258 ~~~{.js}
 259 // JavaScript
 260 var control = new dali.Control( "Control" );
 261
 262 control.background =
 263 {
 264   rendererType : "image",
 265   url : "path-to-image.jpg"
 266 };
 267 ~~~
 268 ___________________________________________________________________________________________________
 269
 270 ### N-Patch {#n-patch-renderer}
 271
 272 Renders an n-patch or a 9-patch image into the control's quad.
 273
 274 ![ ](../assets/img/renderers/n-patch-renderer.png)
 275 ![ ](renderers/n-patch-renderer.png)
 276
 277 #### Properties Supported
 278
 279 **RendererType:** "image"
 280
 281 | Property Name | Type    | Required | Description                      |
 282 |---------------|:-------:|:--------:|----------------------------------|
 283 | url           | STRING  | Yes      | The URL of the n-patch image.    |
 284 | borderOnly    | BOOLEAN | No       | If true, only draws the borders. |
 285
 286 #### Usage
 287
 288 ~~~{.cpp}
 289 // C++
 290 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 291
 292 Dali::Property::Map map;
 293
 294 map[ "rendererType" ] = "image";
 295 map[ "url" ] = "path-to-image.9.png";
 296
 297 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 298 ~~~
 299
 300 ~~~{.js}
 301 // JavaScript
 302 var control = new dali.Control( "Control" );
 303
 304 control.background =
 305 {
 306   rendererType : "image",
 307   url : "path-to-image.9.png"
 308 };
 309 ~~~
 310
 311 ___________________________________________________________________________________________________
 312
 313 ### SVG {#svg-renderer}
 314
 315 Renders a svg image into the control's quad.
 316
 317 #### Features: SVG Tiny 1.2 specification
 318
 319 **supported:**
 320
 321   * basic shapes
 322   * paths
 323   * solid color fill
 324   * gradient color fill
 325   * solid color stroke
 326
 327 **not supported:**
 328
 329   * gradient color stroke
 330   * dash array stroke
 331   * view box
 332   * text
 333   * clip path
 334
 335 <div style="width:300px">
 336
 337 ![ ](../assets/img/renderers/svg-renderer.svg)
 338
 339 </div>
 340
 341 <div style="width:300px">
 342
 343 ![ ](renderers/svg-renderer.svg)
 344
 345 </div>
 346
 347
 348 #### Properties Supported
 349
 350 **RendererType:** "image"
 351
 352 | Property Name | Type    | Required | Description                      |
 353 |---------------|:-------:|:--------:|----------------------------------|
 354 | url           | STRING  | Yes      | The URL of the SVG image.    |
 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[ "rendererType" ] = "image";
 365 map[ "url" ] = "path-to-image.svg";
 366
 367 control.SetSize( 200.f, 200.f );
 368 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 369 ~~~
 370
 371 ~~~{.js}
 372 // JavaScript
 373 var control = new dali.Control( "Control" );
 374
 375 control.background =
 376 {
 377   rendererType : "image",
 378   url : "path-to-image.svg"
 379 };
 380 ~~~
 381 ___________________________________________________________________________________________________
 382
 383 ## Border Renderer {#border-renderer}
 384
 385 Renders a solid color as an internal border to the control's quad.
 386
 387 ![ ](../assets/img/renderers/border-renderer.png)
 388 ![ ](renderers/border-renderer.png)
 389
 390 ### Properties Supported
 391
 392 **RendererType:** "border"
 393
 394 | Property Name | Type    | Required | Description                                      |
 395 |---------------|:-------:|:--------:|--------------------------------------------------|
 396 | borderColor   | VECTOR4 | Yes      | The color of the border.                         |
 397 | borderSize    | FLOAT   | Yes      | The width of the border (in pixels).             |
 398 | antiAliasing  | BOOLEAN | No       | Whether anti-aliasing of the border is required. |
 399
 400 ### Usage
 401
 402 ~~~{.cpp}
 403 // C++
 404 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 405
 406 Dali::Property::Map map;
 407
 408 map[ "rendererType" ] = "border";
 409 map[ "borderColor"  ] = Color::BLUE;
 410 map[ "borderSize"   ] = 5.0f;
 411
 412 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 413 ~~~
 414
 415 ~~~{.js}
 416 // JavaScript
 417 var control = new dali.Control( "Control" );
 418
 419 control.background =
 420 {
 421   rendererType : "border",
 422   borderColor : dali.COLOR_BLUE,
 423   borderSize = 5
 424 };
 425 ~~~
 426
 427 ___________________________________________________________________________________________________
 428
 429 ## Mesh Renderer {#mesh-renderer}
 430
 431 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
 432
 433 ![ ](../assets/img/renderers/mesh-renderer.png)
 434 ![ ](renderers/mesh-renderer.png)
 435
 436 ### Properties Supported
 437
 438 **RendererType** "mesh"
 439
 440 | Property Name | Type    | Required           | Description                                                          |
 441 |---------------|:-------:|:------------------:|----------------------------------------------------------------------|
 442 | objectUrl     | STRING  | Yes                | The location of the .obj file.                                       |
 443 | materialUrl   | STRING  | No                 | The location of the .mtl file. Leave blank for a textureless object. |
 444 | texturesPath  | STRING  | If using material  | Path to the directory textures (including gloss and normal) are stored in.   |
 445 | shaderType    | STRING  | No                 | Sets the type of shader to be used with the mesh. Note that if anything the shader requires is missing, it will use a simpler one that it can handle with what has been supplied.\n Possible values: "textureless", "diffuseTexture", "allTextures".  |
 446
 447 ### Usage
 448
 449 ~~~{.cpp}
 450 // C++
 451 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 452
 453 Dali::Property::Map map;
 454
 455 map[ "rendererType" ] = "mesh";
 456 map[ "objectUrl"    ] = "home/models/Dino.obj";
 457 map[ "materialUrl"  ] = "home/models/Dino.mtl";
 458 map[ "texturesPath" ] = "home/images/";
 459
 460 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 461 ~~~
 462
 463 @class _Guide_Control_Renderers
 464
 465 */