Caffeine

Camera 3D

Stable Namespace: `Caffeine::Render` Last verified: Source: render/Camera3D.hpp

Perspective camera used by the 3D viewport and runtime: view and projection matrices, screen/world conversion, a frustum for culling, and FPS/orbital/follow controls.


Overview#

Camera3D provides a perspective projection for 3D rendering and coexists with Camera2D: the same frame can render 2D (HUD, sprites) and 3D (environment, characters) with different cameras.


API#

cpp
namespace Caffeine::Render {

class Camera3D {
public:
    Camera3D() = default;

    // ── Matrices ───────────────────────────────────────────────
    Mat4 viewMatrix()           const;
    Mat4 projectionMatrix()     const;
    Mat4 viewProjectionMatrix() const;   // cached, recalculated when dirty

    // Frustum for culling
    Spatial::Frustum frustum() const;

    // ── Space conversion ──────────────────────────────────────
    Vec3 worldToScreen(Vec3 worldPos) const;              // pixels + depth 0..1
    Vec3 screenToWorld(Vec2 screenPos, f32 depth = 0.5f) const;
    bool isVisible(const Spatial::AABB3D& bounds) const;

    // ── Perspective configuration ─────────────────────────────
    void setFOV(f32 fovYDegrees);      // clamped to 1..179
    void setAspect(f32 aspect);
    void setNearFar(f32 nearPlane, f32 farPlane);
    void setViewport(Rect2D viewport);

    // ── Transform ─────────────────────────────────────────────
    void setPosition(Vec3 pos);
    void setRotation(Quat rot);
    void lookAt(Vec3 eye, Vec3 target, Vec3 up = {0, 1, 0});

    // ── FPS mode ──────────────────────────────────────────────
    void rotateFPS(f32 deltaPitch, f32 deltaYaw);  // degrees; pitch clamped to ±89
    void moveFPS(Vec3 localDelta);                 // local space

    // ── Orbital mode ──────────────────────────────────────────
    void orbit(f32 deltaAzimuth, f32 deltaElevation);
    void setOrbitTarget(Vec3 target);
    void setOrbitDistance(f32 distance);
    void zoom(f32 delta);

    // ── Follow mode ───────────────────────────────────────────
    void follow(ECS::Entity target, Vec3 offset = {0, 2, -5}, f32 smoothing = 0.05f);
    void stopFollowing();
    void update(f64 dt, const ECS::World& world);

    // ── Getters ───────────────────────────────────────────────
    Vec3 position()    const;
    Quat rotation()    const;
    f32  fov()         const;
    f32  aspect()      const;
    f32  nearPlane()   const;
    f32  farPlane()    const;
    Rect2D viewport()  const;
    Vec3 forward()     const;
    Vec3 right()       const;
    Vec3 up()          const;
};

}  // namespace Caffeine::Render

Defaults: FOV 60°, 16:9, near 0.1, far 1000, position (0, 0, -5).


Perspective projection mathematics#

text
Projection Matrix (perspective):
    f = 1 / tan(fovY/2)

    [f/aspect,  0,      0,                0]
    [0,         f,      0,                0]
    [0,         0,  far/(far-near),       1]
    [0,         0, -far*near/(far-near),  0]

View Matrix (from the rotation quaternion):
    view = inverse(rotation) * translate(-position)

viewProjectionMatrix() returns projection * view and only recomputes when a setter marked the camera dirty.


Frustum culling integration#

cpp
// Camera3D builds the frustum from its own parameters:
Spatial::Frustum frustum = camera3D.frustum();

// The GPU scene renderer tests every mesh AABB against it:
if (!frustum.intersects(aabb)) return;  // no draw

Usage examples#

cpp
// ── Perspective setup ─────────────────────────────────────────
Caffeine::Render::Camera3D camera;
camera.setFOV(60.0f);
camera.setAspect(1280.0f / 720.0f);
camera.setNearFar(0.1f, 1000.0f);
camera.setViewport({ {0, 0}, {1280, 720} });
camera.lookAt({0, 5, -10}, {0, 0, 0});

// ── FPS camera ────────────────────────────────────────────────
camera.rotateFPS(input.axisValue(Axis::LookY) * sensitivity,
                 input.axisValue(Axis::LookX) * sensitivity);

Vec3 moveDir = {
    input.axisValue(Axis::MoveX),
    0,
    input.axisValue(Axis::MoveY)
};
camera.moveFPS(moveDir * moveSpeed * dt);

// ── Follow (third person) ─────────────────────────────────────
camera.follow(playerEntity, {0, 3, -6}, 0.05f);
camera.update(dt, world);

// ── Orbital (editor/strategy) ─────────────────────────────────
camera.setOrbitTarget({0, 0, 0});
camera.setOrbitDistance(15.0f);
camera.orbit(deltaX * 0.5f, deltaY * 0.5f);
camera.zoom(scrollDelta);

Coexistence with Camera2D#

cpp
// 2D + 3D in the same frame:

// 3D (world) — linear HDR scene + post-processing into colorTarget
renderer.renderWithCamera(cmd, world, camera, colorTarget, depthTarget,
                          width, height, projectRoot, options);

// 2D (HUD on top)
cmd->beginRenderPass(hudPassDesc);
batchRenderer.setCamera(camera2D);  // orthographic
batchRenderer.endFrame(cmd);
cmd->endRenderPass();

Behaviour notes#

  • rotateFPS clamps pitch to [-89, +89] and keeps roll at zero.
  • orbit clamps elevation the same way and recomputes the position around the orbit target.
  • follow lerps the position towards the target's Position3D plus a local offset; dt is currently unused, so smoothing is per call.
  • screenToWorld unprojects with the inverse view-projection at the requested depth.

Dependencies#


References#