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