summaryrefslogtreecommitdiff
path: root/legacy/ephysics/doc/examples.dox
blob: 10f63b92b2c670ec2643b937dcba4e6105c49b6a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
/**
 * @page Examples Examples
 *
 * Here is a page with examples.
 *
 * @li @ref tutorial_ephysics_bouncing_ball
 * @li @ref tutorial_ephysics_delete_body
 * @li @ref tutorial_ephysics_constraint
 */

/**
 * @page tutorial_ephysics_bouncing_ball EPhysics - Bouncing Ball
 *
 * The purpose of this example is to show how to write an simple application -
 * as the name suggests - with a small ball bouncing on the ground and
 * responding to users events by making it jump - applying a central impulse on
 * it.
 *
 * We'll guide you on defining a EPhysics world, defining its render geometry
 * and the physics limiting boundaries, you'll learn how to add EPhysics bodies
 * and how to associate it to evas objects.  We also explain how to change
 * restitution and friction properties. We see how to apply central impulse on
 * a EPhysics_Body by implementing an elementary input event callback and
 * calling the proper function.
 *
 * @section test-structure A test struct
 * @dontinclude ephysics_test.h
 *
 * While in this example we'll be working with a struct to hold some objects in
 * our code. For clarity sake we present you the struct declaration in the
 * following block.
 *
 *
 * @skip struct _Test_Data
 * @until };
 *
 * @section world-new World Initialization 
 * @dontinclude test_bouncing_ball.c
 *
 * Calling ephysics_world_new()
 * will create a new physics world with its collision configuration, constraint
 * solver, broadphase interface and dispatcher.
 *
 * The default gravity is set to -9.81. It's possible to stop a running world
 * but its default status is running. Take a look at
 * ephysics_world_running_set() for further informations about world running
 * status.
 *
 * @skipline ephysics_world_new
 *
 * @section render-geometry Render geometry
 *
 * By setting the render geometry you tell ephysics the dimensions of rendered
 * area to be take on account by default updates.
 *
 * By default it starts with null x, y, width and height. Initially there's no
 * physics limits but - as we'll see later in this example - boundaries can be
 * added by issuing either ephysics_body_top_boundary_add(),
 * ephysics_body_bottom_boundary_add(), ephysics_body_left_boundary_add() and
 * ephysics_body_right_boundary_add().
 *
 * While setting the worlds render geometry the first parameter is our just
 * created world, the following parameters indicate the x, y, width and height
 * of our area of interest.
 *
 * @skipline ephysics_world_render_geometry_set
 *
 * @section boundaries Adding boundaries
 *
 * Boundaries are physics limits added by EPhysics which you can use to limit
 * the area where your objects can move around. Bear in mind that those
 * boundaries are created by EPhysics taking in account the render geometry you
 * have previously defined by calling ephysics_world_render_geometry_set().
 *
 * In our example we start by adding a bottom boundary. This EPhysics_Body
 * represents a physics limit under the world render geometry.
 *
 * The second line states the restitution factor for that bottom boundary, and
 * the third line its friction. These changes will make our ball to bounce
 * whenever it hits the ground.
 *
 * @skip ephysics_body_bottom_boundary_add
 * @until ephysics_body_friction_set 
 *
 * Then we add a right boundary limiting the physics world on the left side, we
 * also change its restitution and friction factors but with a smaller value,
 * we don't want to make it bounce as much as it is when hits the ground. 
 *
 * @skip ephysics_body_right_boundary_add
 * @until ephysics_body_friction_set 
 *
 * We also add a left boundary taking the same considerations for right
 * boundary.
 *
 * @skip ephysics_body_left_boundary_add
 * @until ephysics_body_friction_set 
 *
 * One of this examples requirements is to make the ball jump after a specific
 * user event, so the ball can suffer an impulse for any direction.
 *
 * With an upper impulse we don't want our ball to fly all over there, we want
 * to limit its upper movements, it's intended to limit the ball movement
 * within a box, it should not leave the render geometry area, for that purpose
 * we must define a top boundary. 
 *
 * @skipline ephysics_body_top_boundary_add
 * @dontinclude test_bouncing_ball.c
 *
 * @section world-populate Adding a ball
 *
 * Since we have defined the physics limits with our boundaries it's time to
 * add some fun. Here we add a ball as an elementary image widget and tell
 * ephysics about it.
 *
 * After setting the file that will be used as the image's source of our elm
 * image we move it to the center of render geometry and resize it to 70x70
 * pixels and show it.
 *
 * @skip elm_image_add
 * @until evas_object_show
 *
 * The evas object is just set and we must tell EPhysics about it, creating the
 * EPhysics_Body representing our ball and associating it to the just created
 * evas object.
 *
 * Once the ball has been moved to the center of render geometry it should
 * start falling after associating it to the EPhysics_Body. By default its mass
 * is initially set to 1 kilo, but it can be changed by calling
 * ephysics_body_mass_set(). Bear in mind that if you change its mass to 0
 * kilos it becomes a static body and will not move at all, the body will
 * remain fixed in the initial position.
 *
 * In the following code the first line adds a circle body, then we associate
 * the evas object to EPhysics_Body, EPhysics will map every changes on physics
 * object simulation to its evas object. Some restitution and friction factors
 * are added as well.
 *
 * @skip ephysics_body_circle_add
 * @until ephysics_body_friction_set
 *
 * @section jumping-ball Making it jump
 *
 * The next step is to give us the ability to make our ball to jump - actually
 * apply some impulse whenever a key has been pressed. Then we add a elementary
 * input callback to the window widget.
 *
 * @skipline elm_object_event_callback_add
 *
 * @dontinclude test_bouncing_ball.c
 *
 * The jumping callback implementation consists on handling only key up events
 * and discarding any other input event we get. We're interested on keyboard
 * events only. All the operations done in the following lines are done on
 * sphere EPhysics_Body previously created.
 *
 * We mainly use the ephysics_body_central_impulse_apply() function. This
 * function applies an inpulse on the center of a body.
 *
 * Once pressed \<Up> key it applies a central impulse of 0 kilos on X axis and
 * 10 kilos on Y - so the ball is forced up. 
 *
 * If \<Down> key has been pressed we apply an impulse of 0 kilos on X axis and
 * -10 on Y - here the ball is forced down. 
 *
 * In the case of \<Right> key pressing it's applied an impulse of 10 kilos on X
 * axis and 0 kilos on Y - which applies a force to the right side. But if the
 * key being pressed is \<Left> the opposite is done, and an impulse of -10
 * kilos is applied on X and 0 kilos on Y - and the ball is forced to the left.
 *
 * @skip _on_keydown
 * @until }
 *
 * Here we finish the very simple bouncing ball example. The full source code
 * can be found at @ref test_bouncing_ball_c.
 *
 */

