ephysics: add a new example doc: Camera Track -

test_camera_track.c



Patch by: Ricardo de Almeida Gonzaga <ricardo@profusion.mobi>



SVN revision: 76977

legacy/ephysics/doc/examples.dox

@@ -6,6 +6,7 @@
  * @li @ref tutorial_ephysics_bouncing_ball
  * @li @ref tutorial_ephysics_bouncing_text
  * @li @ref tutorial_ephysics_camera
+ * @li @ref tutorial_ephysics_camera_track
  * @li @ref tutorial_ephysics_collision_detection
  * @li @ref tutorial_ephysics_collision_filter
  * @li @ref tutorial_ephysics_delete_body
@@ -421,6 +422,139 @@
  * @example test_camera.c
  */
 
+/**
+ * @page tutorial_ephysics_camera_track EPhysics - Camera Track
+ *
+ * The purpose of this example is to demonstrate the EPhysics_Camera Track
+ * usage.
+ *
+ * The EPhysics_Camera facilitates the usage of scenarios bigger than the
+ * viewport, thats because the EPhysics handles the position of objects
+ * which has control.
+ *
+ * For this example we'll have an EPhysics_World, one main EPhysics_Body that
+ * will be tracked by an EPhysics_Camera on three ways, horizontal, vertical
+ * and full tracking. Also nine EPhysics_Bodys with mass 0, that will be used
+ * as scenario in order to our main body change its position on x and y axes
+ * when passes through this scenario.
+ *
+ * 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-trkstruct Track Data Struct
+ * @dontinclude test_camera_track.c
+ *
+ * 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 _Track_Data {
+ * @until };
+ *
+ * @section add-camera Adding a Camera
+ *
+ * In this example we'll use 3 kinds of tracking, to change this values we'll
+ * have an 
+ * @ref Elm_Spinner
+ * and handle it on this function.
+ *
+ * Every world has a camera, so here we get this camera used by our
+ * EPhysics_World.
+ *
+ * @skip _track_apply(Track_Data *track
+ * @until camera = ephysics_world_camera_get(track_data->base.world
+ *
+ * Here we'll get the elm_spinner value to the tracking base on this
+ * value
+ *
+ * @skip mode =
+ * @until }
+ *
+ * Here we'll set the camera to track the body, when a body is tracked,
+ * the camera will move automatically, following this body. It will keeps the
+ * body centralized on rendered area. If it will be centralized horizontally
+ * and / or vertically depends if parameters horizontal and vertical are set
+ * to EINA_TRUE, in this case we based these values on elm_spinner.
+ *
+ * @skip ephysics_camera_body_track(camera, body
+ * @until }
+ *
+ * @section add-uptfloor Updating the floor
+ *
+ * Here we'll use 2 floor images to give the impression of an infinite ground.
+ *
+ * Calling ephysics_world_event_callback_add()
+ * will register a callback to a type of physics world event.
+ *
+ * @ref EPHYSICS_CALLBACK_WORLD_CAMERA_MOVED : called if the camera position
+ * changed on physics simulation tick.
+ *
+ * @skip ephysics_world_event_callback_add(world,
+ * @until _camera_moved_cb, track_data);
+ *
+ * In the function, we'll get the cameras position to know how much the camera
+ * moved and move the same value to the floor passing it as delta_x to the
+ * function, note that we use an old_x variable to do this calculation.
+ *
+ * We'll get also if the body is being tracked on x and y axes. If the body
+ * isn't being tracked on x axis the floors x position won't change, delta_x
+ * will be zero.
+ *
+ * @dontinclude test_camera_track.c
+ *
+ * @skip _camera_moved_cb(void *data
+ * @until }
+ *
+ * Here we get the floors position and plus the delta_x value to move the
+ * floor in the same "velocity".
+ *
+ * @dontinclude test_camera_track.c
+ *
+ * @skip _update_floor
+ * @until fx = x + delta
+ *
+ * We use 2 floor images because whenever one exits the screen by the left
+ * side, another is being shown, when it happens the one which exit the screen
+ * is sent to the right side, entering into an infinite loop, giving the
+ * impression of an infinite ground image. Its important to note that we need
+ * to use the fx to don't gap the images.
+ *
+ * Note that the fy is being defined considering its offsets, -20 is to the
+ * floor image be above the floor, thus having an border above the collision
+ * point, +40 is the render area height, to offset the cameras y, basically
+ * to draw in the correct position in the canvas.
+ *
+ * @skip if (fx < -FLOOR_WIDTH
+ * @until }
+ *
+ * Here we finish the example. The full source code can be found at
+ * @ref test_camera_track_c.
+ *
+ */
+
+ /**
+ * @page test_camera_track_c test_camera_track.c
+ *
+ * @section ephysics-test-h ephysics_test.h
+ * @include ephysics_test.h
+ *
+ * @section test-camera-track-c test_camera_track.c
+ * @dontinclude test.c
+ *
+ * @skip test_clean
+ * @until }
+ *
+ * @skip test_win_add
+ * @until }
+ *
+ * @include test_camera_track.c
+ *
+ * @example test_camera_track.c
+ */
+
 /**
  * @page tutorial_ephysics_collision_detection EPhysics - Collision Detection
  *