ephysics: add a new example doc: Camera -

test_camera.c



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



SVN revision: 76975

legacy/ephysics/doc/examples.dox

@@ -5,6 +5,7 @@
  *
  * @li @ref tutorial_ephysics_bouncing_ball
  * @li @ref tutorial_ephysics_bouncing_text
+ * @li @ref tutorial_ephysics_camera
  * @li @ref tutorial_ephysics_collision_detection
  * @li @ref tutorial_ephysics_collision_filter
  * @li @ref tutorial_ephysics_delete_body
@@ -294,6 +295,131 @@
  * @example test_bouncing_text.c
  */
 
+/**
+ * @page tutorial_ephysics_camera EPhysics - Camera
+ *
+ * The purpose of this example is to demonstrate the EPhysics_Camera 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, two distant EPhysics_Bodys,
+ * one with an impulse to collide each other and an EPhysics_Camera that 
+ * follows the moving body using an animator.
+ *
+ * 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-camstruct Camera Data Struct
+ * @dontinclude test_camera.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 _Camera_Data {
+ * @until };
+ *
+ * @section add-camera Adding a Camera
+ *
+ * To move the camera in this example, we'll use an animator.
+ *
+ * @skipline camera_data->animator = ecore_animator_add
+ *
+ * In the animators function, we'll have to create a specific type of variable: 
+ * @ref EPhysics_Camera
+ * And also get the worlds rendered area width to define a limit to the camera.
+ *
+ * @dontinclude test_camera.c
+ *
+ * @skip _camera_move_cb(void *data
+ * @until &w, NULL);
+ *
+ * Every world has a camera, so here we get this camera used by our
+ * EPhysics_World.
+ *
+ * @skipline camera = ephysics_world_camera_get
+ *
+ * Here we get the cameras position to after set the position based on previous.
+ *
+ * @skipline ephysics_camera_position_get(camera
+ *
+ * Here we check if the camera reached the end of scenario (define the limit
+ * to the camera) then we stop the animator, else we move the camera + 2
+ * pixel positions to the right.
+ *
+ * @skip if (x + w > WIDTH * 2)
+ * @until ephysics_camera_position_set(camera, x, y
+ * @skipline }
+ *
+ * @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, camera_data);
+ *
+ * In the function, we just 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.
+ * @dontinclude test_camera.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.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.
+ *
+ * @skip if (fx < -FLOOR_WIDTH
+ * @until }
+ *
+ * Here we finish the example. The full source code can be found at
+ * @ref test_camera_c.
+ *
+ */
+
+ /**
+ * @page test_camera_c test_camera.c
+ *
+ * @section ephysics-test-h ephysics_test.h
+ * @include ephysics_test.h
+ *
+ * @section test-camera-c test_camera.c
+ * @dontinclude test.c
+ *
+ * @skip test_clean
+ * @until }
+ *
+ * @skip test_win_add
+ * @until }
+ *
+ * @include test_camera.c
+ *
+ * @example test_camera.c
+ */
+
 /**
  * @page tutorial_ephysics_collision_detection EPhysics - Collision Detection
  *