/**
 * @page test_bouncing_ball_c test_bouncing_ball.c
 *
 * @section ephysics-test-h ephysics_test.h
 * @include ephysics_test.h
 *
 * @section test-bouncing-ball-c test_bouncing_ball.c
 * @dontinclude test.c
 * @skip test_clean
 * @until }
 *
 * @skip test_data_new
 * @until }
 *
 * @skip test_win_add
 * @until }
 *
 * @include test_bouncing_ball.c
 *
 *
 * @example test_bouncing_ball.c
 */

/**
 * @page ephysics_logo_c ephysics_logo.c
 *
 * @section ephysics-logo-c ephysics_logo.c
 * @include ephysics_logo.c
 *
 * @example ephysics_logo.c
 */

/**
 * @page tutorial_ephysics_delete_body EPhysics - Delete Body
 *
 * The purpose of this example is to demonstrate the EPhysics Callbacks usage -
 * The code adds two balls, one with impulse and the second with a collision
 * detection callback, to delete the body.
 *
 * For this example we'll have an EPhysics_World and two basic EPhysics_Bodys,
 * we'll apply an impulse in one of then and the other will be stopped
 * "waiting" for a collision.
 *
 * The basic concepts like - initializing an EPhysics_World, render geometry,
 * physics limiting boundaries, add an EPhysics_Body, associate it to evas
 * objects, change restitution, friction and impulse properties, were already
 * covered in
 * @ref tutorial_ephysics_bouncing_ball
 *
 * @section add-callbacks Adding Callbacks
 * @dontinclude test_delete.c
 *
 * Calling ephysics_body_event_callback_add()
 * registers a callback to a given EPhysics_Body event type.
 *
 * We'll use two types:
 *
 * @ref EPHYSICS_CALLBACK_BODY_DEL : called when a body deletion has been issued
 * and just before the deletion actually happens. In other words, to know that
 * body has been marked for
 * deletion. Typically to free some data associated with the body.
 *
 * @skipline ephysics_body_event_callback_add(sphere_body1,
 * @skip EPHYSICS_CALLBACK_BODY_DEL
 * @until );
 *
 * The callback function will receive the collision_data and free some data
 * associated with the body.
 *
 * @dontinclude test_delete.c
 *
 * @skip _del_cb(void *data,
 * @until }
 *
 * @ref EPHYSICS_CALLBACK_BODY_COLLISION : called just after the collision has
 * been actually processed by the physics engine. In other words, to be notified
 * about a collision between two physical bodies.
 *
 * @skip ephysics_body_event_callback_add(collision_data->sphere,
 * @until );
 *
 * The callback function will get the collision body and check if its body is
 * equal to which we want to delete.
 *
 * @dontinclude test_delete.c
 *
 * @skip _collision_cb(void *data,
 * @until }
 *
 * See
 * @ref _EPhysics_Callback_Body_Type
 * for more event types.
 *
 * Here we finish the example. The full source code can be found at
 * @ref test_delete_c.
 *
 */
 
 /**
 * @page test_delete_c test_delete.c
 *
 * @section ephysics-test-h ephysics_test.h
 * @include ephysics_test.h
 *
 * @section test-delete-c test_delete.c
 * @dontinclude test.c
 * @skip test_clean
 * @until }
 *
 * @skip test_win_add
 * @until }
 *
 * @include test_delete.c
 *
 * @example test_delete.c
 */

 /**
 * @page tutorial_ephysics_constraint EPhysics - Constraint
 *
 * The purpose of this example is to demonstrate the EPhysics Constraint usage -
 * The code apply a constraint between two cubes.
 *
 * For this example we'll have an EPhysics_World, and two basic EPhysics_Bodys.
 *
 * The basic concepts like - defining an EPhysics_World, render geometry,
 * physics limiting boundaries, add an EPhysics_Body, associate it to evas
 * objects, change restitution, friction and impulse properties, were
 * already covered in
 * @ref tutorial_ephysics_bouncing_ball
 *
 * @section add-constraint Adding a constraint
 * @dontinclude test_constraint.c
 *
 * Constraint is a specific type of variable in EPhysics.
 *
 * @skipline EPhysics_Constraint
 *
 * Here we're working with a point-to-point constraint, its purpose is to join
 * two bodies limiting their movements based on specified anchors.
 *
 * After we create our 2 EPhysics_Bodys, now we'll add a constraint between
 * them and setting an anchor to first body's Y using a p2p constraint
 * (point to point).
 *
 * @skip constraint = ephysics_constraint_p2p
 * @until );
 *
 * Here we finish the example. The full source code can be found at
 * @ref test_constraint_c.
 *
 */

 /**
 * @page test_constraint_c test_constraint.c
 *
 * @section ephysics-test-h ephysics_test.h
 * @include ephysics_test.h
 *
 * @section test-constraint-c test_constraint.c
 * @dontinclude test.c
 *
 * @skip test_clean
 * @until }
 *
 * @skip test_data_new
 * @until }
 *
 * @skip test_win_add
 * @until }
 *
 * @include test_constraint.c
 *
 * @example test_constraint.c
 */