Home /Modules/bash/render_math.hpp

render_math.hpp

bash/model-3D/render_math.hpp · 151 line(s) · c

#pragma once

// SleelaTerminal(TM) -- SLeeLa's terminal product, built on GNU Bash
// (GPL, (C) Free Software Foundation). SLeeLa-authored addition; the
// vendored GNU Bash sources keep their own GPL headers and copyright.
// Phraign(TM) City 3D -- rendering math.
//
// Basic, dependency-free rendering primitives shared by the renderer and the
// rendering group: 2D/3D vectors, RGBA color math, the oblique world->screen
// projection, an axis-aligned bounding box, a screen-space quad, and a
// scanline polygon fill that writes into any RenderSink.
//
// The math here is intentionally small and exact for the convex quads the city
// renderer produces (roofs and walls), and keeps rendering "per pixel" onto a
// Phraign frame.

#include <array>
#include <cstddef>
#include <cstdint>

namespace sleela::render {

// ---------------------------------------------------------------------------
// Vectors
// ---------------------------------------------------------------------------

struct Vec2 {
    double x = 0.0;
    double y = 0.0;

    Vec2 operator+(const Vec2& o) const noexcept { return {x + o.x, y + o.y}; }
    Vec2 operator-(const Vec2& o) const noexcept { return {x - o.x, y - o.y}; }
    Vec2 operator*(double s) const noexcept { return {x * s, y * s}; }
};

struct Vec3 {
    double x = 0.0;
    double y = 0.0;
    double z = 0.0;

    Vec3 operator+(const Vec3& o) const noexcept {
        return {x + o.x, y + o.y, z + o.z};
    }
    Vec3 operator-(const Vec3& o) const noexcept {
        return {x - o.x, y - o.y, z - o.z};
    }
    Vec3 operator*(double s) const noexcept { return {x * s, y * s, z * s}; }
};

double dot(const Vec3& a, const Vec3& b) noexcept;
Vec3 cross(const Vec3& a, const Vec3& b) noexcept;
double length(const Vec3& v) noexcept;
Vec3 normalize(const Vec3& v) noexcept;  // returns {0,0,0} for a zero vector

// Signed area * 2 of the 2D triangle (a,b,c). Positive => counter-clockwise.
double signedArea2(const Vec2& a, const Vec2& b, const Vec2& c) noexcept;

double clampd(double v, double lo, double hi) noexcept;
double lerpd(double a, double b, double t) noexcept;

// ---------------------------------------------------------------------------
// Color (RGBA, packed 0xRRGGBBAA to match the Phraign pixel encoding)
// ---------------------------------------------------------------------------

struct Rgba {
    std::uint8_t r = 0;
    std::uint8_t g = 0;
    std::uint8_t b = 0;
    std::uint8_t a = 0xFF;

    constexpr std::uint32_t pack() const noexcept {
        return (static_cast<std::uint32_t>(r) << 24) |
               (static_cast<std::uint32_t>(g) << 16) |
               (static_cast<std::uint32_t>(b) << 8) |
               static_cast<std::uint32_t>(a);
    }
    static constexpr Rgba unpack(std::uint32_t v) noexcept {
        return Rgba{static_cast<std::uint8_t>((v >> 24) & 0xFF),
                    static_cast<std::uint8_t>((v >> 16) & 0xFF),
                    static_cast<std::uint8_t>((v >> 8) & 0xFF),
                    static_cast<std::uint8_t>(v & 0xFF)};
    }
};

// Scale RGB by a factor (alpha preserved), clamped to [0,255]. Useful for
// shading a base tone lighter (>1) or darker (<1).
Rgba shade(const Rgba& c, double factor) noexcept;

// Linear interpolation between two colors, t in [0,1] (per channel).
Rgba lerp(const Rgba& a, const Rgba& b, double t) noexcept;

// ---------------------------------------------------------------------------
// Camera / projection
// ---------------------------------------------------------------------------

// Oblique/dimetric projection parameters: the scene is seen from above and
// slightly to the side. These map a world point (x east, y depth, z up) to a
// screen point. This mirrors the City 3D Viewpoint but lives in the math layer
// so it is reusable and testable on its own.
struct ObliqueCamera {
    double tilt_x = 0.55;       // screen-x skew per unit depth
    double tilt_y = 0.42;       // screen-y advance per unit depth
    double scale_x = 9.0;       // screen px per unit east
    double scale_height = 3.0;  // screen px per unit up (z)
    double origin_x = 150.0;    // screen px for world (0,0,0)
    double origin_y = 210.0;

    Vec2 project(const Vec3& world) const noexcept;
};

// ---------------------------------------------------------------------------
// Screen geometry
// ---------------------------------------------------------------------------

struct BBox {
    double min_x = 0.0, min_y = 0.0, max_x = 0.0, max_y = 0.0;
    bool empty = true;

    void add(const Vec2& p) noexcept;
};

// A convex screen-space quad (4 corners, in order around the perimeter).
struct Quad {
    std::array<Vec2, 4> p{};

    BBox bounds() const noexcept;
    Vec2 centroid() const noexcept;
};

// ---------------------------------------------------------------------------
// Raster sink + scanline fill
// ---------------------------------------------------------------------------

// Minimal target the fill writes into. Implemented over a Phraign frame in the
// rendering-group layer, but kept abstract here so the math has no Phraign
// dependency and can be unit-tested against a plain buffer.
class RenderSink {
public:
    virtual ~RenderSink() = default;
    virtual std::size_t width() const noexcept = 0;
    virtual std::size_t height() const noexcept = 0;
    // Write one pixel; return true if it landed inside the target.
    virtual bool plot(std::size_t x, std::size_t y, std::uint32_t rgba) = 0;
};

// Fill a convex quad into the sink by scanline. Pixel centers at (x+0.5,y+0.5)
// are tested. Returns the number of pixels written. Clipped to the sink bounds.
std::size_t fillQuad(RenderSink& sink, const Quad& quad, std::uint32_t rgba);

} // namespace sleela::render