/* * ============================================================ * FILE: camera.c * * PURPOSE: A player-controlled third-person camera in the spirit of SM64's * "Lakitu": it orbits the player, but it does NOT glue the player * to the center of the screen. The player moves around inside a * screen-space zone and the camera only moves when it has to. The * resulting off-center shots are what give it a cinematic feel. * * FITS IN: Implements camera.h. Reads Input.look and Input.recenter_pressed * (controls.h) and the player's position and facing (passed in * by main.c). * Produces matrices for render.c and a yaw for player.c. * * IMPLEMENT: * - The camera is described by WHERE THE PLAYER SITS ON SCREEN (`framing`, * in NDC) and HOW FAR AWAY they are (`depth`), plus yaw/pitch. The eye * position is derived from those every tick. That makes the zone rules * simple clamps on `framing`, and it makes orbiting keep the player at the * same screen spot (the camera orbits the PLAYER, not empty space). * * - Two screen boxes, given in window fractions (0 = left/bottom, 1 = * right/top) and converted with NDC = 2 * fraction - 1: * resting zone where a stopped player may sit without the camera moving * x: 1/3 + CAMERA_ZONE_INSET .. 2/3 - CAMERA_ZONE_INSET * y: 1/3 + CAMERA_ZONE_INSET .. CAMERA_ZONE_TOP * running bound the resting zone grown by CAMERA_ZONE_INSET on every side * x: 1/3 .. 2/3 (the thirds lines) * y: 1/3 .. CAMERA_ZONE_TOP + CAMERA_ZONE_INSET * The top is lower than the thirds on purpose: it keeps the view AHEAD of * a player running away from the camera open, so upcoming obstacles stay * visible. The "subject" is the player's feet + CAMERA_TARGET_HEIGHT. * * - camera_init(c, follow_point): yaw 0 (camera on +Z looking toward -Z), * pitch CAMERA_PITCH_DEFAULT, distance and depth CAMERA_DISTANCE, framing * (0,0), not recentering, subject = follow_point + target height. Place it. * * - Recentering is a one-shot glide to "centered, behind the player". When * Input.recenter_pressed arrives, capture recenter_yaw = the yaw that puts * the camera behind the player's facing (follow_facing + PI). Until the glide * finishes, the camera rides along rigidly with the player (their movement * does NOT change framing/depth), so it always finishes even while they run. * Then the normal zone rules take over again with the player centered. * The right stick still works mid-glide: it steers recenter_yaw along with * the view, so there's no fight (and a wobble while clicking is harmless). * * - Sideways runs get two extra behaviors, both scaled by the "lateral * share": how much of the player's horizontal motion goes across the * screen (-1 = straight left, +1 = straight right, 0 = straight toward/away * from the camera or not moving horizontally). Up/down runs are untouched. * lead room the camera works AHEAD of the player so they drift to * the TRAILING side of the running bound (running right * -> left thirds line), leaving open screen in the * direction they're heading, for upcoming obstacles. * back-quarter swing the camera slowly turns toward CAMERA_SWING_OFFSET * off directly-behind the player's motion, on the side * it's already on, so a side-on view becomes a view down * the run. Inside that back quarter it doesn't swing. * Controls stay camera-relative, so holding the stick * sideways while it swings makes the player arc, like * Mario circling in SM64. That's intentional. * * - camera_update(c, in, follow_point, follow_facing, aspect, dt): * 1. Movement check: the subject counts as "moving" if it changed since * last tick (this includes slowing to a stop and jumping in place). * On recenter_pressed, start a recenter (see above). * 2. Orbit: yaw -= look.x * CAMERA_YAW_SPEED * dt (the sign is flipped so * stick-right turns the view right), pitch += look.y * * CAMERA_PITCH_SPEED * dt, clamp pitch, wrap yaw. `framing` is kept, * so the player stays at the same screen spot while orbiting. While * recentering, apply the same yaw change to recenter_yaw, then ease yaw * toward recenter_yaw (the short way around) at CAMERA_RECENTER_RATE. * Otherwise, while moving, apply the back-quarter swing: approach its * goal yaw at CAMERA_SWING_SPEED * |lateral share| rad/s (constant rate, * so the swing is slow and even). Framing is kept here too. * 3. Hold still (except while recentering): the camera does NOT follow * vertically or in depth by default. Project how far the subject moved * onto the camera's up/forward axes. Up changes where they sit on * screen, and forward changes `depth`. Sideways motion is NOT turned * into screen drift: horizontally the camera keeps pace with the * player, and the lead-room rule alone decides where they sit across * the screen (a raw drift would push them to the LEADING side, which is * exactly what lead room avoids). * 4. Depth: while recentering, ease `depth` to `distance` at * CAMERA_RECENTER_RATE. Otherwise, only while the player moves, ease it * at CAMERA_FOLLOW_RATE, so running toward/away from the camera briefly * changes the player's size. Once they stop, the depth freezes too: a * still player inside the zone means a still camera. * 5. Framing rules, in priority order: * recentering -> ease framing to (0,0) at CAMERA_RECENTER_RATE; the * recenter ends once framing, depth and yaw all arrive. * not moving -> ease framing to the nearest point of the resting zone * at CAMERA_SETTLE_RATE. Inside the zone that point is * the player itself, so the camera doesn't move at all. * moving -> lead room: ease framing.x toward the running bound's * trailing edge at CAMERA_LEAD_RATE * |lateral share|. * always -> hard clamp framing to the running bound. On runs * toward/away from the camera, that's what pushes the * camera along with the player. * Then keep the eye at least CAMERA_MIN_HEIGHT above the player's feet * (at low pitch, putting the player high on screen would otherwise sink * the eye into the floor). * 6. Place the eye: subject - right*side - up*lift - forward*depth, where * side/lift are the framing converted to meters at `depth`. target = * eye + forward * distance, which keeps the YAW CONVENTION exact. * Every ease is exponential (1 - e^(-rate*dt)) and snaps when within a * hair of its goal, so a settled camera is truly still. * * - camera_view(): mat4_look_at(position, target, (0,1,0)). * - camera_projection(c, aspect): mat4_perspective(CAMERA_FOV_DEG in radians, * aspect, CAMERA_NEAR, CAMERA_FAR). * * CONVENTIONS: Radians internally; FOV converted from degrees where used. * Framing is in NDC so it matches what you see on screen, and it * converts to meters via depth * tan(fov/2) (times aspect for x). * * NOT IN SCOPE: Camera collision, snapping directly behind the player on its * own (only the recenter button does that), shake, vertical * look-ahead. (Good candidates for later tuning, not for now.) * * DONE WHEN: A player standing anywhere inside the resting zone never moves * the camera. Running lets the player reach, but never pass, the * running bound. Stopping outside the resting zone eases the camera * until the player sits on the zone's edge. The recenter button * glides the camera behind the player with them centered, finishes * even mid-run, and leaves the zone rules working afterward. The * right stick orbits around the player without moving them on screen. * A sideways run slowly carries the player to the trailing thirds * line and swings the camera to ~30 deg off behind them, while runs * straight toward/away from the camera behave as before. * ============================================================ */ #include "camera.h" #include "config.h" #define THIRD (1.0f / 3.0f) /* the thirds lines, as window fractions */ #define STILL_EPSILON 1e-5f /* m moved per tick below which the player is "still" */ #define EASE_SNAP 1e-3f /* eases jump to their goal when this close */ /* The camera's axes for a given orbit. forward points from the eye into the * scene; right and up are the screen's right and up in world space. */ typedef struct { Vec3 right, up, forward; } Basis; static Basis camera_basis(float yaw, float pitch) { float sy = sinf(yaw), cy = cosf(yaw), sp = sinf(pitch), cp = cosf(pitch); Basis b; b.forward = vec3_make(-sy * cp, -sp, -cy * cp); /* minus the orbit direction */ b.right = vec3_make(cy, 0.0f, -sy); b.up = vec3_make(-sy * sp, cp, -cy * sp); return b; } /* The point we frame: a bit above the player's feet. */ static Vec3 subject_point(Vec3 follow_point) { return vec3_add(follow_point, vec3_make(0.0f, CAMERA_TARGET_HEIGHT, 0.0f)); } /* How many meters one NDC unit spans at a given depth. The screen edge * (NDC 1) is depth * tan(fov/2) away from the view center, and the * horizontal field is wider by the aspect ratio. */ static Vec2 meters_per_ndc(float depth, float aspect) { float half_height = depth * tanf(CAMERA_FOV_DEG * (M3D_PI / 180.0f) * 0.5f); return vec2_make(half_height * aspect, half_height); } /* Exponential ease: covers the same fraction of the remaining gap every * second no matter the tick rate. Snaps when close so settling ends. */ static float ease_toward(float current, float goal, float rate, float dt) { float next = current + (goal - current) * (1.0f - expf(-rate * dt)); return fabsf(goal - next) < EASE_SNAP ? goal : next; } static Vec2 ease_toward_vec2(Vec2 current, Vec2 goal, float rate, float dt) { return vec2_make(ease_toward(current.x, goal.x, rate, dt), ease_toward(current.y, goal.y, rate, dt)); } /* ease_toward for angles: turns the SHORT way around the circle. */ static float ease_toward_angle(float current, float goal, float rate, float dt) { float next = current + wrap_angle(goal - current) * (1.0f - expf(-rate * dt)); return fabsf(wrap_angle(goal - next)) < EASE_SNAP ? goal : wrap_angle(next); } /* Derives the eye and look-at point from the framing description. */ static void place_camera(Camera *c, float aspect) { Basis b = camera_basis(c->yaw, c->pitch); Vec2 scale = meters_per_ndc(c->depth, aspect); Vec3 eye = c->subject; eye = vec3_sub(eye, vec3_scale(b.right, c->framing.x * scale.x)); eye = vec3_sub(eye, vec3_scale(b.up, c->framing.y * scale.y)); eye = vec3_sub(eye, vec3_scale(b.forward, c->depth)); c->position = eye; c->target = vec3_add(eye, vec3_scale(b.forward, c->distance)); } /* Rotates around the player with the right stick. Right stick RIGHT turns the VIEW right, * so the camera swings LEFT around the player. Forward is * (-sin(yaw), 0, -cos(yaw)), so turning it toward the camera's right * (+X at yaw 0) needs yaw to DECREASE, hence the -=. */ static void orbit(Camera *c, const Input *in, float dt) { c->yaw -= in->look.x * CAMERA_YAW_SPEED * dt; c->pitch += in->look.y * CAMERA_PITCH_SPEED * dt; c->pitch = clampf(c->pitch, CAMERA_PITCH_MIN, CAMERA_PITCH_MAX); c->yaw = wrap_angle(c->yaw); } /* A rectangle on screen, in NDC. */ typedef struct { Vec2 min, max; } ScreenBox; /* Window fraction (0 = left/bottom, 1 = right/top) -> NDC (-1 .. 1). */ static float window_to_ndc(float fraction) { return 2.0f * fraction - 1.0f; } static ScreenBox screen_box(float left, float right, float bottom, float top) { ScreenBox box; box.min = vec2_make(window_to_ndc(left), window_to_ndc(bottom)); box.max = vec2_make(window_to_ndc(right), window_to_ndc(top)); return box; } /* Where a stopped player may sit without the camera moving. */ static ScreenBox resting_zone(void) { return screen_box(THIRD + CAMERA_ZONE_INSET, 2.0f * THIRD - CAMERA_ZONE_INSET, THIRD + CAMERA_ZONE_INSET, CAMERA_ZONE_TOP); } /* How far a moving player may drift before pushing the camera along: the * resting zone grown by CAMERA_ZONE_INSET on every side. */ static ScreenBox running_bound(void) { return screen_box(THIRD, 2.0f * THIRD, THIRD, CAMERA_ZONE_TOP + CAMERA_ZONE_INSET); } static Vec2 clamp_to_box(Vec2 p, ScreenBox box) { return vec2_make(clampf(p.x, box.min.x, box.max.x), clampf(p.y, box.min.y, box.max.y)); } /* How much of the player's horizontal motion goes across the screen: * -1 = straight left, +1 = straight right, 0 = straight toward/away from the * camera (or no horizontal motion at all, like a jump in place). */ static float lateral_share(Vec3 moved_by, Vec3 right) { Vec3 flat = vec3_make(moved_by.x, 0.0f, moved_by.z); float len = vec3_length(flat); if (len < STILL_EPSILON) return 0.0f; return vec3_dot(flat, right) / len; /* right is horizontal and unit length */ } /* Back-quarter swing: on a sideways run, slowly turn the camera toward * CAMERA_SWING_OFFSET off directly-behind the player's motion, staying on the * side it's already on. A side-on view becomes a view down the run, without * ever snapping squarely behind. Inside that back quarter, nothing happens. */ static void swing_toward_back_quarter(Camera *c, Vec3 moved_by, float lateral, float dt) { if (lateral == 0.0f) return; float heading = atan2f(moved_by.x, moved_by.z); /* same convention as facing_yaw */ float behind = wrap_angle(heading + M3D_PI); /* camera yaw directly behind */ float off = wrap_angle(c->yaw - behind); /* signed: which side we're on */ if (fabsf(off) <= CAMERA_SWING_OFFSET) return; float goal = behind + (off > 0.0f ? CAMERA_SWING_OFFSET : -CAMERA_SWING_OFFSET); c->yaw = approach_angle(c->yaw, goal, CAMERA_SWING_SPEED * fabsf(lateral) * dt); } /* Step 5: the framing rules (see the prompt above). */ static void apply_framing_rules(Camera *c, bool subject_moving, float lateral, float dt) { if (c->recentering) { /* The glide is over once every part of the shot has arrived; from * then on the normal zone rules apply, starting from center. */ c->framing = ease_toward_vec2(c->framing, vec2_make(0.0f, 0.0f), CAMERA_RECENTER_RATE, dt); if (c->framing.x == 0.0f && c->framing.y == 0.0f && c->depth == c->distance && c->yaw == c->recenter_yaw) c->recentering = false; } else if (!subject_moving) { /* The nearest point of the resting zone. If the player is inside the * zone this IS the player, so nothing moves: the shot holds. If they * stopped outside it, the camera drifts until they're on its edge. */ Vec2 edge = clamp_to_box(c->framing, resting_zone()); c->framing = ease_toward_vec2(c->framing, edge, CAMERA_SETTLE_RATE, dt); } else if (lateral != 0.0f) { /* Lead room: on a sideways run, work the player toward the TRAILING * edge (running right -> left thirds line), so the open screen is in * the direction they're heading and upcoming obstacles stay visible. */ ScreenBox bound = running_bound(); float trailing_edge = lateral > 0.0f ? bound.min.x : bound.max.x; c->framing.x = ease_toward(c->framing.x, trailing_edge, CAMERA_LEAD_RATE * fabsf(lateral), dt); } /* Hard limit, always. Running toward/away from the camera, the player may * drift out to the running bound but never past it; past that, the camera * is pushed along. (Across the screen, lead room already stays inside.) */ c->framing = clamp_to_box(c->framing, running_bound()); } /* The highest the player may sit on screen (NDC y) before the eye would * drop below CAMERA_MIN_HEIGHT above their feet. The eye's height relative * to the feet is TARGET_HEIGHT - lift*cos(pitch) + depth*sin(pitch), solved * for lift (meters), then converted to NDC. */ static float max_framing_y(const Camera *c, float meters_per_ndc_y) { float max_lift = (CAMERA_TARGET_HEIGHT - CAMERA_MIN_HEIGHT + c->depth * sinf(c->pitch)) / cosf(c->pitch); return max_lift / meters_per_ndc_y; } void camera_init(Camera *c, Vec3 follow_point) { c->yaw = 0.0f; /* on +Z, looking toward -Z */ c->pitch = CAMERA_PITCH_DEFAULT; c->distance = CAMERA_DISTANCE; c->depth = CAMERA_DISTANCE; c->framing = vec2_make(0.0f, 0.0f); c->subject = subject_point(follow_point); c->recentering = false; c->recenter_yaw = 0.0f; /* The aspect ratio only matters for a non-zero framing, which is 0 here. */ place_camera(c, 1.0f); } void camera_update(Camera *c, const Input *in, Vec3 follow_point, float follow_facing, float aspect, float dt) { /* 1. Did the player move since last tick? And start a recenter glide * toward the shot from behind the player (opposite their facing). */ Vec3 subject = subject_point(follow_point); Vec3 moved_by = vec3_sub(subject, c->subject); bool subject_moving = vec3_length(moved_by) > STILL_EPSILON; c->subject = subject; if (in->recenter_pressed) { c->recentering = true; c->recenter_yaw = wrap_angle(follow_facing + M3D_PI); } /* 2. Orbit around the player. Mid-recenter, the stick turns the glide's * goal along with the view, so the two never fight. Otherwise a * sideways run slowly swings the camera toward the back quarter. */ float yaw_before = c->yaw; orbit(c, in, dt); float lateral = 0.0f; /* sideways effects are off during a recenter glide */ if (!c->recentering) lateral = lateral_share(moved_by, camera_basis(c->yaw, c->pitch).right); if (c->recentering) { c->recenter_yaw = wrap_angle(c->recenter_yaw + wrap_angle(c->yaw - yaw_before)); c->yaw = ease_toward_angle(c->yaw, c->recenter_yaw, CAMERA_RECENTER_RATE, dt); } else { swing_toward_back_quarter(c, moved_by, lateral, dt); } Basis b = camera_basis(c->yaw, c->pitch); /* 3. Hold still: with the eye fixed, the player's motion changes where * they sit relative to it. Work in meters, since NDC depends on depth. * Mid-recenter the camera rides along with the player instead, so their * running can't stop the glide from finishing. Sideways motion is left * out on purpose: horizontally the camera keeps pace, and the lead-room * rule (step 5) decides where the player sits across the screen. */ Vec2 scale = meters_per_ndc(c->depth, aspect); float side = c->framing.x * scale.x; float lift = c->framing.y * scale.y; if (!c->recentering) { lift += vec3_dot(moved_by, b.up); c->depth += vec3_dot(moved_by, b.forward); } /* 4. Depth lag: while the player moves, the distance catches back up a * little late, which lets you feel them running toward or away from you. * It freezes when they stop, so a still player means a still camera. */ if (c->recentering) c->depth = ease_toward(c->depth, c->distance, CAMERA_RECENTER_RATE, dt); else if (subject_moving) c->depth = ease_toward(c->depth, c->distance, CAMERA_FOLLOW_RATE, dt); scale = meters_per_ndc(c->depth, aspect); c->framing = vec2_make(side / scale.x, lift / scale.y); /* 5. Zone rules, then keep the eye out of the floor. */ apply_framing_rules(c, subject_moving, lateral, dt); float max_y = max_framing_y(c, scale.y); if (c->framing.y > max_y) c->framing.y = max_y; /* 6. Derive the eye from the framing. */ place_camera(c, aspect); } float camera_yaw(const Camera *c) { return c->yaw; } Mat4 camera_view(const Camera *c) { return mat4_look_at(c->position, c->target, vec3_make(0.0f, 1.0f, 0.0f)); } Mat4 camera_projection(const Camera *c, float aspect) { (void)c; /* every camera shares the same lens for now */ float fovy_rad = CAMERA_FOV_DEG * (M3D_PI / 180.0f); return mat4_perspective(fovy_rad, aspect, CAMERA_NEAR, CAMERA_FAR); }