Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
2D Physics
Collaboration diagram for 2D Physics:

Data Structures

struct  bj_particle_2d
struct  bj_angular_2d
struct  bj_rigid_body_2d

Functions

struct bj_vec2 bj_compute_kinematics_2d (struct bj_vec2 position, struct bj_vec2 velocity, struct bj_vec2 acceleration, bj_real time)
struct bj_vec2 bj_compute_kinematics_velocity_2d (struct bj_vec2 velocity, struct bj_vec2 acceleration, bj_real time)
void bj_apply_particle_force_2d (struct bj_particle_2d *particle, const struct bj_vec2 force)
void bj_step_particle_2d (struct bj_particle_2d *particle, bj_real dt)
void bj_apply_gravity_2d (struct bj_particle_2d *particle, bj_real gravity)
void bj_apply_point_gravity_2d (struct bj_particle_2d *restrict particle_from, const struct bj_particle_2d *restrict particle_to, const bj_real gravity_factor)
void bj_apply_point_gravity_softened_2d (struct bj_particle_2d *restrict particle_from, const struct bj_particle_2d *restrict particle_to, const bj_real gravity_factor, const bj_real epsilon)
void bj_apply_drag_2d (struct bj_particle_2d *particle, bj_real k1, bj_real k2)
bj_real bj_compute_particle_drag_coefficient_2d (const struct bj_vec2 vel, const bj_real k1, const bj_real k2)
struct bj_vec2 bj_compute_particle_drag_force_2d (struct bj_vec2 vel, const bj_real k1, const bj_real k2)
void bj_apply_torque_2d (struct bj_angular_2d *angular, bj_real torque)
void bj_apply_angular_torque_2d (struct bj_angular_2d *angular, bj_real torque)
void bj_step_angular_2d (struct bj_angular_2d *angular, bj_real delta_time)
void bj_apply_rigid_body_force_2d (struct bj_rigid_body_2d *body, const struct bj_vec2 force)
void bj_apply_rigidbody_force_2d (struct bj_rigid_body_2d *body, const struct bj_vec2 force)
void bj_step_rigid_body_2d (struct bj_rigid_body_2d *body, bj_real delta_time)

Detailed Description

Physics for things that move on a flat 2D plane: positions, velocities, forces, particles.

The 2D version of the parent physics topic. The 2D helpers work in terms of bj_vec2 (a (x, y) pair) instead of plain scalars, but the ideas are the same: compute where a body is after some elapsed time from its starting position, velocity, and acceleration; or build up a per-frame simulation by accumulating forces on a particle (a point with a mass) and integrating to update its velocity and position.

Use the kinematics helpers (bj_compute_kinematics_2d and friends) when acceleration is constant and you just want to know "where will this be at time t?": projectiles, falling under gravity, anything ballistic.

Use the particle helpers (bj_step_particle_2d and friends) when forces change over time and you want to step the simulation frame-by-frame: orbiting bodies, soft springs, anything where the acceleration depends on what other things are doing.

See physics_kinematics.c and physics_particle.c for runnable demos of each.

Same unit convention as the parent topic

SI by default (metres and seconds), but the formulas are dimensionally consistent, pick any unit system you like, as long as every input to one formula uses the same one. [L] means "length", [T] means "time", [L T^-1] means "length per time" (a velocity), [L T^-2] means "length per time per time" (an acceleration).


Data Structure Documentation

◆ bj_particle_2d

struct bj_particle_2d

2D point mass state and physical properties.

Positions, velocities, accelerations and force accumulator are expressed in world space. Damping is the share of velocity kept per unit of time: each step multiplies the velocity by damping^dt, so 1 keeps all of it. Mass is represented as inverse mass; use 0 to represent an immovable object.

Parameters
positionCurrent 2D position [L]
velocityCurrent 2D velocity [L T^-1]
accelerationCurrent 2D acceleration [L T^-2]
forcesAccumulated force for the next integration step [M L T^-2]
dampingFraction of velocity kept per unit of time: 0 stops it, below 1 damps it, above 1 magnifies it
inverse_massInverse of mass [M^-1]; 0 means infinite mass
Examples
physics_particle.c.

Definition at line 100 of file physics_2d.h.

Collaboration diagram for bj_particle_2d:
Data Fields
struct bj_vec2 acceleration
bj_real damping
struct bj_vec2 forces
bj_real inverse_mass
struct bj_vec2 position
struct bj_vec2 velocity

