EPhysics World
EPhysics

A world is required to simulate physics between bodies. More...

## Typedefs

typedef struct _EPhysics_World | EPhysics_World
| World handle, most basic type of EPhysics.
typedef enum _EPhysics_Callback_World_Type | EPhysics_Callback_World_Type
| Identifier of callbacks to be set for EPhysics worlds.
typedef enum _EPhysics_World_Constraint_Solver_Mode | EPhysics_World_Solver_Mode
typedef void(* | EPhysics_World_Event_Cb) (void *data, EPhysics_World *world, void *event_info)
| EPhysics world event callback function signature.

## Enumerations

enum | _EPhysics_Callback_World_Type { EPHYSICS_CALLBACK_WORLD_DEL , EPHYSICS_CALLBACK_WORLD_STOPPED , EPHYSICS_CALLBACK_WORLD_CAMERA_MOVED , EPHYSICS_CALLBACK_WORLD_UPDATE , EPHYSICS_CALLBACK_WORLD_LAST }
enum | _EPhysics_World_Constraint_Solver_Mode { EPHYSICS_WORLD_SOLVER_RANDMIZE_ORDER = 1 , EPHYSICS_WORLD_SOLVER_USE_WARMSTARTING = 4 , EPHYSICS_WORLD_SOLVER_USE_2_FRICTION_DIRECTIONS = 16 , EPHYSICS_WORLD_SOLVER_SIMD = 256 }
| typedef EPhysics_World_Constraint_Solver_Mode More...

## Functions

EAPI EPhysics_World * | ephysics_world_new (void)
| Create a new physics world.
EAPI void | ephysics_world_render_geometry_set (EPhysics_World *world, Evas_Coord x, Evas_Coord y, Evas_Coord z, Evas_Coord w, Evas_Coord h, Evas_Coord d)
| Set dimensions of rendered area to be take on account by default updates.
EAPI void | ephysics_world_render_geometry_get (const EPhysics_World *world, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z, Evas_Coord *w, Evas_Coord *h, Evas_Coord *d)
| Get dimensions of rendered area to be take on account by default updates.
EAPI Eina_Bool | ephysics_world_serialize (EPhysics_World *world, const char *path)
| Serializes the `world` to `path`.
EAPI void | ephysics_world_del (EPhysics_World *world)
| Deletes a physics world.
EAPI void | ephysics_world_running_set (EPhysics_World *world, Eina_Bool running)
| Set running status of world.
EAPI Eina_Bool | ephysics_world_running_get (const EPhysics_World *world)
| Get running status of world.
EAPI void | ephysics_world_max_sleeping_time_set (EPhysics_World *world, double sleeping_time)
| Set the max sleeping time value.
EAPI double | ephysics_world_max_sleeping_time_get (const EPhysics_World *world)
| Get the max sleeping time value for `world`.
EAPI void | ephysics_world_gravity_set (EPhysics_World *world, double gx, double gy, double gz)
| Set world gravity in the 3 axes (x, y, z).
EAPI void | ephysics_world_constraint_solver_iterations_set (EPhysics_World *world, int iterations)
| Set the number of iterations the constraint solver will have for contact and joint constraints.
EAPI int | ephysics_world_constraint_solver_iterations_get (const EPhysics_World *world)
| Get the number of iterations the constraint solver will have for contact and joint constraints.
EAPI void | ephysics_world_constraint_solver_mode_enable_set (EPhysics_World *world, EPhysics_World_Solver_Mode solver_mode, Eina_Bool enable)
| Enable or disable a constraint solver mode to `world`.
EAPI Eina_Bool | ephysics_world_constraint_solver_mode_enable_get (const EPhysics_World *world, EPhysics_World_Solver_Mode solver_mode)
| Get the `solver_mode` status on `world`.
EAPI void | ephysics_world_gravity_get (const EPhysics_World *world, double *gx, double *gy, double *gz)
| Get world gravity values for axis x, y and z.
EAPI void | ephysics_world_rate_set (EPhysics_World *world, double rate)
| Set rate between pixels on evas canvas and meters on ephysics world.
EAPI double | ephysics_world_rate_get (const EPhysics_World *world)
| Get rate between pixels on evas canvas and meters on ephysics world.
EAPI Eina_List * | ephysics_world_bodies_get (const EPhysics_World *world)
| Gets the world's bodies list.
EAPI EPhysics_Camera * | ephysics_world_camera_get (const EPhysics_World *world)
| Get the camera used by an ephysics world.
EAPI void | ephysics_world_event_callback_add (EPhysics_World *world, EPhysics_Callback_World_Type type, EPhysics_World_Event_Cb func, const void *data)
| Register a callback to a type of physics world event.
EAPI void * | ephysics_world_event_callback_del (EPhysics_World *world, EPhysics_Callback_World_Type type, EPhysics_World_Event_Cb func)
| Unregister an ephysics world event callback.
EAPI void * | ephysics_world_event_callback_del_full (EPhysics_World *world, EPhysics_Callback_World_Type type, EPhysics_World_Event_Cb func, void *data)
| Unregister an ephysics world event callback matching data pointer.
EAPI void | ephysics_world_linear_slop_set (EPhysics_World *world, double linear_slop)
| Set linear slop to be used by world.
EAPI double | ephysics_world_linear_slop_get (const EPhysics_World *world)
| Get linear slop used by world.
EAPI void | ephysics_world_bodies_outside_top_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the top.
EAPI Eina_Bool | ephysics_world_bodies_outside_top_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the top.
EAPI void | ephysics_world_bodies_outside_bottom_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the bottom.
EAPI Eina_Bool | ephysics_world_bodies_outside_bottom_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the bottom.
EAPI void | ephysics_world_bodies_outside_right_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the right.
EAPI Eina_Bool | ephysics_world_bodies_outside_right_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the right.
EAPI void | ephysics_world_bodies_outside_left_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the left.
EAPI Eina_Bool | ephysics_world_bodies_outside_left_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the left.
EAPI void | ephysics_world_bodies_outside_front_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the front.
EAPI Eina_Bool | ephysics_world_bodies_outside_front_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the front.
EAPI void | ephysics_world_bodies_outside_back_autodel_set (EPhysics_World *world, Eina_Bool autodel)
| Set world autodeleting bodies mode when they're outside of render area by the back.
EAPI Eina_Bool | ephysics_world_bodies_outside_back_autodel_get (const EPhysics_World *world)
| Get world autodeleting bodies mode when they're outside of render area by the back.
EAPI void | ephysics_world_simulation_set (EPhysics_World *world, double fixed_time_step, int max_sub_steps)
| Set world simulation's fixed time step and max number of sub steps configuration.
EAPI void | ephysics_world_simulation_get (const EPhysics_World *world, double *fixed_time_step, int *max_sub_steps)
| Get world simulation's fixed time step and max number of sub steps configuration.
EAPI void | ephysics_world_point_light_position_set (EPhysics_World *world, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz)
| Set position of point light to be applied on the scene.
EAPI void | ephysics_world_point_light_color_set (EPhysics_World *world, int lr, int lg, int lb)
| Set color of point light to be applied on the scene.
EAPI void | ephysics_world_ambient_light_color_set (EPhysics_World *world, int ar, int ag, int ab)
| Set color of the ambient light to be applied on the scene.
EAPI void | ephysics_world_point_light_position_get (const EPhysics_World *world, Evas_Coord *lx, Evas_Coord *ly, Evas_Coord *lz)
| Get position of point light applied on the scene.
EAPI void | ephysics_world_point_light_color_get (const EPhysics_World *world, int *lr, int *lg, int *lb)
| Get color of point light applied on the scene.
EAPI void | ephysics_world_ambient_light_color_get (const EPhysics_World *world, int *ar, int *ag, int *ab)
| Set color of the ambient light to be applied on the scene.
EAPI void | ephysics_world_light_all_bodies_set (EPhysics_World *world, Eina_Bool enable)
| Set if light should be applied over all the bodies.
EAPI Eina_Bool | ephysics_world_light_all_bodies_get (const EPhysics_World *world)
| Get light setting regarding being applied over all the bodies.
EAPI void | ephysics_world_stack_enable_set (EPhysics_World *world, Eina_Bool enabled)
| Enable / disable stacking based on bodies z coordinates.
EAPI Eina_Bool | ephysics_world_stack_enable_get (const EPhysics_World *world)
| Get stacking status of world.

