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-renderer)
16 + [N-Patch](@ref n-patch-renderer)
17 + [SVG](@ref svg-renderer)
18 + [Border](@ref border-renderer)
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 ___________________________________________________________________________________________________
26 ## Color Renderer {#color-renderer}
28 Renders a solid color to the control's quad.
30 ![ ](../assets/img/renderers/color-renderer.png)
31 ![ ](renderers/color-renderer.png)
33 ### Properties Supported
35 **RendererType:** "color"
37 | Property Name | Type | Required | Description |
38 |---------------|:-------:|:--------:|---------------------------|
39 | blendColor | VECTOR4 | Yes | The solid color required. |
45 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
47 Dali::Property::Map map;
48 map[ "rendererType" ] = "color";
49 map[ "blendColor" ] = Color::RED;
51 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
56 var control = new dali.Control( "Control" );
60 rendererType : "color",
61 blendColor : dali.COLOR_RED
64 ___________________________________________________________________________________________________
66 ## Gradient Renderer {#gradient-renderer}
68 Renders a smooth transition of colors to the control's quad.
70 Both Linear and Radial gradients are supported.
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) |
76 ### Properties Supported
78 **RendererType:** "gradient"
80 | Property Name | Type | Required | Description |
81 |--------------------------------------------------------------|:----------------:|:----------:|-------------------------------------------------------------------------|
82 | startPosition | VECTOR2 | For Linear | The start position of the linear gradient. |
83 | endPosition | VECTOR2 | For Linear | The end position of the linear gradient. |
84 | center | VECTOR2 | For Radial | The center point of the gradient. |
85 | radius | FLOAT | For Radial | The size of the radius. |
86 | stopOffset | ARRAY of FLOAT | No | All the stop offsets. If not supplied default is 0.0 and 1.0 |
87 | stopColor | ARRAY of VECTOR4 | Yes | The color at those stop offsets. At least 2 required to show a gradient |
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* |
91 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.
93 ### Units {#gradient-renderer-units}
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.
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). |
104 ### Spread Method {#gradient-renderer-spread-method}
106 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
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. |
119 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
121 Dali::Property::Map map;
122 map[ "rendererType" ] = "gradient";
123 map[ "startPosition" ] = Vector2( 0.5f, 0.5f );
124 map[ "endPosition" ] = Vector2( -0.5f, -0.5f );
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[ "stopOffset" ] = stopOffsets;
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[ "stopColor" ] = stopColors;
142 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
147 var control = new dali.Control( "Control" );
151 rendererType : "gradient",
152 startPosition : [ 0.5, 0.5 ],
153 endPosition : [ -0.5, -0.5 ],
154 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
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 ],
168 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
170 Dali::Property::Map map;
171 map[ "rendererType" ] = "gradient";
172 map[ "center" ] = Vector2( 0.5f, 0.5f );
173 map[ "radius" ] = 1.414f;
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[ "stopOffset" ] = stopOffsets;
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[ "stopColor" ] = stopColors;
191 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
196 var control = new dali.Control( "Control" );
200 rendererType : "gradient",
201 center : [ 0.5, 0.5 ],
203 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
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 ],
213 ___________________________________________________________________________________________________
215 ## Image Renderer {#image-renderer}
217 Renders an image into the control's quad.
219 ![ ](../assets/img/renderers/image-renderer.png)
220 ![ ](renderers/image-renderer.png)
222 ### Properties Supported
224 **RendererType:** "image"
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. |
238 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
240 Dali::Property::Map map;
241 map[ "rendererType" ] = "image";
242 map[ "imageUrl" ] = "path-to-image.jpg";
244 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
249 var control = new dali.Control( "Control" );
253 rendererType : "image",
254 imageUrl : "path-to-image.jpg"
257 ___________________________________________________________________________________________________
259 ## N-Patch Renderer {#n-patch-renderer}
261 Renders an n-patch or a 9-patch image into the control's quad.
263 ![ ](../assets/img/renderers/n-patch-renderer.png)
264 ![ ](renderers/n-patch-renderer.png)
266 ### Properties Supported
268 **RendererType:** "nPatch"
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. |
279 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
281 Dali::Property::Map map;
283 map[ "rendererType" ] = "nPatch";
284 map[ "imageUrl" ] = "path-to-image.9.png";
286 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
291 var control = new dali.Control( "Control" );
295 rendererType : "nPatch",
296 imageUrl : "path-to-image.9.png"
300 ___________________________________________________________________________________________________
302 ## SVG Renderer {#svg-renderer}
304 Renders a svg image into the control's quad.
306 <div style="width:300px">
308 ![ ](../assets/img/renderers/svg-renderer.svg)
312 <div style="width:300px">
314 ![ ](renderers/svg-renderer.svg)
318 ### Properties Supported
320 **RendererType:** "svg"
322 | Property Name | Type | Required | Description |
323 |---------------|:-------:|:--------:|----------------------------------|
324 | imageUrl | STRING | Yes | The URL of the SVG image. |
330 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
332 Dali::Property::Map map;
334 map[ "rendererType" ] = "svg";
335 map[ "imageUrl" ] = "path-to-image.svg";
337 control.SetSize( 200.f, 200.f );
338 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
343 var control = new dali.Control( "Control" );
347 rendererType : "svg",
348 imageUrl : "path-to-image.svg"
351 ___________________________________________________________________________________________________
353 ## Border Renderer {#border-renderer}
355 Renders a solid color as an internal border to the control's quad.
357 ![ ](../assets/img/renderers/border-renderer.png)
358 ![ ](renderers/border-renderer.png)
360 ### Properties Supported
362 **RendererType:** "border"
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. |
374 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
376 Dali::Property::Map map;
378 map[ "rendererType" ] = "border";
379 map[ "borderColor" ] = Color::BLUE;
380 map[ "borderSize" ] = 5.0f;
382 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
387 var control = new dali.Control( "Control" );
391 rendererType : "border",
392 borderColor : dali.COLOR_BLUE,
397 @class _Guide_Control_Renderers