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)
17 + [Mesh](@ref mesh-renderer)
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 ___________________________________________________________________________________________________
25 ## Color Renderer {#color-renderer}
27 Renders a solid color to the control's quad.
29 ![ ](../assets/img/renderers/color-renderer.png)
30 ![ ](renderers/color-renderer.png)
32 ### Properties Supported
34 **RendererType:** "color"
36 | Property Name | Type | Required | Description |
37 |---------------|:-------:|:--------:|---------------------------|
38 | mixColor | VECTOR4 | Yes | The solid color required. |
44 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
46 Dali::Property::Map map;
47 map[ "rendererType" ] = "color";
48 map[ "mixColor" ] = Color::RED;
50 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
55 var control = new dali.Control( "Control" );
59 rendererType : "color",
60 mixColor : dali.COLOR_RED
63 ___________________________________________________________________________________________________
65 ## Gradient Renderer {#gradient-renderer}
67 Renders a smooth transition of colors to the control's quad.
69 Both Linear and Radial gradients are supported.
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) |
75 ### Properties Supported
77 **RendererType:** "gradient"
79 | Property Name | Type | Required | Description |
80 |--------------------------------------------------------------|:----------------:|:----------:|-------------------------------------------------------------------------|
81 | startPosition | VECTOR2 | For Linear | The start position of the linear gradient. |
82 | endPosition | VECTOR2 | For Linear | The end position of the linear gradient. |
83 | center | VECTOR2 | For Radial | The center point of the gradient. |
84 | radius | FLOAT | For Radial | The size of the radius. |
85 | stopOffset | ARRAY of FLOAT | No | All the stop offsets. If not supplied default is 0.0 and 1.0 |
86 | stopColor | ARRAY of VECTOR4 | Yes | The color at those stop offsets. At least 2 required to show a gradient |
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* |
90 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.
92 ### Units {#gradient-renderer-units}
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.
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). |
103 ### Spread Method {#gradient-renderer-spread-method}
105 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
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. |
118 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
120 Dali::Property::Map map;
121 map[ "rendererType" ] = "gradient";
122 map[ "startPosition" ] = Vector2( 0.5f, 0.5f );
123 map[ "endPosition" ] = Vector2( -0.5f, -0.5f );
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[ "stopOffset" ] = stopOffsets;
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[ "stopColor" ] = stopColors;
141 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
146 var control = new dali.Control( "Control" );
150 rendererType : "gradient",
151 startPosition : [ 0.5, 0.5 ],
152 endPosition : [ -0.5, -0.5 ],
153 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
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 ],
167 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
169 Dali::Property::Map map;
170 map[ "rendererType" ] = "gradient";
171 map[ "center" ] = Vector2( 0.5f, 0.5f );
172 map[ "radius" ] = 1.414f;
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[ "stopOffset" ] = stopOffsets;
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[ "stopColor" ] = stopColors;
190 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
195 var control = new dali.Control( "Control" );
199 rendererType : "gradient",
200 center : [ 0.5, 0.5 ],
202 stopOffset : [ 0.0, 0.3, 0.6, 0.8, 1.0 ],
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 ],
212 ___________________________________________________________________________________________________
214 ## Image Renderers {#image-renderers}
216 Renders an image into the control's quad.
218 Depending on the extension of the image, different renderer is provided to render the image onto the screen.
220 + [Normal](@ref image-renderer)
221 + [N-Patch](@ref n-patch-renderer)
222 + [SVG](@ref svg-renderer)
224 ___________________________
226 ### Normal {#image-renderer}
228 Renders a raster image ( jpg, png etc.) into the control's quad.
230 ![ ](../assets/img/renderers/image-renderer.png)
231 ![ ](renderers/image-renderer.png)
233 #### Properties Supported
235 **RendererType:** "image"
237 | Property Name | Type | Required | Description |
238 |--------------------|:--------:|:--------:|-------------------------------------------------------------------------------------------------------------------------------------------------|
239 | url | STRING | Yes | The URL of the image. |
240 | [fittingMode](@ref resourceimagescaling-fittingmode) | STRING | No | *SHRINK_TO_FIT*, *SCALE_TO_FILL*, *FIT_WIDTH* or *FIT_HEIGHT*. Default: *SHRINK_TO_FIT*. |
241 | [samplingMode](@ref resourceimagescaling-scaling) | STRING | No | *BOX*, *NEAREST*, *LINEAR*, *BOX_THEN_NEAREST*, *BOX_THEN_LINEAR*, *NO_FILTERr* or *DONT_CARE*. Default: *BOX*. |
242 | desiredWidth | INT | No | The desired image width. Will use actual image width if not specified. |
243 | desiredHeight | INT | No | The desired image height. Will use actual image height if not specified. |
249 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
251 Dali::Property::Map map;
252 map[ "rendererType" ] = "image";
253 map[ "url" ] = "path-to-image.jpg";
255 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
260 var control = new dali.Control( "Control" );
264 rendererType : "image",
265 url : "path-to-image.jpg"
268 ___________________________________________________________________________________________________
270 ### N-Patch {#n-patch-renderer}
272 Renders an n-patch or a 9-patch image into the control's quad.
274 ![ ](../assets/img/renderers/n-patch-renderer.png)
275 ![ ](renderers/n-patch-renderer.png)
277 #### Properties Supported
279 **RendererType:** "image"
281 | Property Name | Type | Required | Description |
282 |---------------|:-------:|:--------:|----------------------------------|
283 | url | STRING | Yes | The URL of the n-patch image. |
284 | borderOnly | BOOLEAN | No | If true, only draws the borders. |
290 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
292 Dali::Property::Map map;
294 map[ "rendererType" ] = "image";
295 map[ "url" ] = "path-to-image.9.png";
297 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
302 var control = new dali.Control( "Control" );
306 rendererType : "image",
307 url : "path-to-image.9.png"
311 ___________________________________________________________________________________________________
313 ### SVG {#svg-renderer}
315 Renders a svg image into the control's quad.
317 #### Features: SVG Tiny 1.2 specification
324 * gradient color fill
329 * gradient color stroke
335 <div style="width:300px">
337 ![ ](../assets/img/renderers/svg-renderer.svg)
341 <div style="width:300px">
343 ![ ](renderers/svg-renderer.svg)
348 #### Properties Supported
350 **RendererType:** "image"
352 | Property Name | Type | Required | Description |
353 |---------------|:-------:|:--------:|----------------------------------|
354 | url | STRING | Yes | The URL of the SVG image. |
360 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
362 Dali::Property::Map map;
364 map[ "rendererType" ] = "image";
365 map[ "url" ] = "path-to-image.svg";
367 control.SetSize( 200.f, 200.f );
368 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
373 var control = new dali.Control( "Control" );
377 rendererType : "image",
378 url : "path-to-image.svg"
381 ___________________________________________________________________________________________________
383 ## Border Renderer {#border-renderer}
385 Renders a solid color as an internal border to the control's quad.
387 ![ ](../assets/img/renderers/border-renderer.png)
388 ![ ](renderers/border-renderer.png)
390 ### Properties Supported
392 **RendererType:** "border"
394 | Property Name | Type | Required | Description |
395 |---------------|:-------:|:--------:|--------------------------------------------------|
396 | borderColor | VECTOR4 | Yes | The color of the border. |
397 | borderSize | FLOAT | Yes | The width of the border (in pixels). |
398 | antiAliasing | BOOLEAN | No | Whether anti-aliasing of the border is required. |
404 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
406 Dali::Property::Map map;
408 map[ "rendererType" ] = "border";
409 map[ "borderColor" ] = Color::BLUE;
410 map[ "borderSize" ] = 5.0f;
412 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
417 var control = new dali.Control( "Control" );
421 rendererType : "border",
422 borderColor : dali.COLOR_BLUE,
427 ___________________________________________________________________________________________________
429 ## Mesh Renderer {#mesh-renderer}
431 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
433 ![ ](../assets/img/renderers/mesh-renderer.png)
434 ![ ](renderers/mesh-renderer.png)
436 ### Properties Supported
438 **RendererType** "mesh"
440 | Property Name | Type | Required | Description |
441 |---------------|:-------:|:------------------:|----------------------------------------------------------------------|
442 | objectUrl | STRING | Yes | The location of the .obj file. |
443 | materialUrl | STRING | No | The location of the .mtl file. Leave blank for a textureless object. |
444 | texturesPath | STRING | If using material | Path to the directory textures (including gloss and normal) are stored in. |
445 | shaderType | STRING | No | Sets the type of shader to be used with the mesh. Note that if anything the shader requires is missing, it will use a simpler one that it can handle with what has been supplied.\n Possible values: "textureless", "diffuseTexture", "allTextures". |
451 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
453 Dali::Property::Map map;
455 map[ "rendererType" ] = "mesh";
456 map[ "objectUrl" ] = "home/models/Dino.obj";
457 map[ "materialUrl" ] = "home/models/Dino.mtl";
458 map[ "texturesPath" ] = "home/images/";
460 control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
463 @class _Guide_Control_Renderers