## Detailed Description

A world is required to simulate physics between bodies.

It will setup collision configuration, constraint solver, the broadphase interface and a dispatcher to dispatch calculations for overlapping pairs.

A new world can be created with ephysics_world_new() and deleted with ephysics_world_del(). It can have its gravity changed with ephysics_world_gravity_set() and play / paused with ephysics_world_running_set(). When running, the simulation will be gradually stepped.

## Typedef Documentation

## EPhysics_World

typedef struct _EPhysics_World EPhysics_World

World handle, most basic type of EPhysics.

Created with ephysics_world_new() and deleted with ephysics_world_del().

Examples
  ephysics_logo.c, test_bouncing_ball.c, test_bouncing_text.c, test_camera.c, test_camera_track.c, test_collision_detection.c, test_collision_filter.c, test_constraint.c, test_delete.c, test_forces.c, test_growing_balls.c, test_no_gravity.c, test_rotating_forever.c, test_shapes.c, test_sleeping_threshold.c, test_slider.c, and test_velocity.c.

## EPhysics_Callback_World_Type

typedef enum _EPhysics_Callback_World_Type EPhysics_Callback_World_Type

Identifier of callbacks to be set for EPhysics worlds.

See also
  ephysics_world_event_callback_add()
  ephysics_world_event_callback_del()
  ephysics_world_event_callback_del_full()

## EPhysics_World_Event_Cb

typedef void(* EPhysics_World_Event_Cb) (void *data, EPhysics_World *world, void *event_info)

EPhysics world event callback function signature.

Callbacks can be registered for events like world deleting.

Parameters

  data | User data that will be set when registering the callback.
  world | Physics world.
  event_info | Data specific to a kind of event. Some types of events don't have `event_info`.

