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  + [Border](@ref border-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 | blendColor    | 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[ "blendColor" ] = 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   blendColor : 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 | gradientStartPosition                                        | VECTOR2          | For Linear | The start position of the linear gradient.                        |
  82 | gradientEndPosition                                          | VECTOR2          | For Linear | The end position of the linear gradient.                          |
  83 | gradientCenter                                               | VECTOR2          | For Radial | The center point of the gradient.                                 |
  84 | gradientRadius                                               | FLOAT            | For Radial | The size of the radius.                                           |
  85 | gradientStopOffset                                           | ARRAY of FLOAT   | Yes        | All the stop offsets.                                             |
  86 | gradientStopColor                                            | ARRAY of VECTOR4 | Yes        | The color at those stop offsets.                                  |
  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 *gradientStopOffset* and *gradientStopColor* 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[ "gradientStartPosition" ] = Vector2( 0.5f, 0.5f );
 123 map[ "gradientEndPosition" ] = 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[ "gradientStopOffset" ] = 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[ "gradientStopColor" ] = 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   gradientStartPosition : [ 0.5, 0.5 ],
 152   gradientEndPosition : [ -0.5, -0.5 ],
 153   gradientStopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 154   gradientStopColor : [
 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[ "gradientCenter" ] = Vector2( 0.5f, 0.5f );
 172 map[ "gradientRadius" ] = 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[ "gradientStopOffset" ] = 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[ "gradientStopColor" ] = 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   gradientCenter : [ 0.5, 0.5 ],
 201   gradientRadius : 1.414,
 202   gradientStopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
 203   gradientStopColor : [
 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 Renderer {#image-renderer}
 215
 216 Renders an image into the control's quad.
 217
 218 ![ ](../assets/img/renderers/image-renderer.png)
 219 ![ ](renderers/image-renderer.png)
 220
 221 ### Properties Supported
 222
 223 **RendererType:** "image"
 224
 225 | Property Name      | Type     | Required | Description                                                                                                                                     |
 226 |--------------------|:--------:|:--------:|-------------------------------------------------------------------------------------------------------------------------------------------------|
 227 | imageUrl           | STRING   | Yes      | The URL of the image.                                                                                                                           |
 228 | [imageFittingMode](@ref resourceimagescaling-fittingmode) | STRING   | No       | *shrinkToFit*, *scaleToFill*, *fitWidth* or *fitHeight*. Default: *shrinkToFit*.                         |
 229 | [imageSamplingMode](@ref resourceimagescaling-scaling)    | STRING   | No       | *box*, *nearest*, *linear*, *boxThenNearest*, *boxThenLinear*, *noFilter* or *dontCare*. Default: *box*. |
 230 | imageDesiredWidth  | INT      | No       | The desired image width. Will use actual image width if not specified.                                                                          |
 231 | imageDesiredHeight | INT      | No       | The desired image height. Will use actual image height if not specified.                                                                        |
 232
 233 ### Usage
 234
 235 ~~~{.cpp}
 236 // C++
 237 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 238
 239 Dali::Property::Map map;
 240 map[ "rendererType" ] = "image";
 241 map[ "imageUrl" ] = "path-to-image.jpg";
 242
 243 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 244 ~~~
 245
 246 ~~~{.js}
 247 // JavaScript
 248 var control = new dali.Control( "Control" );
 249
 250 control.background =
 251 {
 252   rendererType : "image",
 253   imageUrl : "path-to-image.jpg"
 254 };
 255 ~~~
 256 ___________________________________________________________________________________________________
 257
 258 ## N-Patch Renderer {#n-patch-renderer}
 259
 260 Renders an n-patch or a 9-patch image into the control's quad.
 261
 262 ![ ](../assets/img/renderers/n-patch-renderer.png)
 263 ![ ](renderers/n-patch-renderer.png)
 264
 265 ### Properties Supported
 266
 267 **RendererType:** "nPatch"
 268
 269 | Property Name | Type    | Required | Description                      |
 270 |---------------|:-------:|:--------:|----------------------------------|
 271 | imageUrl      | STRING  | Yes      | The URL of the n-patch image.    |
 272 | borderOnly    | BOOLEAN | No       | If true, only draws the borders. |
 273
 274 ### Usage
 275
 276 ~~~{.cpp}
 277 // C++
 278 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 279
 280 Dali::Property::Map map;
 281
 282 map[ "rendererType" ] = "nPatch";
 283 map[ "imageUrl" ] = "path-to-image.9.png";
 284
 285 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 286 ~~~
 287
 288 ~~~{.js}
 289 // JavaScript
 290 var control = new dali.Control( "Control" );
 291
 292 control.background =
 293 {
 294   rendererType : "nPatch",
 295   imageUrl : "path-to-image.9.png"
 296 };
 297 ~~~
 298 ___________________________________________________________________________________________________
 299
 300 ## Border Renderer {#border-renderer}
 301
 302 Renders a solid color as an internal border to the control's quad.
 303
 304 ![ ](../assets/img/renderers/border-renderer.png)
 305 ![ ](renderers/border-renderer.png)
 306
 307 ### Properties Supported
 308
 309 **RendererType:** "border"
 310
 311 | Property Name | Type    | Required | Description                                      |
 312 |---------------|:-------:|:--------:|--------------------------------------------------|
 313 | borderColor   | VECTOR4 | Yes      | The color of the border.                         |
 314 | borderSize    | FLOAT   | Yes      | The width of the border (in pixels).             |
 315 | antiAliasing  | BOOLEAN | No       | Whether anti-aliasing of the border is required. |
 316
 317 ### Usage
 318
 319 ~~~{.cpp}
 320 // C++
 321 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
 322
 323 Dali::Property::Map map;
 324
 325 map[ "rendererType" ] = "border";
 326 map[ "borderColor"  ] = Color::BLUE;
 327 map[ "borderSize"   ] = 5.0f;
 328
 329 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
 330 ~~~
 331
 332 ~~~{.js}
 333 // JavaScript
 334 var control = new dali.Control( "Control" );
 335
 336 control.background =
 337 {
 338   rendererType : "border",
 339   borderColor : dali.COLOR_BLUE,
 340   borderSize = 5
 341 };
 342 ~~~
 343
 344 @class _Guide_Control_Renderers
 345
 346 */