EPhysics Camera
EPhysics

A camera defines the region of the physics world that will be rendered on the canvas. More...

## Typedefs

typedef struct _EPhysics_Camera | EPhysics_Camera
| Camera handle, used to change the position of the frame to be rendered.

## Functions

EAPI void | ephysics_camera_position_set (EPhysics_Camera *camera, Evas_Coord x, Evas_Coord y)
| Set camera's position.
EAPI void | ephysics_camera_position_get (const EPhysics_Camera *camera, Evas_Coord *x, Evas_Coord *y)
| Get camera's position.
EAPI void | ephysics_camera_body_track (EPhysics_Camera *camera, EPhysics_Body *body, Eina_Bool horizontal, Eina_Bool vertical)
| Set camera to track a body.
EAPI void | ephysics_camera_tracked_body_get (EPhysics_Camera *camera, EPhysics_Body **body, Eina_Bool *horizontal, Eina_Bool *vertical)
| Get body tracked by camera.
EAPI void | ephysics_camera_perspective_set (EPhysics_Camera *camera, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc)
| Set perspective to be applied on the scene.
EAPI void | ephysics_camera_perspective_get (const EPhysics_Camera *camera, Evas_Coord *px, Evas_Coord *py, Evas_Coord *z0, Evas_Coord *foc)
| Get perspective applied on the scene.
EAPI void | ephysics_camera_perspective_enabled_set (EPhysics_Camera *camera, Eina_Bool enabled)
| Set if perspective should be applied.
EAPI Eina_Bool | ephysics_camera_perspective_enabled_get (const EPhysics_Camera *camera)
| Return if perspective is enabled or not.

## Detailed Description

A camera defines the region of the physics world that will be rendered on the canvas.

It sets the point of view.

Every world has a camera, that can be gotten with ephysics_world_camera_get(). Its position can be set with ephysics_camera_position_set() or can be set to track a body, with ephysics_camera_body_track();

## Typedef Documentation

## EPhysics_Camera

typedef struct _EPhysics_Camera EPhysics_Camera

Camera handle, used to change the position of the frame to be rendered.

Every world have a camera that can be gotten with ephysics_world_camera_get().

Examples
  test_camera.c, and test_camera_track.c.

## Function Documentation

## ephysics_camera_position_set()

EAPI void ephysics_camera_position_set | ( | EPhysics_Camera * | camera,
|  | Evas_Coord | x,
|  | Evas_Coord | y )

Set camera's position.

Camera's position referes to the position of the top-left point of the camera.

By default a camera is created to map the first quadrant of physics world from the point (0, 0) to (render area width / world rate, render area height / world rate).

When render area is set with ephysics_world_render_geometry_set(), the camera geometry is updated to match it. So, for most cases, camera won't need to be handled by the user.

But it can be modified passing another top-left point position, so another region of the physics world will be rendered on the render area. So if you have a scene larger than the render area, camera handling can be very useful.

This function will make camera stop tracking a body set with ephysics_camera_body_track().

Note
  This change will be noticed on the next physics tick, so evas objects will be updated taking the camera's new position in account.

Parameters

  camera | The camera to be positioned.
  x | The new position on x axis, in pixels.
  y | The new position on y axis, in pixels.

See also
  ephysics_camera_position_get().
  ephysics_world_camera_get().
  ephysics_world_rate_get().

Examples
  test_camera.c, and test_camera_track.c.

## ephysics_camera_position_get()

EAPI void ephysics_camera_position_get | ( | const EPhysics_Camera * | camera,
|  | Evas_Coord * | x,
|  | Evas_Coord * | y )

Get camera's position.

Parameters

  camera | The world's camera.
  x | Position on x axis, in pixels.
  y | Position on y axis, in pixels.

See also
  ephysics_camera_position_set() for more details.

Examples
  test_camera.c, and test_camera_track.c.

## ephysics_camera_body_track()

EAPI void ephysics_camera_body_track | ( | EPhysics_Camera * | camera,
|  | EPhysics_Body * | body,
|  | Eina_Bool | horizontal,
|  | Eina_Bool | vertical )