See also
  ephysics_world_event_callback_add() for more info.

## Enumeration Type Documentation

## _EPhysics_Callback_World_Type

enum _EPhysics_Callback_World_Type

Enumerator
EPHYSICS_CALLBACK_WORLD_DEL | World being deleted (called before free).
EPHYSICS_CALLBACK_WORLD_STOPPED | no objects are moving any more
EPHYSICS_CALLBACK_WORLD_CAMERA_MOVED | camera position changed
EPHYSICS_CALLBACK_WORLD_UPDATE | world being updated
EPHYSICS_CALLBACK_WORLD_LAST | kept as sentinel, not really an event

## _EPhysics_World_Constraint_Solver_Mode

enum _EPhysics_World_Constraint_Solver_Mode

typedef EPhysics_World_Constraint_Solver_Mode

Identifies the worlds contact and joint constraint solver mode. By default EPHYSICS_WORLD_SOLVER_USE_WARMSTARTING is the only enabled solver mode.

See also
  ephysics_world_constraint_solver_mode_enable_set()
  ephysics_world_constraint_solver_mode_enable_get()

Enumerator
EPHYSICS_WORLD_SOLVER_RANDMIZE_ORDER | Randomize the order of solving the constraint rows.
EPHYSICS_WORLD_SOLVER_USE_WARMSTARTING | The PGS is an iterative algorithm where each iteration is based on the solution of previous iteration, if no warmstarting is used, the initial solution for PGS is set to zero each frame (by default this mode is enabled, disabling this mode the user can face a better performance depending on the amount of objects in the simulation).
EPHYSICS_WORLD_SOLVER_USE_2_FRICTION_DIRECTIONS | While calculating a friction impulse consider this should be applied on both bodies (this mode cause a better stacking stabilization).
EPHYSICS_WORLD_SOLVER_SIMD | Use a SSE optimized innerloop, using assembly intrinsics, this is implemented and can be enabled/disabled for Windows and Mac OSX versions, single-precision floating point, 32bit(disabled by default).

## Function Documentation

## ephysics_world_new()

EAPI EPhysics_World * ephysics_world_new | ( | void |  | ) |

Create a new physics world.

A new world will be created with set collision configuration, constraint solver, broadphase interface and dispatcher.

It can be paused / unpaused with ephysics_world_running_set() and its gravity can be changed with ephysics_world_gravity_set().

By default it starts with gravity y = 294 Evas coordinates per second ^ 2 and playing.

If default updates between physics bodies and evas objects will be used it's mandatory to set the size of the area to be rendered with ephysics_world_render_geometry_set().

Returns
  A new world or `NULL`, on errors.

See also
  ephysics_world_del().

Examples
  ephysics_logo.c, test_bouncing_ball.c, test_bouncing_text.c, test_camera.c, test_camera_track.c, test_collision_detection.c, test_collision_filter.c, test_constraint.c, test_delete.c, test_forces.c, test_growing_balls.c, test_no_gravity.c, test_rotating_forever.c, test_shapes.c, test_sleeping_threshold.c, test_slider.c, and test_velocity.c.

## ephysics_world_render_geometry_set()

EAPI void ephysics_world_render_geometry_set | ( | EPhysics_World * | world,
|  | Evas_Coord | x,
|  | Evas_Coord | y,
|  | Evas_Coord | z,
|  | Evas_Coord | w,
|  | Evas_Coord | h,
|  | Evas_Coord | d )

Set dimensions of rendered area to be take on account by default updates.

By default it starts with null x, y, width and height.

The physics world won't be limited, but boundaries can be added with:

- ephysics_body_top_boundary_add(),
- ephysics_body_bottom_boundary_add(),
- ephysics_body_left_boundary_add(),
- ephysics_body_right_boundary_add(),
- ephysics_body_front_boundary_add(),
- ephysics_body_back_boundary_add().

Parameters

  world | the world to be configured.
  x | Coordinate x of the top left point of rendered area, in pixels.
  y | Coordinate y of the top left point of rendered area, in pixels.
  z | Coordinate z of the rendered area, in pixels.
  w | rendered area width, in pixels.
  h | rendered area height, in pixels.
  d | rendered area depth, in pixels.

Note
  The unit used for geometry is Evas coordinates.

See also
  ephysics_body_event_callback_add() for more info.
  ephysics_world_rate_get().
  ephysics_world_render_geometry_get().

Examples
  ephysics_logo.c, test_bouncing_ball.c, test_bouncing_text.c, test_camera.c, test_camera_track.c, test_collision_detection.c, test_collision_filter.c, test_constraint.c, test_delete.c, test_forces.c, test_growing_balls.c, test_no_gravity.c, test_rotating_forever.c, test_shapes.c, test_sleeping_threshold.c, test_slider.c, and test_velocity.c.

## ephysics_world_render_geometry_get()

EAPI void ephysics_world_render_geometry_get | ( | const EPhysics_World * | world,
|  | Evas_Coord * | x,
|  | Evas_Coord * | y,
|  | Evas_Coord * | z,
|  | Evas_Coord * | w,
|  | Evas_Coord * | h,
|  | Evas_Coord * | d )

