4 # Control Renderers {#control-renderers}
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.
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.
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)
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 ___________________________________________________________________________________________________
24 ## Color Renderer {#color-renderer}
26 Renders a solid color to the control's quad.
28 ![ ](../assets/img/renderers/color-renderer.png)
29 ![ ](renderers/color-renderer.png)
31 ### Properties Supported
33 **RendererType:** "color"
35 | Property Name | Type | Required | Description |
36 |---------------|:-------:|:--------:|---------------------------|
37 | mixColor | VECTOR4 | Yes | The solid color required. |
43 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
45 Dali::Property::Map map;
46 map[ "rendererType" ] = "color";
47 map[ "mixColor" ] = Color::RED;
49 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
54 var control = new dali.Control( "Control" );
58 rendererType : "color",
59 mixColor : dali.COLOR_RED
62 ___________________________________________________________________________________________________
64 ## Gradient Renderer {#gradient-renderer}
66 Renders a smooth transition of colors to the control's quad.
68 Both Linear and Radial gradients are supported.
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) |
74 ### Properties Supported
76 **RendererType:** "gradient"
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* |
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.
91 ### Units {#gradient-renderer-units}
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.
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). |
102 ### Spread Method {#gradient-renderer-spread-method}
104 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
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. |
117 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
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 );
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;
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;
140 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
145 var control = new dali.Control( "Control" );
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 ],
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 ],
166 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
168 Dali::Property::Map map;
169 map[ "rendererType" ] = "gradient";
170 map[ "center" ] = Vector2( 0.5f, 0.5f );
171 map[ "radius" ] = 1.414f;
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;
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;
189 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
194 var control = new dali.Control( "Control" );
198 rendererType : "gradient",
199 center : [ 0.5, 0.5 ],
201 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
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 ],
211 ___________________________________________________________________________________________________
213 ## Image Renderers {#image-renderers}
215 Renders an image into the control's quad.
217 Depending on the extension of the image, different renderer is provided to render the image onto the screen.
219 + [Normal](@ref image-renderer)
220 + [N-Patch](@ref n-patch-renderer)
221 + [SVG](@ref svg-renderer)
223 ___________________________
225 ### Normal {#image-renderer}
227 Renders a raster image ( jpg, png etc.) into the control's quad.
229 ![ ](../assets/img/renderers/image-renderer.png)
230 ![ ](renderers/image-renderer.png)
232 #### Properties Supported
234 **RendererType:** "image"
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. |
248 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
250 Dali::Property::Map map;
251 map[ "rendererType" ] = "image";
252 map[ "url" ] = "path-to-image.jpg";
254 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
259 var control = new dali.Control( "Control" );
263 rendererType : "image",
264 url : "path-to-image.jpg"
267 ___________________________________________________________________________________________________
269 ### N-Patch {#n-patch-renderer}
271 Renders an n-patch or a 9-patch image into the control's quad.
273 ![ ](../assets/img/renderers/n-patch-renderer.png)
274 ![ ](renderers/n-patch-renderer.png)
276 #### Properties Supported
278 **RendererType:** "image"
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. |
289 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
291 Dali::Property::Map map;
293 map[ "rendererType" ] = "image";
294 map[ "url" ] = "path-to-image.9.png";
296 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
301 var control = new dali.Control( "Control" );
305 rendererType : "image",
306 url : "path-to-image.9.png"
310 ___________________________________________________________________________________________________
312 ### SVG {#svg-renderer}
314 Renders a svg image into the control's quad.
316 #### Features: SVG Tiny 1.2 specification
323 * gradient color fill
328 * gradient color stroke
334 <div style="width:300px">
336 ![ ](../assets/img/renderers/svg-renderer.svg)
340 <div style="width:300px">
342 ![ ](renderers/svg-renderer.svg)
347 #### Properties Supported
349 **RendererType:** "image"
351 | Property Name | Type | Required | Description |
352 |---------------|:-------:|:--------:|----------------------------------|
353 | url | STRING | Yes | The URL of the SVG image. |
359 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
361 Dali::Property::Map map;
363 map[ "rendererType" ] = "image";
364 map[ "url" ] = "path-to-image.svg";
366 control.SetSize( 200.f, 200.f );
367 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
372 var control = new dali.Control( "Control" );
376 rendererType : "image",
377 url : "path-to-image.svg"
380 ___________________________________________________________________________________________________
382 ## Border Renderer {#border-renderer}
384 Renders a solid color as an internal border to the control's quad.
386 ![ ](../assets/img/renderers/border-renderer.png)
387 ![ ](renderers/border-renderer.png)
389 ### Properties Supported
391 **RendererType:** "border"
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. |
403 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
405 Dali::Property::Map map;
407 map[ "rendererType" ] = "border";
408 map[ "borderColor" ] = Color::BLUE;
409 map[ "borderSize" ] = 5.0f;
411 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
416 var control = new dali.Control( "Control" );
420 rendererType : "border",
421 borderColor : dali.COLOR_BLUE,
426 @class _Guide_Control_Renderers