summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas_Eo.h
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2017-05-03 12:38:41 +0200
committerStefan Schmidt <stefan@osg.samsung.com>2017-05-03 12:38:41 +0200
commit910c316c1740bf3965ccb227e74fbbeea12a8fdf (patch)
tree1dbee6a1a47752ac447f40419fc5e3724f5cbc24 /src/lib/evas/Evas_Eo.h
parentccd78c7708acbd7a737eb3c506355387dadf643b (diff)
evas: Rewrite Evas Eo documentation
Summary: Cleans up grammar, simplifies wording, and elaborates on some details for better clarity. Assume the reader will already have a basic understanding of reference counting and 3D graphics in order to avoid overexplaining these concepts. Subscribers: cedric, jpeg Differential Revision: https://phab.enlightenment.org/D4837
Diffstat (limited to 'src/lib/evas/Evas_Eo.h')
-rw-r--r--src/lib/evas/Evas_Eo.h175
1 files changed, 89 insertions, 86 deletions
diff --git a/src/lib/evas/Evas_Eo.h b/src/lib/evas/Evas_Eo.h
index e3ec81b936..2b72b15561 100644
--- a/src/lib/evas/Evas_Eo.h
+++ b/src/lib/evas/Evas_Eo.h
@@ -87,33 +87,23 @@
87 * @section evas_canvas3d_intro Introduction 87 * @section evas_canvas3d_intro Introduction
88 * 88 *
89 * Evas 3D is an extension to support 3D scene graph rendering into 2D Evas 89 * Evas 3D is an extension to support 3D scene graph rendering into 2D Evas
90 * canvases, supporting typical tree-based scene graph manipulation and other 3D 90 * canvases, with tree-based scene graph manipulation and other typical 3D
91 * graphics rendering techniques. 91 * rendering techniques.
92 * 92 *
93 * Evas 3D provides 3D objects that are used for describing 3D scene and APIs 93 * 3D objects are used to describe three dimensional scenes and to provide
94 * to connect the scene with an evas image object so that the scene is rendered 94 * interfaces to connect the scene to an Evas image object for rendering.
95 * on that image object. 95 *
96 * 96 * Scenes are constructed by locating cameras and lights and selecting desired
97 * Construction of a 3D scene is a process of locating desired cameras, lights and 97 * meshes, and organizing Node objects into hierarchical n-ary tree data structures.
98 * meshes in the scene. Typically the scene is structured with some hierarchical 98 * The scene is stacked on the canvas with existing Evas objects, which permits
99 * data structure. Evas 3D supports n-ary tree structures for describing the 99 * intermingling 3D rendered content in existing 2D application layouts.
100 * scene. Node is used to build the tree representation of the scene. Other 100 *
101 * objects, like camera, light and mesh can be located in the scene by being 101 * Rendering techniques supported by Evas 3D include flat and phong
102 * contained in a node. 102 * shading, normal and texture mapping, and triangle meshes. Existing
103 * 103 * Evas objects may also be used as textures inside the 3D scene,
104 * Like other 3D graphics engines, Evas 3D supports standard 3D rendering methods 104 * including EFL widgets and even application windows. This latter
105 * like flat shading, phong shading and normal map and other features like 105 * capability makes it possible to create a 3D version of an arbitrary
106 * texture mapping and triangle meshes. 106 * EFL application with minimal code changes.
107 *
108 * Besides all the traditional 3D rendering things, one of the key features of
109 * the Evas 3D is that it is able to use existing evas objects as textures
110 * inside of the 3D scene. "Existing evas objects" means all the EFL widgets
111 * and applications. By supporting this, it is easy to make a 3D version of an
112 * application without modifying the original source that much.
113 *
114 * Also, 3D scene can be located on the canvas naturally stacked with existing
115 * evas objects. This can make it possible to put 3D things into existing 2D
116 * application layouts.
117 * 107 *
118 * @section evas_canvas3d_example Introductory Example 108 * @section evas_canvas3d_example Introductory Example
119 * 109 *
@@ -131,118 +121,131 @@
131 * @defgroup Evas_Canvas3D_Object Generic 3D Object Descriptions 121 * @defgroup Evas_Canvas3D_Object Generic 3D Object Descriptions
132 * @ingroup Evas_3D 122 * @ingroup Evas_3D
133 * 123 *
134 * Evas 3D object is a generic type of all evas 3D objects like scenes, nodes, 124 * The Evas_Canvas3D_Object structure is an abstract base for other Evas
135 * cameras, lights, meshes, textures and materials. Evas 3D object is basically 125 * 3D objects (scenes, nodes, lights, meshes, textures, and materials)
136 * reference counted. Any successful function call on an object that makes a 126 * with reference counting and propagation of modifications via
137 * reference to another object will increase the reference count. When the 127 * reference tracking. This permits, for example, when a scene object
138 * reference count gets to 0, the object will be actually deleted. 128 * is modified (marked dirty), a number of image objects rendering that
139 * 129 * object to be notified to update themselves, without needing to call
140 * Any modifications are automatically propagated to other objects referencing 130 * update functions manually.
141 * the modified objects. As a result, if the scene object is set to a modified
142 * state, all image objects having the scene as a rendering source are marked
143 * as dirty, so that rendering will be updated at next frame. But all these
144 * things are done internally, so feel free to forget about calling some kind
145 * of update functions.
146 */ 131 */
147 132
148/** 133/**
149 * @defgroup Evas_Canvas3D_Scene Scene Object 134 * @defgroup Evas_Canvas3D_Scene Scene Object
150 * @ingroup Evas_3D 135 * @ingroup Evas_3D
151 * 136 *
152 * A scene represents a captured image of a scene graph through its viewing 137 * The Evas_Canvas3D_Scene structure represents a captured image of a
153 * camera. A scene can be set to an image object to be displayed on the Evas 138 * scene graph through its viewing camera. A scene can be associated
154 * canvas by using evas_object_image_scene_set() function. 139 * with an image object for canvas display via the
140 * evas_object_image_scene_set() function.
155 */ 141 */
156 142
157/** 143/**
158 * @defgroup Evas_Canvas3D_Node Node Object 144 * @defgroup Evas_Canvas3D_Node Node Object
159 * @ingroup Evas_3D 145 * @ingroup Evas_3D
160 * 146 *
161 * A node is used for hierarchical construction of a scene graph. Evas 3D 147 * The Evas_Canvas3D_Node structure defines the position, orientation,
162 * provides n-ary tree structures for the scene graph construction. A node has 148 * and scale of canvas objects (cameras, lights, meshes, etc.) in a 3D
163 * its position, orientation and scale. Other objects, like cameras, lights and 149 * space. These nodes can be organized into a hierarchical n-ary tree
164 * meshes can be contained in a node to be located in a 3D space. 150 * structure to construct a scene graph.
165 */ 151 */
166 152
167/** 153/**
168 * @defgroup Evas_Canvas3D_Camera Camera Object 154 * @defgroup Evas_Canvas3D_Camera Camera Object
169 * @ingroup Evas_3D 155 * @ingroup Evas_3D
170 * 156 *
171 * A camera object is used for taking a picture of a scene graph. A camera 157 * The Evas_Canvas3D_Camera structure defines properties used to
172 * object itself is just a set of properties on how the camera should take the 158 * generate 2D pictures of a given scene graph, similar in concept to
173 * picture (like focus length and film size of the real world cameras). To be 159 * focus length and film size for a real world camera.
174 * able to take a shot of the scene, a camera should be located in the scene, so 160 *
175 * that it has its viewing position and direction. It is done by containing the 161 * A given camera definition can be used to take multiple pictures of
176 * camera on a node. If one wants to locate several cameras having same 162 * the scene by establishing multiple nodes for the
177 * properties, instead of creating multiple cameras, just create one camera and 163 * Evas_Canvas3D_Camera, each of which are located at different
178 * multiple nodes containing the camera and locate them at each desired position 164 * positions and with different orientations. Convenience routines
179 * and direction. Just for convenience, use evas_canvas3d_node_position_set() to move 165 * evas_canvas3d_node_position_set() and
180 * the camera to desired position and use evas_canvas3d_node_look_at_set() to adjust 166 * evas_canvas3d_node_look_at_set() are provided to adjust the position
181 * the viewing direction of the camera. 167 * and viewing direction for these nodes.
182 */ 168 */
183 169
184/** 170/**
185 * @defgroup Evas_Canvas3D_Light Light Object 171 * @defgroup Evas_Canvas3D_Light Light Object
186 * @ingroup Evas_3D 172 * @ingroup Evas_3D
187 * 173 *
188 * A light object represents a set of properties of a light source. Evas 3D 174 * The Evas_Canvas3D_Light structure defines various light source
189 * provides standard reflection model that of ambient, diffuse and specular 175 * properties. Reflection models include: Ambient, diffuse, and
190 * reflection model. Also, Evas 3D support 3 types of light models: directional, 176 * specular. Light models include directional, point, and spot. The
191 * point and spot light. Light position and direction is determined by the node 177 * position and direction for the light is tracked by the node that
192 * containing the light. 178 * contains the light.
193 */ 179 */
194 180
195/** 181/**
196 * @defgroup Evas_Canvas3D_Mesh Mesh Object 182 * @defgroup Evas_Canvas3D_Mesh Mesh Object
197 * @ingroup Evas_3D 183 * @ingroup Evas_3D
198 * 184 *
199 * A mesh object is a set of information on a visible geometrical object like 185 * The Evas_Canvas3D_Mesh structure manages key-frame based mesh
200 * character models, terrains or other structures and entities. Evas 3D supports 186 * animations for geometrical objects like character models, terrain,
201 * key-frame-based mesh animation, so a mesh can have multiple frames and each 187 * buildings, and other such visible objects. Each mesh frame can have
202 * frame has its own material and geometric data. Like other data objects, a 188 * its own material and geometric data. Blending functions, fog
203 * mesh can be located on a scene by being contained in a node. The mesh is 189 * effects, level of detail boundaries, and shadow properties are also
204 * transformed from its modeling coordinate space into the node's coordinate 190 * supported.
205 * space. Also, the frame number is saved in the containing node. So, one can 191 *
206 * locate multiple nodes having same mesh object with different animation frames 192 * Like other data objects, a mesh definition is located and oriented in
207 * and transforms. Unlike camera and light objects, multiple meshes can be 193 * the canvas with one or more nodes, with the mesh transformed from its
208 * contained in a single node. 194 * modeling coordinate space to the node's coordinate space. The frame
195 * number is also tracked by the node, permitting creation of multiple
196 * nodes in the canvas each set to a different animation frame, for
197 * example.
198 *
199 * Unlike camera and light objects, multiple meshes can be contained in
200 * a single node.
209 */ 201 */
210 202
211/** 203/**
212 * @defgroup Evas_Canvas3D_Primitive Primitive Object 204 * @defgroup Evas_Canvas3D_Primitive Primitive Object
213 * @ingroup Evas_3D 205 * @ingroup Evas_3D
214 * 206 *
215 * A primitive object is an object with necessary data for creating 207 * The Evas_Canvas3D_Primitive structure defines the data for
216 * meshes with primitive shapes. Data from a primitive can be set to 208 * generating meshes for various types of primitive shapes such as
217 * Evas_Canvas3D_Mesh by using evas_canvas3d_mesh_from_primitive_set() 209 * cubes, cylinders, spheres, surfaces, terrain, etc. Use the
218 * function. 210 * evas_canvas3d_mesh_from_primitive_set() function to generate a
211 * mesh's frame of this primitive.
219 */ 212 */
220 213
221/** 214/**
222 * @defgroup Evas_Canvas3D_Texture Texture Object 215 * @defgroup Evas_Canvas3D_Texture Texture Object
223 * @ingroup Evas_3D 216 * @ingroup Evas_3D
224 * 217 *
225 * A texture object is an image represents material of surfaces. A texture can 218 * The Evas_Canvas3D_Texture structure associates a 2D bitmap image to a
226 * be set to a slot of Evas_Canvas3D_Material by using evas_canvas3d_material_texture_set() 219 * material for a surface. Image data for the texture can be loaded
227 * function. The data of a texture can be loaded from memory, file and other 220 * from memory, a file, or an Evas_Object. Use the
228 * Evas_Object. 221 * evas_canvas3d_material_texture_set() function to add the texture to
222 * an Evas_Canvas3DMaterial's slot.
229 */ 223 */
230 224
231/** 225/**
232 * @defgroup Evas_Canvas3D_Material Material Object 226 * @defgroup Evas_Canvas3D_Material Material Object
233 * @ingroup Evas_3D 227 * @ingroup Evas_3D
234 * 228 *
235 * A material object represents properties of surfaces. Evas 3D defines the 229 * The Evas_Canvas3D_Material structure defines a set of material
236 * properties with 5 material attributes, ambient, diffuse, specular emission 230 * attributes used for determining the color of mesh surfaces. Each
237 * and normal. Each attribute has its own color value and texture map. Materials 231 * attribute is defined by a color value and texture map. The five
238 * are used to determine the color of mesh surfaces. 232 * attributes are: ambient, diffuse, specular, emission, and normal.
239 */ 233 */
240 234
241/** 235/**
242 * @typedef Evas_Canvas3D_Surface_Func 236 * @typedef Evas_Canvas3D_Surface_Func
243 * 237 *
244 * User-defined parametric surface function. 238 * The Evas_Canvas3D_Surface_Func type of functions are used to
245 * Used for easy creation of custom surfaces as a primitive. 239 * create parametric surfaces as primitives. These compute the
240 * vertex x,y,z values for given v,u values.
241 *
242 * @param out_x The x component of the calculated value.
243 * @param out_y The y component of the calculated value.
244 * @param out_z The z component of the calculated value.
245 * @param a is the v value.
246 * @param b is the u value.
247
248 * @see Evas_Canvas3D_Primitive
246 * 249 *
247 * @since 1.15 250 * @since 1.15
248 * @ingroup Evas_Canvas3D_Primitive 251 * @ingroup Evas_Canvas3D_Primitive