Get dimensions of rendered area to be take on account by default updates.

Parameters

  world | the world to be configured.
  x | Coordinate x of the top left point of rendered area, in pixels.
  y | Coordinate y of the top left point of rendered area, in pixels.
  z | Coordinate z of the rendered area, in pixels.
  w | rendered area width, in pixels.
  h | rendered area height, in pixels.
  d | rendered area depth, in pixels.

See also
  ephysics_world_render_geometry_set() for more information.

Examples
  test_camera.c.

## ephysics_world_serialize()

EAPI Eina_Bool ephysics_world_serialize | ( | EPhysics_World * | world,
|  | const char * | path )

Serializes the `world` to `path`.

Save the dynamics world to a binary dump, a .bullet file.

Note
  Should be used only for debugging purposes.

Parameters

  world | the world to be serialized.
  path | where the serialized world should be written to.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise

## ephysics_world_del()

EAPI void ephysics_world_del | ( | EPhysics_World * | world | ) |

Deletes a physics world.

It will also delete all bodies associated to it.

Parameters

  world | The world to be deleted.

See also
  ephysics_world_new() for more details.

Examples
  ephysics_logo.c, test_camera.c, test_camera_track.c, test_collision_detection.c, test_delete.c, and test_velocity.c.

## ephysics_world_running_set()

EAPI void ephysics_world_running_set | ( | EPhysics_World * | world,
|  | Eina_Bool | running )

Set running status of world.

A world can be played / paused. When running, it will simulate the physics step by step. When paused, it will stop simulation. Consequently all the registered callbacks won't be called since no event will occur (no collisions, no object updates).

When a world is created it starts running.

Parameters

  world | The world to be played / paused.
  running | If `EINA_TRUE` it will play, otherwise it will pause.

See also
  ephysics_world_running_get()

## ephysics_world_running_get()

EAPI Eina_Bool ephysics_world_running_get | ( | const EPhysics_World * | world | ) |

Get running status of world.

By default a world starts running.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if it's running, or `EINA_FALSE` if it's paused or on error.

See also
  ephysics_world_running_set() for more details.

## ephysics_world_max_sleeping_time_set()

EAPI void ephysics_world_max_sleeping_time_set | ( | EPhysics_World * | world,
|  | double | sleeping_time )

Set the max sleeping time value.

This value determines how long(in seconds) a rigid body under the linear and angular threshold is supposed to be marked as sleeping. Default value is set to 2.0.

Parameters

  world | The world to set the max sleeping time.
  sleeping_time | The max sleeping time to set to `world`.

See also
  ephysics_world_max_sleeping_time_get()
  ephysics_body_sleeping_threshold_set() for sleeping thresholds details.

Examples
  test_sleeping_threshold.c.

## ephysics_world_max_sleeping_time_get()

EAPI double ephysics_world_max_sleeping_time_get | ( | const EPhysics_World * | world | ) |

Get the max sleeping time value for `world`.

Parameters

  world | The world to get the max sleeping time from.

Returns
  The max sleeping time from `world`.

See also
  ephysics_world_max_sleeping_time_set()

## ephysics_world_gravity_set()

EAPI void ephysics_world_gravity_set | ( | EPhysics_World * | world,
|  | double | gx,
|  | double | gy,
|  | double | gz )

Set world gravity in the 3 axes (x, y, z).

Gravity will act over bodies with mass over all the time.