◆ bj_angular_2d

struct bj_angular_2d

Angular.

2D angular state and properties (scalar angle about Z).

Angle units are radians. Damping is the share of angular velocity kept per unit of time: each step multiplies it by damping^dt. Inertia is represented via inverse inertia; use 0 for infinite inertia.

Parameters
valueAngle theta [rad]
velocityAngular velocity omega [rad T^-1]
accelerationAngular acceleration alpha [rad T^-2]
torqueAccumulated torque tau for next step [M L^2 T^-2]
dampingFraction of angular velocity kept per unit of time: 0 stops it, below 1 damps it, above 1 magnifies it
inverse_inertiaInverse moment of inertia I^-1 [M^-1 L^-2]

Definition at line 254 of file physics_2d.h.

Data Fields
bj_real acceleration
bj_real damping
bj_real inverse_inertia
bj_real torque
bj_real value
bj_real velocity

◆ bj_rigid_body_2d

struct bj_rigid_body_2d

Rigid body with translational and angular components.

Particle terms are in world space. Angle is about +Z.

Parameters
particleLinear state (position, velocity, forces)
angularAngular state (theta, omega, tau)

Definition at line 304 of file physics_2d.h.

Collaboration diagram for bj_rigid_body_2d:
Data Fields
struct bj_angular_2d angular
struct bj_particle_2d particle

Function Documentation

◆ bj_apply_angular_torque_2d()

void bj_apply_angular_torque_2d ( struct bj_angular_2d * angular,
bj_real torque )
Deprecated
Renamed to bj_apply_torque_2d. Removed in 2.0.

◆ bj_apply_drag_2d()

void bj_apply_drag_2d ( struct bj_particle_2d * particle,
bj_real k1,
bj_real k2 )

Apply quadratic + linear drag to a particle's accumulator.

Drag magnitude = k1 * |v| + k2 * |v|^2 along -v_hat.

Parameters
particleParticle to affect, or NULL, which does nothing
k1Linear drag coefficient [M T^-1]
k2Quadratic drag coefficient [M L^-1]

◆ bj_apply_gravity_2d()

void bj_apply_gravity_2d ( struct bj_particle_2d * particle,
bj_real gravity )

Apply constant downward gravity in world space to a particle.

Adds force F = m * g * (0, -1) assuming -Y is "down", and nothing to an immovable particle (inverse mass 0).

Parameters
particleParticle to affect, or NULL, which does nothing
gravityGravitational acceleration magnitude g >= 0 [L T^-2]

◆ bj_apply_particle_force_2d()

void bj_apply_particle_force_2d ( struct bj_particle_2d * particle,
const struct bj_vec2 force )

Add a force to a particle's accumulator.

The force will be used on the next integration step, then should be cleared by the step routine.

Parameters
particleParticle to modify, or NULL, which does nothing
forceForce to add [M L T^-2]

◆ bj_apply_point_gravity_2d()

void bj_apply_point_gravity_2d ( struct bj_particle_2d *restrict particle_from,
const struct bj_particle_2d *restrict particle_to,
const bj_real gravity_factor )

Apply point gravity from one particle to another.

Pulls particle_from toward particle_to, adding F = G m1 m2 r_hat / r^2 to particle_from only, with gravity_factor = G. Adds nothing when either particle has an inverse mass of 0.

Parameters
particle_fromParticle receiving the force, or NULL, which does nothing
particle_toSource particle, or NULL, which does nothing
gravity_factorGravitational constant G [L^3 M^-1 T^-2]

◆ bj_apply_point_gravity_softened_2d()

void bj_apply_point_gravity_softened_2d ( struct bj_particle_2d *restrict particle_from,
const struct bj_particle_2d *restrict particle_to,
const bj_real gravity_factor,
const bj_real epsilon )

Apply softened point gravity to avoid singularities at small r.

Uses F proportional to r / (r^2 + epsilon^2)^(3/2).

Parameters
particle_fromParticle receiving the force, or NULL, which does nothing
particle_toSource particle, or NULL, which does nothing
gravity_factorGravitational constant G [L^3 M^-1 T^-2]
epsilonSoftening length epsilon >= 0 [L]
Examples
physics_particle.c.

Referenced by physics().

◆ bj_apply_rigid_body_force_2d()

