Remove V8 plugin
[platform/core/uifw/dali-toolkit.git] / docs / content / programming-guide / visuals.md
1 <!--
2 /**-->
3
4 # Visuals {#visuals}
5
6 Visuals provide reusable rendering 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 visuals which increases performance.
8  
9 Visuals reuse geometry, shaders etc. across controls and manages the renderer and texture to exist only when the control is on-stage.
10 Additionally, they respond to actor size and color change, while also providing clipping at the renderer level.
11  
12 DALi provides the following visuals:
13  + [Color](@ref color-visual)
14  + [Gradient](@ref gradient-visual)
15  + [Image](@ref image-visuals)
16  + [Border](@ref border-visual)
17  + [Mesh](@ref mesh-visual)
18  + [Primitive](@ref primitive-visual)
19  + [Text](@ref text-visual)
20  + [Wireframe](@ref wireframe-visual)
21  
22 Controls can provide properties that allow users to specify the visual type ( visualType ).
23 Setting visual properties are done via a property map.
24 The **visualType** field in the property map specifies the visual to use/create.
25 This is required to avoid ambiguity as multiple visuals may be capable of rendering the same contents.
26
27 Visuals have a **transform** field in the property map to allow layouting within a control. If this field is not set, then the visual defaults to filling the control. The **transform** field has a property map with the following keys:
28
29 | Property                                                       | String       | Type              | Required | Description                                                                                 |
30 |----------------------------------------------------------------|--------------|:-----------------:|:--------:|---------------------------------------------------------------------------------------------|
31 | Dali::Toolkit::Visual::Transform::Property::OFFSET        | offset       | VECTOR2           | No       | The offset of the visual.                                                                   |
32 | Dali::Toolkit::Visual::Transform::Property::SIZE          | size         | VECTOR2           | No       | The size of the visual.                                                                     |
33 | Dali::Toolkit::Visual::Transform::Property::OFFSET_POLICY | offsetPolicy | VECTOR4           | No       | Whether the offset components are Relative or Absolute [More info](@ref offset-size-policy) |
34 | Dali::Toolkit::Visual::Transform::Property::SIZE_POLICY   | sizePolicy   | VECTOR4           | No       | Whether the size components are Relative or Absolute [More info](@ref offset-size-policy)   |
35 | Dali::Toolkit::Visual::Transform::Property::ORIGIN        | origin       | INTEGER or STRING | No       | The origin of the visual within the control's area. [More info](@ref align-type)            |
36 | Dali::Toolkit::Visual::Transform::Property::ANCHOR_POINT  | anchorPoint  | INTEGER or STRING | No       | The anchor point of the visual. [More info](@ref align-type)                                |
37  
38
39 ## Offset & Size Policy  {#offset-size-policy}
40
41 The offset and size policies can be either Relative or Absolute.
42
43 | Enumeration                                             | String   | Description                                                                   |
44 |---------------------------------------------------------|----------|-------------------------------------------------------------------------------|
45 | Dali::Toolkit::Visual::Transform::Policy::RELATIVE | RELATIVE | *Default*. The size or offset value represents a ratio of the control's size  |
46 | Dali::Toolkit::Visual::Transform::Policy::ABSOLUTE | ABSOLUTE | The size or offset value represents world units (pixels)                      |
47
48 For example, an offsetPolicy of [ RELATIVE, RELATIVE ], a sizePolicy of [ ABSOLUTE, ABSOLUTE ], an offset of ( 0, 0.25 ) and a size of ( 20, 20 ) means the visual will be 20 pixels by 20 pixels in size, positioned 25% above the center of the control.
49
50 ## Alignment  {#align-type}
51 | Enumeration                                          | String  | Description                                                                                          |
52 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
53 | Dali::Toolkit::Align::TOP_BEGIN | TOP_BEGIN | Aligns to the top of the vertical axis and the beginning of the horizontal axis (The left or right edge in Left-To-Right or Right-to-Left layouts, respectively) |
54 | Dali::Toolkit::Align::TOP_CENTER | TOP_CENTER | Aligns to the top of the vertical axis and the center of the horizontal axis |
55 | Dali::Toolkit::Align::TOP_END | TOP_END | Aligns to the top of the vertical axis and end of the horizontal axis (The right or left edge in Left-To-Right or Right-to-Left layouts, respectively) |
56 | Dali::Toolkit::Align::CENTER_BEGIN | CENTER_BEGIN | Aligns to the center of the vertical axis and the beginning of the horizontal axis|
57 | Dali::Toolkit::Align::CENTER | CENTER | Aligns to the center of the control |
58 | Dali::Toolkit::Align::CENTER_END | CENTER_END | Aligns to the center of the vertical axis and end of the horizontal axis |
59 | Dali::Toolkit::Align::BOTTOM_BEGIN | BOTTOM_BEGIN | Aligns to the bottom of the vertical axis and the beginning of the horizontal axis|
60 | Dali::Toolkit::Align::BOTTOM_CENTER | BOTTOM_CENTER | Aligns to the bottom of the vertical axis and the center of the horizontal axis
61 | Dali::Toolkit::Align::BOTTOM_END | BOTTOM_END | Aligns to the bottom of the vertical axis and end of the horizontal axis |
62  
63 Visuals also have a custom **shader** property. Whilst it's possible to change the shader, please note that some visuals rely on the vertex shader to perform certain functions. For example, the NPatch visual uses the vertex shader to perform the stretching. The **shader** property is a Property::Map with the following keys:
64
65
66 | Property                                                  | String         | Type                       | Required | Description                                                                                |
67 |-----------------------------------------------------------|----------------|:--------------------------:|:--------:|--------------------------------------------------------------------------------------------|
68 | Dali::Toolkit::Visual::Shader::Property::VERTEX_SHADER    | vertexShader   | STRING or ARRAY of STRING  | No       | The vertex shader code. Can use an array of strings to split shader over multiple lines.   |
69 | Dali::Toolkit::Visual::Shader::Property::FRAGMENT_SHADER  | fragmentShader | STRING or ARRAY of STRING  | No       | The fragment shader code. Can use an array of strings to split shader over multiple lines. |
70 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_X | subdivideGridX | INTEGER                    | No       | How to subdivide the grid along the X-Axis. Defaults to 1.                                 |
71 | Dali::Toolkit::Visual::Shader::Property::SUBDIVIDE_GRID_Y | subdivideGridY | INTEGER                    | No       | How to subdivide the grid along the Y-Axis. Defaults to 1.                                 |
72 | Dali::Toolkit::Visual::Shader::Property::HINTS            | hints          | INTEGER or ARRAY of STRING | No       | Shader hints bitmask [More info](@ref shader-hints)                                        |
73
74 ## Shader hints {#shader-hints}
75
76 This is a bitmask giving hints to the renderer about what the shader does, in order to help the rendering system optimise it's rendering.
77
78 The bitmask can have the following values:
79
80 | Value | Description |
81 |-------------------------------------------|----------------------------------------|
82 | Dali::Shader::Hint::NONE | No hints |
83 | Dali::Shader::Hint::OUTPUT_IS_TRANSPARENT | Might generate transparent alpha from opaque inputs |
84 | Dali::Shader::Hint::MODIFIES_GEOMETRY | Might change the position of vertices - this disables culling optimizations |
85
86
87 See also Dali::Shader::Hint::Value enumeration.
88
89 ___________________________________________________________________________________________________
90
91 ## Color Visual {#color-visual}
92
93 Renders a color to the visual's quad geometry.
94  
95 ![ ](visuals/color-visual.png)
96
97 ### Properties Supported
98
99 **VisualType:** Dali::Toolkit::Visual::COLOR, "COLOR"
100
101 | Property                                        | String   | Type    | Required | Description               |
102 |-------------------------------------------------|----------|:-------:|:--------:|---------------------------|
103 | Dali::Toolkit::ColorVisual::Property::MIX_COLOR | mixColor | VECTOR4 | Yes      | The color required. |
104
105 ### Usage
106
107 ~~~{.cpp}
108 // C++
109 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
110
111 Dali::Property::Map map;
112 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::COLOR;
113 map[ ColorVisual::Property::MIX_COLOR ] = Color::RED;
114
115 control.SetProperty( Control::Property::BACKGROUND, map );
116 ~~~
117 ___________________________________________________________________________________________________
118
119 ## Gradient Visual {#gradient-visual}
120
121 Renders a smooth transition of colors to the visual's quad geometry.
122  
123 Both Linear and Radial gradients are supported.
124
125 | Linear | Radial |
126 |--------|--------|
127 | ![ ](visuals/linear-gradient-visual.png) | ![ ](visuals/radial-gradient-visual.png) |
128
129 ### Properties Supported
130
131 **VisualType:** Dali::Toolkit::Visual::GRADIENT, "GRADIENT"
132
133 | Property                                                | String        | Type              | Required   | Description                                                                                                      |
134 |---------------------------------------------------------|---------------|:-----------------:|:----------:|------------------------------------------------------------------------------------------------------------------|
135 | Dali::Toolkit::GradientVisual::Property::START_POSITION | startPosition | VECTOR2           | For Linear | The start position of the linear gradient.                                                                       |
136 | Dali::Toolkit::GradientVisual::Property::END_POSITION   | endPosition   | VECTOR2           | For Linear | The end position of the linear gradient.                                                                         |
137 | Dali::Toolkit::GradientVisual::Property::CENTER         | center        | VECTOR2           | For Radial | The center point of the gradient.                                                                                |
138 | Dali::Toolkit::GradientVisual::Property::RADIUS         | radius        | FLOAT             | For Radial | The size of the radius.                                                                                          |
139 | Dali::Toolkit::GradientVisual::Property::STOP_OFFSET    | stopOffset    | ARRAY of FLOAT    | No         | All the stop offsets. If not supplied default is 0.0 and 1.0.                                                    |
140 | Dali::Toolkit::GradientVisual::Property::STOP_COLOR     | stopColor     | ARRAY of VECTOR4  | Yes        | The color at those stop offsets. At least 2 required to show a gradient.                                         |
141 | Dali::Toolkit::GradientVisual::Property::UNITS          | units         | INTEGER or STRING | No         | Defines the coordinate system. [More info](@ref gradient-visual-units)                                           |
142 | Dali::Toolkit::GradientVisual::Property::SPREAD_METHOD  | spreadMethod  | INTEGER or STRING | No         | Indicates what happens if gradient starts or ends inside bounds. [More info](@ref gradient-visual-spread-method) |
143
144 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.
145
146 ### Units {#gradient-visual-units}
147
148 Defines the coordinate system for the attributes:
149  + Start (x1, y1) and End (x2 and y2) points of a line if using a linear gradient.
150  + Center point (cx, cy) and radius (r) of a circle if using a radial gradient.
151  
152 | Enumeration                                               | String              | Description                                                                                                                                    |
153 |-----------------------------------------------------------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
154 | Dali::Toolkit::GradientVisual::Units::OBJECT_BOUNDING_BOX | OBJECT_BOUNDING_BOX | *Default*. Uses the normals for the start, end & center points, i.e. top-left is (-0.5, -0.5) and bottom-right is (0.5, 0.5).                  |
155 | Dali::Toolkit::GradientVisual::Units::USER_SPACE          | USER_SPACE          | 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). |
156
157 ### Spread Method {#gradient-visual-spread-method}
158
159 Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
160
161 | Enumeration                                          | String  | Description                                                                                          |
162 |------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------|
163 | Dali::Toolkit::GradientVisual::SpreadMethod::PAD     | PAD     | *Default*. Uses the terminal colors of the gradient to fill the remainder of the quad geometry.               |
164 | Dali::Toolkit::GradientVisual::SpreadMethod::REFLECT | REFLECT | Reflect the gradient pattern start-to-end, end-to-start, start-to-end etc. until the quad geometry is filled. |
165 | Dali::Toolkit::GradientVisual::SpreadMethod::REPEAT  | REPEAT  | Repeat the gradient pattern start-to-end, start-to-end, start-to-end etc. until the quad geometry is filled.  |
166
167 ### Usage
168
169 **Linear:**
170 ~~~{.cpp}
171 // C++
172 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
173
174 Dali::Property::Map map;
175 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
176 map[ GradientVisual::Property::START_POSITION ] = Vector2( 0.5f, 0.5f );
177 map[ GradientVisual::Property::END_POSITION ] = Vector2( -0.5f, -0.5f );
178
179 Dali::Property::Array stopOffsets;
180 stopOffsets.PushBack( 0.0f );
181 stopOffsets.PushBack( 0.3f );
182 stopOffsets.PushBack( 0.6f );
183 stopOffsets.PushBack( 0.8f );
184 stopOffsets.PushBack( 1.f );
185 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
186
187 Dali::Property::Array stopColors;
188 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
189 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
190 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
191 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
192 stopColors.PushBack( Color::YELLOW );
193 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
194
195 control.SetProperty( Control::Property::BACKGROUND, map );
196 ~~~
197
198 **Radial:**
199 ~~~{.cpp}
200 // C++
201 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
202
203 Dali::Property::Map map;
204 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::GRADIENT;
205 map[ GradientVisual::Property::CENTER ] = Vector2( 0.5f, 0.5f );
206 map[ GradientVisual::Property::RADIUS ] = 1.414f;
207
208 Dali::Property::Array stopOffsets;
209 stopOffsets.PushBack( 0.0f );
210 stopOffsets.PushBack( 0.3f );
211 stopOffsets.PushBack( 0.6f );
212 stopOffsets.PushBack( 0.8f );
213 stopOffsets.PushBack( 1.f );
214 map[ GradientVisual::Property::STOP_OFFSET ] = stopOffsets;
215
216 Dali::Property::Array stopColors;
217 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 255.f )/255.f );
218 stopColors.PushBack( Vector4( 196.f, 198.f, 71.f, 122.f )/255.f );
219 stopColors.PushBack( Vector4( 214.f, 37.f, 139.f, 191.f )/255.f );
220 stopColors.PushBack( Vector4( 129.f, 198.f, 193.f, 150.f )/255.f );
221 stopColors.PushBack( Color::YELLOW );
222 map[ GradientVisual::Property::STOP_COLOR ] = stopColors;
223
224 control.SetProperty( Control::Property::BACKGROUND, map );
225 ~~~
226 ___________________________________________________________________________________________________
227
228 ## Image Visual {#image-visuals}
229
230 Renders an image into the visual's geometry.
231  
232 Depending on the extension of the image, a different visual is provided to render the image onto the screen.
233  
234  + [Normal (Quad)](@ref image-visual)
235  + [N-Patch](@ref n-patch-visual)
236  + [SVG](@ref svg-visual)
237  + [Animated Image]( @ref animated-image-visual )
238  
239 ___________________________
240  
241 ### Normal {#image-visual}
242  
243 Renders a raster image ( jpg, png etc.) into the visual's quad geometry.
244  
245 ![ ](visuals/image-visual.png)
246
247 #### Properties Supported
248
249 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
250
251 | Property                                             | String        | Type              | Required | Description                                                                                                              |
252 |------------------------------------------------------|---------------|:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------|
253 | Dali::Toolkit::ImageVisual::Property::URL            | url           | STRING            | Yes      | The URL of the image.                                                                                                    |
254 | Dali::Toolkit::ImageVisual::Property::FITTING_MODE   | fittingMode   | INTEGER or STRING | No       | Fitting options, used when resizing images to fit desired dimensions. [More info](@ref resourceimagescaling-fittingmode) |
255 | Dali::Toolkit::ImageVisual::Property::SAMPLING_MODE  | samplingMode  | INTEGER or STRING | No       | Filtering options, used when resizing images to sample original pixels. [More info](@ref resourceimagescaling-scaling)   |
256 | Dali::Toolkit::ImageVisual::Property::DESIRED_WIDTH  | desiredWidth  | INT               | No       | The desired image width. Will use actual image width if not specified.                                                   |
257 | Dali::Toolkit::ImageVisual::Property::DESIRED_HEIGHT | desiredHeight | INT               | No       | The desired image height. Will use actual image height if not specified.                                                 |
258 | Dali::Toolkit::ImageVisual::Property::PIXEL_AREA     | pixelArea     | VECTOR4           | No       | The image area to be displayed, default value is [0.0, 0.0, 1.0, 1.0]                                                    |
259 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_U    | wrapModeU     | INTEGER or STRING | No       | Wrap mode for u coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT                               |
260 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_V    | wrapModeV     | INTEGER or STRING | No       | Wrap mode for v coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT                               |
261
262 #### Usage
263
264 ~~~{.cpp}
265 // C++
266 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
267
268 Dali::Property::Map map;
269 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
270 map[ ImageVisual::Property::URL ] = "path-to-image.jpg";
271
272 control.SetProperty( Control::Property::BACKGROUND, map );
273 ~~~
274 ___________________________________________________________________________________________________
275
276 ### N-Patch {#n-patch-visual}
277
278 Renders an n-patch or a 9-patch image. Uses non-quad geometry. Both geometry and texture are cached to reduce memory consumption if the same n-patch image is used elsewhere.
279  
280 ![ ](visuals/n-patch-visual.png)
281
282 #### Properties Supported
283
284 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
285
286 | Property                                          | String        | Type    | Required | Description                      |
287 |---------------------------------------------------|---------------|:-------:|:--------:|----------------------------------|
288 | Dali::Toolkit::ImageVisual::Property::URL         | url           | STRING  | Yes      | The URL of the n-patch image.    |
289 | Dali::Toolkit::ImageVisual::Property::BORDER_ONLY | borderOnly    | BOOLEAN | No       | If true, only draws the borders. |
290
291 #### Usage
292
293 ~~~{.cpp}
294 // C++
295 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
296
297 Dali::Property::Map map;
298
299 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
300 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.9.png";
301
302 control.SetProperty( Control::Property::BACKGROUND, map );
303 ~~~
304 ___________________________________________________________________________________________________
305
306 ### SVG {#svg-visual}
307
308 Renders a svg image into the visual's quad geometry.
309  
310 #### Features: SVG Tiny 1.2 specification
311
312 **supported:**
313  
314   * basic shapes
315   * paths
316   * solid color fill
317   * gradient color fill
318   * solid color stroke
319  
320 **not supported:**
321  
322   * gradient color stroke
323   * dash array stroke
324   * view box
325   * text
326   * clip path
327
328 <div style="width:300px">
329  
330  
331 </div>
332  
333 <div style="width:300px">
334  
335 ![ ](visuals/svg-visual.svg)
336  
337 </div>
338
339  
340 #### Properties Supported
341
342 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
343
344 | Property                                  | String | Type    | Required | Description                      |
345 |-------------------------------------------|--------|:-------:|:--------:|----------------------------------|
346 | Dali::Toolkit::ImageVisual::Property::URL | url    | STRING  | Yes      | The URL of the SVG image.    |
347
348 #### Usage
349
350 ~~~{.cpp}
351 // C++
352 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
353
354 Dali::Property::Map map;
355
356 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::IMAGE;
357 map[ Dali::Toolkit::ImageVisual::Property::URL ] = "path-to-image.svg";
358
359 control.SetSize( 200.f, 200.f );
360 control.SetProperty( Control::Property::BACKGROUND, map );
361 ~~~
362 ___________________________________________________________________________________________________
363
364 ## Animated Image Visual {#animated-image-visual}
365
366 Renders an animated image into the visual's quad geometry. Currently, only the GIF format is supported.
367
368 ![ ](animated-image-visual.gif)
369
370 #### Properties Supported
371
372 **VisualType:** Dali::Toolkit::Visual::IMAGE, "IMAGE"
373
374 | Property                                          | String     | Type              | Required | Description                                                                                  |
375 |---------------------------------------------------|------------|:-----------------:|:--------:|----------------------------------------------------------------------------------------------|
376 | Dali::Toolkit::ImageVisual::Property::URL         | url        | STRING            | Yes      | The URL of the animated image.                                                               |
377 | Dali::Toolkit::ImageVisual::Property::PIXEL_AREA  | pixelArea  | VECTOR4           | No       | The image area to be displayed, default value is [0.0, 0.0, 1.0, 1.0]                        |
378 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_U | wrapModeU  | INTEGER or STRING | No       | Wrap mode for u coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT |
379 | Dali::Toolkit::ImageVisual::Property::WRAP_MODE_V | wrapModeV  | INTEGER or STRING | No       | Wrap mode for v coordinate, valid values are CLAMP_TO_EDGE(default), REPEAT, MIRRORED_REPEAT |
380
381 #### Usage
382
383 ~~~{.cpp}
384 // C++
385 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
386
387 control.SetProperty( Control::Property::BACKGROUND,
388                      Property::Map().Add( Visual::Property::TYPE, Dali::Toolkit::Visual::IMAGE )
389                                     .Add( Dali::Toolkit::ImageVisual::Property::URL, "path-to-image.gif" ) );
390 ~~~
391 ___________________________________________________________________________________________________
392
393 ## Border Visual {#border-visual}
394
395 Renders a color as an internal border to the visual's geometry.
396  
397 ![ ](visuals/border-visual.png)
398
399 ### Properties Supported
400
401 **VisualType:** Dali::Toolkit::Visual::BORDER, "BORDER"
402
403 | Property                                             | String        | Type    | Required | Description                                      |
404 |------------------------------------------------------|---------------|:-------:|:--------:|--------------------------------------------------|
405 | Dali::Toolkit::BorderVisual::Property::COLOR         | borderColor   | VECTOR4 | Yes      | The color of the border.                         |
406 | Dali::Toolkit::BorderVisual::Property::SIZE          | borderSize    | FLOAT   | Yes      | The width of the border (in pixels).             |
407 | Dali::Toolkit::BorderVisual::Property::ANTI_ALIASING | antiAliasing  | BOOLEAN | No       | Whether anti-aliasing of the border is required. |
408
409 ### Usage
410
411 ~~~{.cpp}
412 // C++
413 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
414
415 Dali::Property::Map map;
416
417 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::BORDER;
418 map[ BorderVisual::Property::COLOR ] = Color::BLUE;
419 map[ BorderVisual::Property::SIZE ] = 5.0f;
420
421 control.SetProperty( Control::Property::BACKGROUND, map );
422 ~~~
423 ___________________________________________________________________________________________________
424
425 ## Mesh Visual {#mesh-visual}
426
427 Renders a mesh using a .obj file, optionally with textures provided by a mtl file. Scaled to fit the control.
428  
429 ![ ](visuals/mesh-visual.png)
430  
431 ### Properties Supported
432  
433 **VisualType:** Dali::Toolkit::Visual::MESH, "MESH"
434
435 | Property                                              | String         | Type               | Required          | Description                                                                                      |
436 |-------------------------------------------------------|----------------|:------------------:|:-----------------:|--------------------------------------------------------------------------------------------------|
437 | Dali::Toolkit::MeshVisual::Property::OBJECT_URL       | objectUrl      | STRING             | Yes               | The location of the ".obj" file.                                                                 |
438 | Dali::Toolkit::MeshVisual::Property::MATERIAL_URL     | materialUrl    | STRING             | No                | The location of the ".mtl" file. Leave blank for a textureless object.                           |
439 | Dali::Toolkit::MeshVisual::Property::TEXTURES_PATH    | texturesPath   | STRING             | If using material | Path to the directory the textures (including gloss and normal) are stored in.                   |
440 | Dali::Toolkit::MeshVisual::Property::SHADING_MODE     | shadingMode    | INTEGER or STRING  | No                | Sets the type of shading mode that the mesh will use. [More info](@ref mesh-visual-shading-mode) |
441 | Dali::Toolkit::MeshVisual::Property::USE_MIPMAPPING   | useMipmapping  | BOOLEAN            | No                | Flag for whether to use mipmaps for textures or not. Default true.                               |
442 | Dali::Toolkit::MeshVisual::Property::USE_SOFT_NORMALS | useSoftNormals | BOOLEAN            | No                | Flag for whether to average normals at each point to smooth textures or not. Default true.       |
443 | Dali::Toolkit::MeshVisual::Property::LIGHT_POSITION   | lightPosition  | VECTOR3            | No                | The position, in stage space, of the point light that applies lighting to the model.             |
444  
445 ### Shading Mode {#mesh-visual-shading-mode}
446
447 When specifying the shading mode, if anything the mode requires is missing, a simpler mode that can be handled with what has been supplied will be used instead.
448  
449 **Possible values:**
450  
451 | Enumeration                                                                     | String                                   | Description                                                                                                             |
452 |---------------------------------------------------------------------------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
453 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURELESS_WITH_DIFFUSE_LIGHTING        | TEXTURELESS_WITH_DIFFUSE_LIGHTING        | *Simplest*. One color that is lit by ambient and diffuse lighting.                                                      |
454 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURED_WITH_SPECULAR_LIGHTING          | TEXTURED_WITH_SPECULAR_LIGHTING          | Uses only the visual image textures provided with specular lighting in addition to ambient and diffuse lighting.        |
455 | Dali::Toolkit::MeshVisual::ShaderType::TEXTURED_WITH_DETAILED_SPECULAR_LIGHTING | TEXTURED_WITH_DETAILED_SPECULAR_LIGHTING | Uses all textures provided including a gloss, normal and texture map along with specular, ambient and diffuse lighting. |
456
457 ### Usage
458
459 ~~~{.cpp}
460 // C++
461 Dali::Stage stage = Dali::Stage::GetCurrent();
462 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
463
464 Dali::Property::Map map;
465
466 map[ Visual::Property::TYPE  ] = Dali::Toolkit::Visual::MESH;
467 map[ MeshVisual::Property::OBJECT_URL ] = "home/models/Dino.obj";
468 map[ MeshVisual::Property::MATERIAL_URL ] = "home/models/Dino.mtl";
469 map[ MeshVisual::Property::TEXTURES_PATH ] = "home/images/";
470
471 control.SetProperty( Control::Property::BACKGROUND, map );
472 ~~~
473
474 ___________________________________________________________________________________________________
475
476 ## Primitive Visual {#primitive-visual}
477
478 Renders a simple 3D shape, such as a cube or sphere. Scaled to fit the control.
479
480 The shapes are generated with clockwise winding and back-face culling on by default.
481
482 ![ ](visuals/cube.png)
483  
484 ### Properties Supported
485
486 **VisualType:** Dali::Toolkit::Visual::PRIMITIVE, "PRIMITIVE"
487
488 | Property                                                      | String            | Type               | Description                                                                                                     | Default Value                                           | Range                          |
489 |---------------------------------------------------------------|-------------------|:------------------:|-----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------:|:------------------------------:|
490 | Dali::Toolkit::PrimitiveVisual::Property::SHAPE               | shape             | INTEGER or STRING  | The specific shape to render. [More info](@ref shape-details)                                                   | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE, "SPHERE" | [See list](@ref shape-details) |
491 | Dali::Toolkit::PrimitiveVisual::Property::MIX_COLOR           | mixColor          | VECTOR4            | The color of the shape.                                                                                         | (0.5, 0.5, 0.5, 1.0)                                    | 0.0 - 1.0 for each             |
492 | Dali::Toolkit::PrimitiveVisual::Property::SLICES              | slices            | INTEGER            | The number of slices as you go around the shape. [More info](@ref slices-details)                               | 128                                                     | 1 - 255                        |
493 | Dali::Toolkit::PrimitiveVisual::Property::STACKS              | stacks            | INTEGER            | The number of stacks as you go down the shape. [More info](@ref stacks-details)                                 | 128                                                     | 1 - 255                        |
494 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_TOP_RADIUS    | scaleTopRadius    | FLOAT              | The scale of the radius of the top circle of a conical frustrum.                                                | 1.0                                                     | ≥ 0.0                          |
495 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS | scaleBottomRadius | FLOAT              | The scale of the radius of the bottom circle of a conical frustrum.                                             | 1.5                                                     | ≥ 0.0                          |
496 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_HEIGHT        | scaleHeight       | FLOAT              | The scale of the height of a conic.                                                                             | 3.0                                                     | > 0.0                          |
497 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_RADIUS        | scaleRadius       | FLOAT              | The scale of the radius of a cylinder.                                                                          | 1.0                                                     | > 0.0                          |
498 | Dali::Toolkit::PrimitiveVisual::Property::SCALE_DIMENSIONS    | scaleDimensions   | VECTOR3            | The dimensions of a cuboid. Scales in the same fashion as a 9-patch image.                                      | Vector3::ONE                                            | > 0.0 for each                 |
499 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_PERCENTAGE    | bevelPercentage   | FLOAT              | Determines how bevelled the cuboid should be, based off the smallest dimension. [More info](@ref bevel-details) | 0.0 (no bevel)                                          | 0.0 - 1.0                      |
500 | Dali::Toolkit::PrimitiveVisual::Property::BEVEL_SMOOTHNESS    | bevelSmoothness   | FLOAT              | Defines how smooth the bevelled edges should be.                                                                | 0.0 (sharp edges)                                       | 0.0 - 1.0                      |
501 | Dali::Toolkit::PrimitiveVisual::Property::LIGHT_POSITION      | lightPosition     | VECTOR3            | The position, in stage space, of the point light that applies lighting to the model.                            | (Offset outwards from the center of the screen.)        | Unlimited                      |
502
503 ### Shapes {#shape-details}
504
505 There are six shapes that can be chosen, some of which are simplified specialisations of another.
506
507 | Enumeration                                             | String           | Description                                                                       | Parameters                                                    |
508 |---------------------------------------------------------|------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------|
509 | Dali::Toolkit::PrimitiveVisual::Shape::SPHERE           | SPHERE           | *Default*.                                                                        | color, slices, stacks                                         |
510 | Dali::Toolkit::PrimitiveVisual::Shape::CONICAL_FRUSTRUM | CONICAL_FRUSTRUM | The area bound between two circles, i.e. a cone with the tip removed.             | color, scaleTopRadius, scaleBottomRadius, scaleHeight, slices |
511 | Dali::Toolkit::PrimitiveVisual::Shape::CONE             | CONE             | Equivalent to a conical frustrum with top radius of zero.                         | color, scaleBottomRadius, scaleHeight, slices                 |
512 | Dali::Toolkit::PrimitiveVisual::Shape::CYLINDER         | CYLINDER         | Equivalent to a conical frustrum with equal radii for the top and bottom circles. | color, scaleRadius, scaleHeight, slices                       |
513 | Dali::Toolkit::PrimitiveVisual::Shape::CUBE             | CUBE             | Equivalent to a bevelled cube with a bevel percentage of zero.                    | color, scaleDimensions                                        |
514 | Dali::Toolkit::PrimitiveVisual::Shape::OCTAHEDRON       | OCTAHEDRON       | Equivalent to a bevelled cube with a bevel percentage of one.                     | color, scaleDimensions                                        |
515 | Dali::Toolkit::PrimitiveVisual::Shape::BEVELLED_CUBE    | BEVELLED_CUBE    | A cube/cuboid with all edges flattened to some degree.                            | color, scaleDimensions, bevelPercentage, bevelSmoothness      |
516
517 #### Examples below:
518
519 **sphere:**
520  
521 ![ ](visuals/sphere.png)
522  
523 **conics:**
524  
525 | Frustrum | Cone | Cylinder |
526 |----------|------|----------|
527 | ![ ](visuals/conical-frustrum.png) | ![ ](visuals/cone.png) | ![ ](visuals/cylinder.png) |
528  
529 ### Bevel {#bevel-details}
530  
531 Bevel percentage ranges from 0.0 to 1.0. It affects the ratio of the outer face widths to the width of the overall cube, as shown:
532  
533 | 0.0 ( cube) | 0.3 | 0.7 | 1.0 (octahedron) |
534 |-------------|-----|-----|------------------|
535 | ![ ](visuals/cube.png) | ![ ](visuals/bevelled-cube-low.png) | ![ ](visuals/bevelled-cube-high.png) | ![ ](visuals/octahedron.png) |
536  
537 ### Slices {#slices-details}
538  
539 For spheres and conical frustrums, 'slices' determines how many divisions there are as you go around the object.
540  
541 ![ ](visuals/slices.png)
542  
543 ### Stacks {#stacks-details}
544  
545 For spheres, 'stacks' determines how many layers there are as you go down the object.
546  
547 ![ ](visuals/stacks.png)
548  
549 ### Usage
550  
551 **sphere**
552  
553 ~~~{.cpp}
554 // C++
555 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
556
557 Dali::Property::Map map;
558
559 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
560 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::SPHERE;
561 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
562
563 control.SetProperty( Control::Property::BACKGROUND, map );
564 ~~~
565
566 **conical frustrum**
567
568 ~~~{.cpp}
569 // C++
570 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
571
572 Dali::Property::Map map;
573
574 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
575 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::CONICAL_FRUSTRUM;
576 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
577 map[ PrimitiveVisual::Property::SCALE_TOP_RADIUS ] = 1.0f;
578 map[ PrimitiveVisual::Property::SCALE_BOTTOM_RADIUS ] = 1.5f;
579 map[ PrimitiveVisual::Property::SCALE_HEIGHT ] = 3.0f;
580
581 control.SetProperty( Control::Property::BACKGROUND, map );
582 ~~~
583
584 **bevelled cube**
585
586 ~~~{.cpp}
587 // C++
588 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
589
590 Dali::Property::Map map;
591
592 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::PRIMITIVE;
593 map[ PrimitiveVisual::Property::SHAPE ] = PrimitiveVisual::Shape::BEVELLED_CUBE;
594 map[ PrimitiveVisual::Property::MIX_COLOR ] = Vector4( 1.0, 0.5, 0.0, 1.0 );
595 map[ PrimitiveVisual::Property::BEVEL_PERCENTAGE ] = 0.4f;
596
597 control.SetProperty( Control::Property::BACKGROUND, map );
598 ~~~
599 ___________________________________________________________________________________________________
600
601 ## Text Visual {#text-visual}
602
603 Renders text within a control.
604
605 ![ ](visuals/HelloWorld.png)
606
607 ### Properties
608
609 **VisualType:** Dali::Toolkit::Visual::TEXT, "TEXT"
610
611 | Property                                                    | String              | Type          | Required | Description                                                                   | Default                |
612 |-------------------------------------------------------------|---------------------|:-------------:|:--------:|-------------------------------------------------------------------------------|------------------------|
613 | Dali::Toolkit::TextVisual::Property::TEXT                   | text                | STRING        | Yes      | The text to display in UTF-8 format                                           |                        |
614 | Dali::Toolkit::TextVisual::Property::FONT_FAMILY            | fontFamily          | STRING        | No       | The requested font family to use                                              |                        |
615 | Dali::Toolkit::TextVisual::Property::FONT_STYLE             | fontStyle           | MAP           | No       | The requested font style to use                                               |                        |
616 | Dali::Toolkit::TextVisual::Property::POINT_SIZE             | pointSize           | FLOAT         | Yes      | The size of font in points                                                    |                        |
617 | Dali::Toolkit::TextVisual::Property::MULTI_LINE             | multiLine           | BOOLEAN       | No       | The single-line or multi-line layout option                                   | false                  |
618 | Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT   | horizontalAlignment | STRING        | No       | The line horizontal alignment: "BEGIN", "CENTER", "END"                       | "BEGIN"                |
619 | Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT     | verticalAlignment   | STRING        | No       | The line vertical alignment: "TOP",   "CENTER", "BOTTOM"                      | "TOP"                  |
620 | Dali::Toolkit::TextVisual::Property::TEXT_COLOR             | textColor           | VECTOR4       | No       | The color of the text                                                         | Color::BLACK           |
621 | Dali::Toolkit::TextVisual::Property::ENABLE_MARKUP         | enableMarkup           | BOOL       | No       | If mark up should be enabled |                                                        |
622
623 ### Usage
624
625 ~~~{.cpp}
626     // C++
627     Dali::Stage stage = Dali::Stage::GetCurrent();
628     stage.SetBackgroundColor( Dali::Color::WHITE );
629
630     Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
631     control.SetParentOrigin( ParentOrigin::CENTER );
632
633     Dali::Property::Map map;
634     map[ Dali::Toolkit::Visual::Property::TYPE ] = Dali::Toolkit::Visual::TEXT;
635     map[ Dali::Toolkit::TextVisual::Property::TEXT ] = "Hello world";
636     map[ Dali::Toolkit::TextVisual::Property::TEXT_COLOR ] = Dali::Color::BLACK;
637     map[ Dali::Toolkit::TextVisual::Property::FONT_FAMILY ] = "Sans";
638     map[ Dali::Toolkit::TextVisual::Property::POINT_SIZE ] = 30.f;
639     map[ Dali::Toolkit::TextVisual::Property::HORIZONTAL_ALIGNMENT ] = "CENTER";
640     map[ Dali::Toolkit::TextVisual::Property::VERTICAL_ALIGNMENT ] = "CENTER";
641
642     control.SetProperty( Dali::Toolkit::Control::Property::BACKGROUND, map );
643
644     stage.Add( control );
645 ~~~
646
647 ## Wireframe Visual {#wireframe-visual}
648
649 Renders a wireframe around a quad geometry.
650 Is mainly used for debugging and is the visual that replaces all other visuals when [Visual Debug Rendering](@ref debugrendering) is turned on.
651  
652 ![ ](visuals/wireframe-visual.png)
653
654 ### Properties
655
656 **VisualType:** Dali::Toolkit::Visual::WIREFRAME, "WIREFRAME"
657
658 ### Usage
659
660 ~~~{.cpp}
661 // C++
662 Dali::Toolkit::Control control = Dali::Toolkit::Control::New();
663
664 Dali::Property::Map map;
665 map[ Visual::Property::TYPE ] = Dali::Toolkit::Visual::WIREFRAME;
666
667 control.SetProperty( Control::Property::BACKGROUND, map );
668 ~~~
669
670
671
672 */