By default values are 0, 294, 0 Evas Coordinates per second ^ 2 (9.8 m/s^2, since we've a default rate of 30 pixels).

If you change the rate but wants to keep 9.8 m/s^2, you well need to set world gravity with: 9.8 * new_rate.

Parameters

  world | The world object.
  gx | Gravity on x axis.
  gy | Gravity on y axis.
  gz | Gravity on z axis.

Note
  The unit used for acceleration is Evas coordinates per second ^ 2.

See also
  ephysics_world_gravity_get().
  ephysics_world_rate_set().

Examples
  test_forces.c, test_no_gravity.c, and test_rotating_forever.c.

## ephysics_world_constraint_solver_iterations_set()

EAPI void ephysics_world_constraint_solver_iterations_set | ( | EPhysics_World * | world,
|  | int | iterations )

Set the number of iterations the constraint solver will have for contact and joint constraints.

The default value is set to 10. The greater number of iterations more quality and precise the result but with performance penalty.

By default, the Projected Gauss Seidel constraint solver is used for contact and joint constraints. The algorithm is an iterative LCP solver, informally known as 'sequential impulse'.

A reasonable range of iterations is from 4 (low quality, good performance) to 20 (good quality, less but still reasonable performance).

Parameters

  world | The world to be set.
  iterations | The number of iterations to be set.

See also
  ephysics_world_constraint_solver_iterations_get().

## ephysics_world_constraint_solver_iterations_get()

EAPI int ephysics_world_constraint_solver_iterations_get | ( | const EPhysics_World * | world | ) |

Get the number of iterations the constraint solver will have for contact and joint constraints.

Parameters

  world | The world to get number of iterations from.

Returns
  the number of iterations set to `world`, or 0 on failure.

See also
  ephysics_world_constraint_solver_iterations_set() for its meaning.

## ephysics_world_constraint_solver_mode_enable_set()

EAPI void ephysics_world_constraint_solver_mode_enable_set | ( | EPhysics_World * | world,
|  | EPhysics_World_Solver_Mode | solver_mode,
|  | Eina_Bool | enable )

Enable or disable a constraint solver mode to `world`.

A world can operate on several constraint solver modes.

Parameters

  world | The world to be set.
  solver_mode | The solver mode to set.
  enable | If `EINA_TRUE` enable the mode, if EINA_FALSE, disable it.

See also
  EPhysics_World_Solver_Mode for supported solver modes.
  ephysics_world_constraint_solver_mode_enable_get()

## ephysics_world_constraint_solver_mode_enable_get()

EAPI Eina_Bool ephysics_world_constraint_solver_mode_enable_get | ( | const EPhysics_World * | world,
|  | EPhysics_World_Solver_Mode | solver_mode )

Get the `solver_mode` status on `world`.

Parameters

  world | The world to be queried.
  solver_mode | The solver mode of interest.

Returns
  EINA_TRUE if `solver_mode` is enabled, EINA_FALSE otherwise.

See also
  ephysics_world_constraint_solver_mode_enable_set()

## ephysics_world_gravity_get()

EAPI void ephysics_world_gravity_get | ( | const EPhysics_World * | world,
|  | double * | gx,
|  | double * | gy,
|  | double * | gz )

Get world gravity values for axis x, y and z.

Parameters

  world | The world object.
  gx | Gravity on x axis.
  gy | Gravity on y axis.
  gz | Gravity on y axis.

See also
  ephysics_world_gravity_set().

## ephysics_world_rate_set()

EAPI void ephysics_world_rate_set | ( | EPhysics_World * | world,
|  | double | rate )

Set rate between pixels on evas canvas and meters on ephysics world.

It will be used by automatic updates of evas objects associated to physics bodies.

By default its value is 30 Evas coordinates (pixels) per meter.

If you change the rate but wants to keep gravity as (0, 9.8 m/s^2), you well need to set world gravity with: 9.8 * new_rate. For this, use ephysics_world_gravity_set();

Parameters

  world | The world object.
  rate | Rate between pixels and meters. Value must be > 0.

See also
  ephysics_body_event_callback_add() for more info.
  ephysics_world_rate_get().

## ephysics_world_rate_get()

EAPI double ephysics_world_rate_get | ( | const EPhysics_World * | world | ) |

Get rate between pixels on evas canvas and meters on ephysics world.

Parameters

  world | The world object.

Returns
  The rate between pixels and meters.

See also
  ephysics_world_rate_set() for details.

## ephysics_world_bodies_get()

EAPI Eina_List * ephysics_world_bodies_get | ( | const EPhysics_World * | world | ) |

Gets the world's bodies list.

Parameters

  world | The world object.

Returns
  The list of bodies that belongs to this `world`.

Note
  The list should be freed after usage.

See also
  ephysics_body_cylinder_add().
  ephysics_body_box_add().
  ephysics_body_del().

## ephysics_world_camera_get()

EAPI EPhysics_Camera * ephysics_world_camera_get | ( | const EPhysics_World * | world | ) |

Get the camera used by an ephysics world.

Parameters

  world | The world object.

Returns
  The camera.

See also
  ephysics_camera_position_set().
  ephysics_camera_body_track().

Examples
  test_camera.c, and test_camera_track.c.

## ephysics_world_event_callback_add()

EAPI void ephysics_world_event_callback_add | ( | EPhysics_World * | world,
|  | EPhysics_Callback_World_Type | type,
|  | EPhysics_World_Event_Cb | func,
|  | const void * | data )

Register a callback to a type of physics world event.

The registered callback will receives the world and extra user data that can be passed.

What follows is a list of details about each callback type:

- EPHYSICS_CALLBACK_WORLD_DEL: Called just before a world is freed. No event_info is passed to the callback.
- EPHYSICS_CALLBACK_WORLD_STOPPED: Called when all the bodies are stopped. No event_info is passed to the callback.
- EPHYSICS_CALLBACK_WORLD_CAMERA_MOVED: Called if camera position changed on physics simulation tick. Camera is passed as event_info to the callback. Useful to move backgrounds, since objects would be already updated considering camera's position.

Parameters

  world | The physics world.
  type | Type of callback to be listened by `func`.
  func | Callback function that will be called when event occurs.
  data | User data that will be passed to callback function. It won't be used by ephysics in any way.

Examples
  test_camera.c, and test_camera_track.c.

## ephysics_world_event_callback_del()

EAPI void * ephysics_world_event_callback_del | ( | EPhysics_World * | world,
|  | EPhysics_Callback_World_Type | type,
|  | EPhysics_World_Event_Cb | func )

Unregister an ephysics world event callback.

A previously added callback that match `world`, `type` and `func` will be deleted.

Parameters

  world | The physics world.
  type | The type of callback to be unregistered.
  func | The callback function to be unregistered.

Returns
  The user data passed when the callback was registered, or `NULL` on error.

See also
  ephysics_world_event_callback_add() for details.
  ephysics_world_event_callback_del_full() if you need to match data pointer.

## ephysics_world_event_callback_del_full()

EAPI void * ephysics_world_event_callback_del_full | ( | EPhysics_World * | world,
|  | EPhysics_Callback_World_Type | type,
|  | EPhysics_World_Event_Cb | func,
|  | void * | data )

Unregister an ephysics world event callback matching data pointer.

A previously added callback that match `world`, `type`, `func` and `data` will be deleted.

Parameters

  world | The physics world.
  type | The type of callback to be unregistered.
  func | The callback function to be unregistered.
  data | The data pointer that was passed to the callback.

Returns
  The user data passed when the callback was registered, or `NULL` on error.

See also
  ephysics_world_event_callback_add() for details.
  ephysics_world_event_callback_del() if you don't need to match data pointer.

## ephysics_world_linear_slop_set()

EAPI void ephysics_world_linear_slop_set | ( | EPhysics_World * | world,
|  | double | linear_slop )

Set linear slop to be used by world.

Constraint solver can be configured using some advanced settings, like the solver slop factor.

The default value is set to 0 with a small value results in a smoother stabilization for stacking bodies.

Linear slop on sequencial impulse constraint solver is used as a factor for penetration. The penetration will the manifold distance + linear slop.

Parameters

  world | The physics world.
  linear_slop | New linear slop value to be used by constraint solver of physics engine.

## ephysics_world_linear_slop_get()

EAPI double ephysics_world_linear_slop_get | ( | const EPhysics_World * | world | ) |

Get linear slop used by world.

Parameters

  world | The physics world.

Returns
  Linear slop value used by constraint solver of physics engine or 0 on failure.

See also
  ephysics_world_linear_slop_set() for details.

## ephysics_world_bodies_outside_top_autodel_set()

EAPI void ephysics_world_bodies_outside_top_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the top.

It's useful when you don't care about bodies leaving the render area set with ephysics_world_render_geometry_set(), and don't think they could / should return. So you can safely delete them and save resources.

Also, it's useful if you have only a bottom border set with ephysics_body_top_boundary_add() and gravity set, and want to listen for EPHYSICS_CALLBACK_WORLD_STOPPED event. If a body goes out of the render area, they will be acting by gravity and won't collide to anything, so they could be moving forever and world would never stop. For this case, enabling autodel for left and right borders seems to be a good idea.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_get().
  ephysics_world_bodies_outside_bottom_autodel_set().
  ephysics_world_bodies_outside_left_autodel_set().
  ephysics_world_bodies_outside_right_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_top_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_top_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the top.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_top_autodel_set() for details.

## ephysics_world_bodies_outside_bottom_autodel_set()

EAPI void ephysics_world_bodies_outside_bottom_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the bottom.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_set() for more details.
  ephysics_world_bodies_outside_bottom_autodel_get().
  ephysics_world_bodies_outside_left_autodel_set().
  ephysics_world_bodies_outside_right_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_bottom_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_bottom_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the bottom.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_bottom_autodel_set() for details.

## ephysics_world_bodies_outside_right_autodel_set()

EAPI void ephysics_world_bodies_outside_right_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the right.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_set() for more details.
  ephysics_world_bodies_outside_right_autodel_get().
  ephysics_world_bodies_outside_bottom_autodel_set().
  ephysics_world_bodies_outside_left_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_right_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_right_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the right.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_right_autodel_set() for details.

## ephysics_world_bodies_outside_left_autodel_set()

EAPI void ephysics_world_bodies_outside_left_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the left.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_set() for more details.
  ephysics_world_bodies_outside_left_autodel_get().
  ephysics_world_bodies_outside_bottom_autodel_set().
  ephysics_world_bodies_outside_right_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_left_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_left_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the left.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_left_autodel_set() for details.

## ephysics_world_bodies_outside_front_autodel_set()

EAPI void ephysics_world_bodies_outside_front_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the front.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_set() for more details.
  ephysics_world_bodies_outside_left_autodel_get().
  ephysics_world_bodies_outside_bottom_autodel_set().
  ephysics_world_bodies_outside_right_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_front_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_front_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the front.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_front_autodel_set() for details.

## ephysics_world_bodies_outside_back_autodel_set()

EAPI void ephysics_world_bodies_outside_back_autodel_set | ( | EPhysics_World * | world,
|  | Eina_Bool | autodel )

Set world autodeleting bodies mode when they're outside of render area by the back.

Parameters

  world | The physics world.
  autodel | If `EINA_TRUE` delete bodies when they are outside render area, otherwise, don't delete.

See also
  ephysics_world_bodies_outside_top_autodel_set() for more details.
  ephysics_world_bodies_outside_left_autodel_get().
  ephysics_world_bodies_outside_bottom_autodel_set().
  ephysics_world_bodies_outside_right_autodel_set().
  ephysics_world_bodies_outside_front_autodel_set().
  ephysics_world_bodies_outside_back_autodel_set().

## ephysics_world_bodies_outside_back_autodel_get()

EAPI Eina_Bool ephysics_world_bodies_outside_back_autodel_get | ( | const EPhysics_World * | world | ) |

Get world autodeleting bodies mode when they're outside of render area by the back.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if bodies will be deleted or `EINA_FALSE` if they won't, or on error.

See also
  ephysics_world_bodies_outside_back_autodel_set() for details.

## ephysics_world_simulation_set()

EAPI void ephysics_world_simulation_set | ( | EPhysics_World * | world,
|  | double | fixed_time_step,
|  | int | max_sub_steps )

Set world simulation's fixed time step and max number of sub steps configuration.

It's important that time step is always less than `max_sub_steps` * `fixed_time_step`, otherwise you are losing time. Mathematically:

time step < `max_sub_steps` * `fixed_time_step`;

If you're a using a very large time step [say, five times the size of the fixed internal time step], then you must increase the number of max sub steps to compensate for this, otherwise your simulation is “losing” time.

The time step may vary. Simulation ticks are called by an animator, so, by default, time step is `1/30` secs. If you're using elementary, default FPS configuration is 60 fps, i.e. time step is `1/60` secs. You can change that setting a different time with ecore_animator_frametime_set().

Also, keep in mind that if you're using CPU intense calculations maybe this framerate won't be achieved, so the time step will be bigger. You need to define what range of frames per seconds you need to support and configure `max_sub_steps` and `fixed_time_step` according to this.

By decreasing the size of `fixed_time_step`, you are increasing the “resolution” of the simulation.

If you are finding that your objects are moving very fast and escaping from your walls instead of colliding with them, then one way to help fix this problem is by decreasing `fixed_time_step`. If you do this, then you will need to increase `max_sub_steps` to ensure the equation listed above is still satisfied.

The issue with this is that each internal “tick” takes an amount of computation. More of them means your CPU will be spending more time on physics and therefore less time on other stuff. Say you want twice the resolution, you'll need twice the `max_sub_steps`, which could chew up twice as much CPU for the same amount of simulation time.

When you pass `max_sub_steps` > 1, it will interpolate movement for you. This means that if your `fixed_time_step` is 3 units, and you pass a timeStep of 4, then it will do exactly one tick, and estimate the remaining movement by 1/3. This saves you having to do interpolation yourself, but keep in mind that maxSubSteps needs to be greater than 1.

By default `fixed_time_step` is 1/60 seconds and `max_sub_steps` is 3.

Parameters

  world | The physics world.
  fixed_time_step | size of the internal simulation step, in seconds.
  max_sub_steps | maximum number of steps that simulation is allowed to take at each simulation tick.

Note
  The unit used for time is seconds.

See also
  ephysics_world_simulation_get().

## ephysics_world_simulation_get()

EAPI void ephysics_world_simulation_get | ( | const EPhysics_World * | world,
|  | double * | fixed_time_step,
|  | int * | max_sub_steps )

Get world simulation's fixed time step and max number of sub steps configuration.

Parameters

  world | The physics world.
  fixed_time_step | size of the internal simulation step, in seconds.
  max_sub_steps | maximum number of steps that simulation is allowed to take at each simulation tick.

See also
  ephysics_world_simulation_set() for details.

## ephysics_world_point_light_position_set()

EAPI void ephysics_world_point_light_position_set | ( | EPhysics_World * | world,
|  | Evas_Coord | lx,
|  | Evas_Coord | ly,
|  | Evas_Coord | lz )

Set position of point light to be applied on the scene.

It will perform lighting calculations on the evas map applied on evas objects associated with all the bodies to have light applied over.

This is used to apply lighting calculations (from a single light source) to a given object. The R, G and B values of each vertex will be modified to reflect the lighting based on the lixth point coordinates, the light color and the ambient color, and at what angle the map is facing the light source. A surface should have its points be declared in a clockwise fashion if the face is "facing" towards you (as opposed to away from you) as faces have a "logical" side for lighting.

More details can be found on evas_map_util_3d_lighting() documentation, since this function is used internally by EPhysics.

There are two ways of setting a body to receive lighting. One is to simple set all the bodies to be affected, with ephysics_world_light_all_bodies_set(). The other, is to set each body individually, with ephysics_body_light_set().

By default, point light is set to position (0, 0, -200) and has white color (r=255, g=255, b=255). The ambient color is black (r=0, g=0, b=0). But no body will be affected. No change will be visible until some bodies are set to be enlightened.

Parameters

  world | The physics world.
  lx | X coordinate in space of light point
  ly | Y coordinate in space of light point
  lz | Z coordinate in space of light point

See also
  ephysics_world_point_light_position_get().
  ephysics_world_point_light_color_set().
  ephysics_world_ambient_light_color_set().

## ephysics_world_point_light_color_set()

EAPI void ephysics_world_point_light_color_set | ( | EPhysics_World * | world,
|  | int | lr,
|  | int | lg,
|  | int | lb )

Set color of point light to be applied on the scene.

By default color of point light is r=255, g=255, b=255.

Parameters

  world | The physics world.
  lr | light red value (0 - 255)
  lg | light green value (0 - 255)
  lb | light blue value (0 - 255)

See also
  ephysics_world_point_light_position_set() for more details.
  ephysics_world_point_light_color_get().

## ephysics_world_ambient_light_color_set()

EAPI void ephysics_world_ambient_light_color_set | ( | EPhysics_World * | world,
|  | int | ar,
|  | int | ag,
|  | int | ab )

Set color of the ambient light to be applied on the scene.

By default, ambient color is set to r=0, g=0, b=0.

Parameters

  world | The physics world.
  ar | ambient color red value (0 - 255)
  ag | ambient color green value (0 - 255)
  ab | ambient color blue value (0 - 255)

See also
  ephysics_world_point_light_position_set() for more details.
  ephysics_world_ambient_light_color_get().

## ephysics_world_point_light_position_get()

EAPI void ephysics_world_point_light_position_get | ( | const EPhysics_World * | world,
|  | Evas_Coord * | lx,
|  | Evas_Coord * | ly,
|  | Evas_Coord * | lz )

Get position of point light applied on the scene.

Parameters

  world | The physics world.
  lx | X coordinate in space of light point
  ly | Y coordinate in space of light point
  lz | Z coordinate in space of light point

See also
  ephysics_world_point_light_position_set() for details.

## ephysics_world_point_light_color_get()

EAPI void ephysics_world_point_light_color_get | ( | const EPhysics_World * | world,
|  | int * | lr,
|  | int * | lg,
|  | int * | lb )

Get color of point light applied on the scene.

By default color of point light is r=255, g=255, b=255.

Parameters

  world | The physics world.
  lr | light red value (0 - 255)
  lg | light green value (0 - 255)
  lb | light blue value (0 - 255)

See also
  ephysics_world_point_light_position_set() for more details.
  ephysics_world_point_light_color_set().

## ephysics_world_ambient_light_color_get()

EAPI void ephysics_world_ambient_light_color_get | ( | const EPhysics_World * | world,
|  | int * | ar,
|  | int * | ag,
|  | int * | ab )

Set color of the ambient light to be applied on the scene.

By default, ambient color is set to r=0, g=0, b=0.

Parameters

  world | The physics world.
  ar | ambient color red value (0 - 255)
  ag | ambient color green value (0 - 255)
  ab | ambient color blue value (0 - 255)

See also
  ephysics_world_point_light_position_set() for more details.
  ephysics_world_ambient_light_color_set().

## ephysics_world_light_all_bodies_set()

EAPI void ephysics_world_light_all_bodies_set | ( | EPhysics_World * | world,
|  | Eina_Bool | enable )

Set if light should be applied over all the bodies.

Parameters

  world | The physics world.
  enable | `EINA_TRUE` if light should be obligatory applied over all the bodies, or `EINA_FALSE` if it only should be applied on bodies with light property set.

See also
  ephysics_world_point_light_position_set() for more details.
  ephysics_world_light_all_bodies_get().

Examples
  test_bouncing_ball.c.

## ephysics_world_light_all_bodies_get()

EAPI Eina_Bool ephysics_world_light_all_bodies_get | ( | const EPhysics_World * | world | ) |

Get light setting regarding being applied over all the bodies.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if light will be obligatory applied over all the bodies, or `EINA_FALSE` if it only will be applied on bodies with light property set, or on error.

See also
  ephysics_world_light_all_bodies_set() for details.

## ephysics_world_stack_enable_set()

EAPI void ephysics_world_stack_enable_set | ( | EPhysics_World * | world,
|  | Eina_Bool | enabled )

Enable / disable stacking based on bodies z coordinates.

Evas objects associated to bodies will be restacked when it's enabled. So if a body A has coordinates x = 10, y = 10, z = 8 and a body B has coordinates x = 10, y = 10, z = 10, the evas object associated to B will be displayed below the evas object associated to A.

Evas objects will be restacked at each simulation tick. It's enabled by default, and disabling it can lead to wrong scenarios when movement on Z axis is enabled or when cloths are used.

But disabling it can save performance, so if you won't face these scenarios, it safe to disable it, since no evas object will be moved to be below or above others.

Parameters

  world | The physics world.
  enabled | If `EINA_TRUE`, stacking based on Z coordinates will be enabled, otherwise it will be disabled.

See also
  ephysics_world_stack_enable_get()
  ephysics_body_evas_object_set()

## ephysics_world_stack_enable_get()

EAPI Eina_Bool ephysics_world_stack_enable_get | ( | const EPhysics_World * | world | ) |

Get stacking status of world.

Stacking based on bodies z coordinates can be enabled or disabled.

Parameters

  world | The physics world.

Returns
  `EINA_TRUE` if it's running, or `EINA_FALSE` if it's paused or on error.

See also
  ephysics_world_stack_enable_set() for more details.