void bj_apply_rigid_body_force_2d ( struct bj_rigid_body_2d * body,
const struct bj_vec2 force )

Apply a world-space force at the center of mass.

Only affects linear state. Use external torque to affect rotation.

Parameters
bodyRigid body to modify, or NULL, which does nothing
forceForce to add [M L T^-2]

◆ bj_apply_rigidbody_force_2d()

void bj_apply_rigidbody_force_2d ( struct bj_rigid_body_2d * body,
const struct bj_vec2 force )
Deprecated
Renamed to bj_apply_rigid_body_force_2d. Removed in 2.0.

◆ bj_apply_torque_2d()

void bj_apply_torque_2d ( struct bj_angular_2d * angular,
bj_real torque )

Add torque to the angular accumulator.

Parameters
angularAngular state to modify, or NULL, which does nothing
torqueTorque to add tau [M L^2 T^-2]

◆ bj_compute_kinematics_2d()

struct bj_vec2 bj_compute_kinematics_2d ( struct bj_vec2 position,
struct bj_vec2 velocity,
struct bj_vec2 acceleration,
bj_real time )

Integrate constant-acceleration 2D kinematics: position at time t.

Uses: out = position + velocity * time + 0.5 * acceleration * time^2.

Parameters
positionInitial position [L]
velocityInitial velocity [L T^-1]
accelerationConstant acceleration [L T^-2]
timeElapsed time t [T]
Returns
Output position at time t [L]
Examples
physics_kinematics.c.

Referenced by bj_compute_kinematics_2d(), and update().

◆ bj_compute_kinematics_velocity_2d()

struct bj_vec2 bj_compute_kinematics_velocity_2d ( struct bj_vec2 velocity,
struct bj_vec2 acceleration,
bj_real time )

Integrate constant-acceleration 2D kinematics: velocity at time t.

Uses: out = velocity + acceleration * time.

Parameters
velocityInitial velocity [L T^-1]
accelerationConstant acceleration [L T^-2]
timeElapsed time t [T]
Returns
Output velocity at time t [L T^-1]

Referenced by bj_compute_kinematics_velocity_2d().

◆ bj_compute_particle_drag_coefficient_2d()

bj_real bj_compute_particle_drag_coefficient_2d ( const struct bj_vec2 vel,
const bj_real k1,
const bj_real k2 )

Return scalar drag coefficient for a velocity.

Computes c = k1 * |v| + k2 * |v|^2.

Parameters
velVelocity vector [L T^-1]
k1Linear drag coefficient [M T^-1]
k2Quadratic drag coefficient [M L^-1]
Returns
c >= 0 [M T^-1]

◆ bj_compute_particle_drag_force_2d()

struct bj_vec2 bj_compute_particle_drag_force_2d ( struct bj_vec2 vel,
const bj_real k1,
const bj_real k2 )

Compute drag force for a velocity.

result = -c * v_hat with c as above. Zero if vel is near zero.

Parameters
velVelocity vector [L T^-1]
k1Linear drag coefficient [M T^-1]
k2Quadratic drag coefficient [M L^-1]
Returns
Output force [M L T^-2]

Referenced by bj_compute_particle_drag_force_2d().

◆ bj_step_angular_2d()

void bj_step_angular_2d ( struct bj_angular_2d * angular,
bj_real delta_time )

Semi-implicit Euler step for angular motion.

Integrates alpha and omega, applies damping, and advances theta. Clears torque. An angle that leaves [-π, π] is brought back into it by whole turns, however many the step took.

Parameters
angularAngular state to integrate, or NULL, which does nothing
delta_timeTime step [T]

◆ bj_step_particle_2d()

void bj_step_particle_2d ( struct bj_particle_2d * particle,
bj_real dt )

Semi-implicit Euler step for a particle.

Integrates acceleration and velocity, applies damping, and advances position. Clears the force accumulator after use.

Parameters
particleParticle to integrate, or NULL, which does nothing
dtTime step [T]
Examples
physics_particle.c.

Referenced by physics().

◆ bj_step_rigid_body_2d()

void bj_step_rigid_body_2d ( struct bj_rigid_body_2d * body,
bj_real delta_time )

Step rigid body linear and angular states.

Calls the corresponding particle and angular integrators. Clears accumulators.

Parameters
bodyRigid body to integrate, or NULL, which does nothing
delta_timeTime step [T]