summaryrefslogtreecommitdiff
path: root/platformer/src/camera.h
blob: 7dc2cc14f680d134c858864f7e17f7b2916e75f1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
/*
 * ============================================================
 * FILE:        camera.h
 *
 * PURPOSE:     Public interface for the third-person "framing" camera: it
 *              orbits the player (right stick), and instead of pinning the player
 *              to the center of the screen it lets them wander inside a screen-
 *              space zone, SM64-style. Off-center framing is intentional.
 *
 * FITS IN:     main.c calls camera_update() each tick AFTER player_update().
 *              player_update() receives camera_yaw() so "stick up" means "away
 *              from the camera". render.c reads camera_view()/camera_projection().
 *
 * INTERFACE:   Use these exact names:
 *
 *   typedef struct Camera {
 *       Vec3  target;       derived look-at point, `distance` ahead of the eye
 *       float yaw;          orbit angle around the player, radians
 *       float pitch;        angle above horizontal, radians
 *       float distance;     resting distance from eye to player, meters
 *       Vec3  position;     derived eye position (recomputed in camera_update)
 *       Vec2  framing;      where the player sits on screen, in NDC:
 *                           (0,0) = center, +x = right, +y = up, edges = +-1
 *       float depth;        current eye-to-player distance along the view
 *                           direction; eases toward `distance` (follow lag)
 *       Vec3  subject;      the point we frame (player feet + target height)
 *                           as of last tick, to detect whether they moved
 *       bool  recentering;  true during the recenter glide
 *       float recenter_yaw; where the glide is headed: behind the player
 *       float hands_off_time; seconds since the camera was last moved by hand
 *                           (right stick or recenter), capped at
 *                           CAMERA_AUTO_PITCH_DELAY; drives the auto-pitch
 *       float auto_pitch_speed; current auto-pitch speed, rad/s (>= 0), so the
 *                           tilt can ease in and out instead of moving linearly
 *   } Camera;
 *
 *   void  camera_init(Camera *c, Vec3 follow_point);
 *   void  camera_update(Camera *c, const Input *in, Vec3 follow_point,
 *                       float follow_facing, bool pan_locked, float aspect, float dt);
 *             follow_point = the player's feet position; the camera adds
 *             CAMERA_TARGET_HEIGHT itself. follow_facing = the player's
 *             facing_yaw, used by recenter to swing behind them. pan_locked =
 *             the player is in a locked-pan zone (main.c asks the world): the
 *             camera doesn't swing toward the back quarter on its own (the
 *             stick, recenter, framing and auto-tilt all still work). aspect =
 *             framebuffer width/height, needed because the framing zone is
 *             defined in screen space.
 *   float camera_yaw(const Camera *c);
 *   Mat4  camera_view(const Camera *c);
 *   Mat4  camera_projection(const Camera *c, float aspect);
 *
 *   YAW CONVENTION (player.c relies on this, so keep it exact):
 *     position = target + distance * ( sin(yaw)*cos(pitch),
 *                                      sin(pitch),
 *                                      cos(yaw)*cos(pitch) )
 *     So on the ground plane, the camera's
 *       forward (toward target) = (-sin(yaw), 0, -cos(yaw))
 *       right                   = ( cos(yaw), 0, -sin(yaw))
 *
 *   Include <stdbool.h>, "math3d.h" and "controls.h".
 *
 * CONVENTIONS: Include guard: CAMERA_H.
 *
 * NOT IN SCOPE: Collision with geometry, automatic "behind the player"
 *              rotation, cutscene/fixed cameras, zoom levels.
 *
 * DONE WHEN:   player.c and render.c can be written against this header alone.
 * ============================================================
 */
#ifndef CAMERA_H
#define CAMERA_H

#include <stdbool.h>

#include "controls.h"
#include "math3d.h"

typedef struct Camera {
    Vec3  target;       /* derived look-at point, `distance` ahead of the eye */
    float yaw;          /* orbit angle around the player, radians */
    float pitch;        /* angle above horizontal, radians */
    float distance;     /* resting distance from eye to player, meters */
    Vec3  position;     /* derived eye position (recomputed in camera_update) */
    Vec2  framing;      /* player's screen position in NDC: (0,0) = center, edges = +-1 */
    float depth;        /* current eye-to-player distance along the view; eases to `distance` */
    Vec3  subject;      /* last tick's framed point (feet + target height) */
    bool  recentering;  /* gliding to "centered, behind the player" */
    float recenter_yaw; /* the yaw that glide is headed for */
    float hands_off_time; /* s since the camera was last moved by hand (capped) */
    float auto_pitch_speed; /* current auto-pitch speed, rad/s (>= 0), for easing */
} Camera;

void  camera_init(Camera *c, Vec3 follow_point);
void  camera_update(Camera *c, const Input *in, Vec3 follow_point, float follow_facing,
                    bool pan_locked, float aspect, float dt);
float camera_yaw(const Camera *c);
Mat4  camera_view(const Camera *c);
Mat4  camera_projection(const Camera *c, float aspect);

#endif /* CAMERA_H */