Set camera to track a 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`.

Default updates (ephysics_body_evas_object_update()) will take care of updating evas objects associated to the bodies correctly. But if you need to do it yourself, you'll need to take camera's position in consideration, using ephysics_camera_position_get().

Note
  This change will be noticed on the next physics tick, so evas objects will be updated taking the camera's new position in account.

Parameters

  camera | The world's camera.
  body | The body tracked by the `camera`, or `NULL` if camera isn't tracking any body.
  horizontal | `EINA_TRUE` if `body` is tracked on x axis, `EINA_FALSE` otherwise;
  vertical | `EINA_TRUE` if `body` is tracked on y axis, `EINA_FALSE` otherwise;

See also
  ephysics_camera_tracked_body_get().
  ephysics_camera_position_set().
  ephysics_world_camera_get().

Examples
  test_camera_track.c.

## ephysics_camera_tracked_body_get()

EAPI void ephysics_camera_tracked_body_get | ( | EPhysics_Camera * | camera,
|  | EPhysics_Body ** | body,
|  | Eina_Bool * | horizontal,
|  | Eina_Bool * | vertical )

Get body tracked by camera.

Parameters

  camera | The world's camera.
  body | The body tracked by the `camera`, or `NULL` if camera isn't tracking any body.
  horizontal | `EINA_TRUE` if `body` is tracked on x axis, `EINA_FALSE` otherwise;
  vertical | `EINA_TRUE` if `body` is tracked on y axis, `EINA_FALSE` otherwise;

See also
  ephysics_camera_body_track() for more details.

Examples
  test_camera_track.c.

## ephysics_camera_perspective_set()

EAPI void ephysics_camera_perspective_set | ( | EPhysics_Camera * | camera,
|  | Evas_Coord | px,
|  | Evas_Coord | py,
|  | Evas_Coord | z0,
|  | Evas_Coord | foc )

Set perspective to be applied on the scene.

This applies a given perspective (3D) to the world rendering. It will be used when the scene is rendered, after each simulation step, by ephysics_body_evas_object_update().

The `px` and `py` points specify the "infinite distance" point in the 3D conversion (where all lines converge to like when artists draw 3D by hand). The `z0` value specifies the z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates. Any points on this z value will not have their X and Y values modified in the transform. Those further away (Z value higher) will shrink into the distance, and those less than this value will expand and become bigger. The foc value determines the "focal length" of the camera. This is in reality the distance between the camera lens plane itself (at or closer than this rendering results are undefined) and the `z0` z value. This allows for some "depth" control and `foc` must be greater than 0.

Considering the world geometry, by default, perspective is set to px = x + w / 2, py = y + h / 2, z0 = z + d / 2 and foc = 10 * (z + d). This means the conversion point is centered on render area, and `z0` is on the center of render area z axis. It is set when ephysics_world_render_geometry_set() is called.

Note
  The unit used for all parameters is Evas coordinates.
  To be used, perspective need to be enabled with ephysics_camera_perspective_enabled_set().

Parameters

  camera | The world's camera.
  px | The perspective distance X coordinate
  py | The perspective distance Y coordinate
  z0 | The "0" z plane value
  foc | The focal distance

See also
  ephysics_camera_perspective_get().
  ephysics_camera_perspective_enabled_set().

## ephysics_camera_perspective_get()

EAPI void ephysics_camera_perspective_get | ( | const EPhysics_Camera * | camera,
|  | Evas_Coord * | px,
|  | Evas_Coord * | py,
|  | Evas_Coord * | z0,
|  | Evas_Coord * | foc )

Get perspective applied on the scene.

Parameters

  camera | The world's camera.
  px | The perspective distance X coordinate
  py | The perspective distance Y coordinate
  z0 | The "0" z plane value
  foc | The focal distance

See also
  ephysics_camera_perspective_set() for more details.
  ephysics_camera_perspective_enabled_get().

## ephysics_camera_perspective_enabled_set()

EAPI void ephysics_camera_perspective_enabled_set | ( | EPhysics_Camera * | camera,
|  | Eina_Bool | enabled )

Set if perspective should be applied.

The applied perspective can be set with ephysics_camera_perspective_set().

Parameters

  camera | The world's camera.
  enabled | `EINA_TRUE` if perspective should be used, or `EINA_FALSE` if it shouldn't.

See also
  ephysics_camera_perspective_set() for more details.
  ephysics_camera_perspective_enabled_get().

## ephysics_camera_perspective_enabled_get()

EAPI Eina_Bool ephysics_camera_perspective_enabled_get | ( | const EPhysics_Camera * | camera | ) |

Return if perspective is enabled or not.

Parameters

  camera | The world's camera.

Returns
  `EINA_TRUE` if perspective is enabled, or `EINA_FALSE` if it isn't, or on error.

See also
  ephysics_camera_perspective_set() for more details.
  ephysics_camera_perspective_enabled_set().