Math

The math types wrap GLM behind a small, explicit API. OkPoint is a 3D point or vector, OkRotation holds Euler angles (and the matrix they produce), and OkMath is a static helper for direction/angle conversions and look-at.

Coordinate system

Okinawa uses a right-handed coordinate system: X points right, Y points up, Z points towards the viewer (out of the screen). The default camera sits at the origin looking down negative Z, with up along positive Y. Rotations are Euler angles in radians: pitch (X), yaw (Y), roll (Z), with pitch clamped to avoid gimbal lock. See src/okinawa/math/readme.md in the engine for the full conventions.

OkPoint methods

OkPoint also supports +, -, * (scalar), and the compound assignment operators.

OkRotation methods

OkMath methods

OkRay

A half-line through the world — an origin and a direction — with the intersection tests worth having against it. It is what a cursor becomes once OkCamera::rayThroughPixel has turned a pixel into a direction, and what OkItem::intersectRay is asked with.

Distances are measured in units of the direction

Every distance a ray reports is in units of its own direction, not in world units. With a unit direction the two are the same and nobody has to think about it, which is the ordinary case — rayThroughPixel returns one.

The distinction is there for transformed. Multiplying a ray by the inverse of an object's model matrix puts it in that object's local space, where the object's vertices already are, so a mesh test transforms one ray instead of every vertex. Under a scaling the transformed direction is no longer a unit vector, and that is deliberate: the scaling lives in the direction's length, which is what makes a hit found in local space come back with a distance measured in world units. Normalizing after the transform throws that conversion away and reports the wrong distance for any scaling but 1.

What it does not decide

OkRay holds no policy about what may be hit. Which objects are worth testing, whether a hidden one counts, and which of several hits wins are questions for whoever is asking — and applications answer them differently: an editor's cursor wants the nearest selectable thing, a projectile wants the first solid one, a line-of-sight check only wants to know whether anything is in the way. An engine that answered any of them here would be answering it for all of them.

OkFrustum

The view frustum as six planes, extracted from a combined projection * view matrix (Gribb-Hartmann), used for bounding-sphere culling. OkCore builds one per frame from the current camera and activates it for the world pass: OkItem::drawSelf skips any item whose bounding sphere (bbox centre + half-diagonal radius, transformed by the item's matrix) falls fully outside — in a dense scene over half the scene's items are skipped every frame. The GUI and camera-attached passes run with no active frustum (their calibrated cameras are not the world camera), and the skybox dome is camera-centred so it always intersects. get_state (MCP) reports the per-frame skipped count as scene.frustum_culled.

Draw distance

render.drawdistance (world units, 0 disables) skips anything whose bounding sphere lies entirely beyond it. It is a single comparison and in an open world it rejects far more than the frustum test does, so the draw path tries it first. Set it where the project's distance fog has already swallowed the world: past that point the draws change nothing on screen.

Opaque geometry is also drawn nearest first (see OkScene), so the depth buffer rejects hidden fragments early — the cheapest defence against overdraw in a scene full of occluders. The order is refreshed periodically rather than every frame, since it only has to be roughly right.

Example

OkPoint eye(0.0f, 100.0f, 200.0f);
OkPoint target(0.0f, 0.0f, 0.0f);
OkPoint direction = (target - eye).normalize();

float pitch, yaw;
OkMath::directionVectorToAngles(direction, pitch, yaw);
camera->setRotation(pitch, yaw, 0.0f);