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