Add #

Add an existing box.

method : public : Add(box:Box) ~ Box

Parameters

Return

AddBatch #

Add an instanced batch, drawn in one call after the solid geometry. A batch brings its own shader, so it is not affected by SetShader and does not take part in the material runs the boxes and props share. It inherits the scene's light when it has none of its own. Note it counts as ONE toward GetDrawn, not one per instance -- what that number measures is submissions, and the whole point of a batch is that four hundred trees are a single submission. ## Batches do not cast shadows DrawInto walks the boxes and the props, not the batches. The depth pass runs one shader over everything, and DepthOnly is a per-object program -- an instanced depth shader would be a second one, and Scene would have to switch between them mid-pass. So a batch is lit but casts nothing, which is fine for grass and wrong for pillars. Use props for anything whose shadow matters.

method : public : AddBatch(batch:PropBatch) ~ PropBatch

Parameters

Return

AddBox #

Build and add a box.

method : public : AddBox(center:Vector3, half:Vector3, texture:Texture2D) ~ Box

Parameters

Return

AddProp #

Add a prop -- a mesh, material and transform of its own. Returned so it can be kept and moved: lamp := scene->AddProp(Prop->New(lamp_mesh, brass)); lamp->GetTransform()->SetPosition(2.0, 0.0, -3.0); Props are drawn after the boxes in the solid pass, and join the boxes in the sorted pass if they are transparent. They do NOT block movement -- Scene->Blocked walks only the boxes, because a plan-view overlap test says nothing about a rotated model.

method : public : AddProp(prop:Prop) ~ Prop

Parameters

Return

Blocked #

Whether a circle in plan view hits any SOLID box.

method : public : Blocked(x:Float, z:Float, radius:Float) ~ Bool

Parameters

Return

Clear #

Drop every box and every prop. Does NOT free the shared mesh, shader or textures -- those were passed in and belong to the caller.

method : public : Clear() ~ Nil

Draw #

Draw every box. Binds the shader, then for each box sets the "mvp" uniform and draws the shared mesh. Rebinds a texture only when it changes from the previous box.

method : public : Draw(view_projection:Float[]) ~ Nil

Parameters

DrawBatches #

Draw the instanced batches, then put back what they disturbed. A batch binds its own shader -- it has to, since an instanced program takes the camera as "view_projection" and reads the model matrix from a vertex attribute, which is a different shape from the per-object "mvp" every other shader here uses. Rebinding the scene's shader here is DEFENSIVE, not load-bearing, and it is worth being exact about that. Every uniform setter binds its own program before writing -- that was the phase-3 fix for uniforms landing on the wrong shader -- so the transparent pass would bind the right program anyway on its first SetMatrix4. This is here so the bound program matches what the scene believes for any future draw path that does not happen to set a uniform first. Removing it breaks no current test, which is exactly why the comment should not claim otherwise. What DID leak was the texture unit, which is global rather than per-program: a batch binds its material's texture, and anything drawn afterwards whose material carries no texture of its own sampled it. That is fixed in DrawOne rather than here, because the real fault was a coloured box never binding its own texture at all.

method : private : DrawBatches() ~ Nil

Parameters

DrawInto #

Draw every box through a DIFFERENT shader, with a different matrix. For a pass that is not the normal one: a shadow map's depth pass wants this scene's geometry rendered from the light with a depth-only program, and nothing else about the scene changes. Deliberately minimal -- no light, no sampler, no per-object model matrix unless the shader asks for one -- because an auxiliary pass generally wants positions and nothing else, and setting uniforms a depth shader does not declare would file a diagnostic per box per frame.

method : public : DrawInto(shader:Shader, view_projection:Float[]) ~ Nil

Parameters

DrawOne #

Bind what one box needs and draw it. Split out because the two passes are the same work in a different order, and a second copy of it would be a second place for the material-run tracking to go wrong.

method : private : DrawOne() ~ Nil

Parameters

EyeDistance #

Squared distance from the eye to a box's centre -- squared because only the ORDER matters, and a square root per box per frame buys nothing.

method : private : EyeDistance() ~ Float

Parameters

Get #

method : public : Get(index:Int) ~ Box

Parameters

Return

GetBatch #

method : public : GetBatch(index:Int) ~ PropBatch

Parameters

Return

GetBatchCount #

method : public : GetBatchCount() ~ Int

Return

GetCount #

method : public : GetCount() ~ Int

Return

GetCulledCount #

How many boxes the last Draw skipped as off-screen.

method : public : GetCulledCount() ~ Int

Return

GetDrawnCount #

How many boxes the last Draw actually submitted. The last Draw only. DrawInto -- which is what a shadow pass runs, six times over for a point light -- deliberately leaves these alone, so a HUD reading them reports what the camera drew rather than whatever the final shadow face happened to submit.

method : public : GetDrawnCount() ~ Int

Return

GetLight #

method : public : GetLight() ~ Light

Return

GetLightRig #

method : public : GetLightRig() ~ LightRig

Return

GetProp #

method : public : GetProp(index:Int) ~ Prop

Parameters

Return

GetPropCount #

method : public : GetPropCount() ~ Int

Return

IsCulling #

method : public : IsCulling() ~ Bool

Return

New # constructor

New(mesh:Mesh, shader:Shader)

Parameters

PropEyeDistance #

Squared distance from the eye to a prop, for the transparent sort.

method : private : PropEyeDistance() ~ Float

Parameters

Raycast #

Fire a ray into the scene and report the nearest thing it hits. This is what a hitscan weapon, a "what am I looking at" prompt, a line-of-sight check or a mouse pick is built on -- none of which had any route before, since the only spatial query here was Blocked, which answers a plan-view movement question and nothing else. hit := scene->RaycastFrom(camera, 100.0); if(hit->IsHit()) { target := hit->GetProp(); ... }; ## What it tests against Boxes are tested against their actual axis-aligned extent, so the hit point and the normal are exact. Props are tested against their BOUNDING SPHERE, not their mesh. A prop is an arbitrary rotated model and this bundle never keeps its triangles after upload -- they live on the GPU -- so there is nothing here to intersect. The sphere is conservative, which means a shot can register slightly wide of a thin model. Put a Box where precision matters, the same way collision already works. Batches are NOT tested. A batch exists so that four hundred instances cost one draw call, and walking its transforms per shot would work but RayHit has nowhere to report WHICH instance was struck. Stating that rather than quietly returning a miss. Solidity is ignored on purpose: Box->IsSolid means "blocks movement", which is a different question from "stops a bullet". Filter on hit->GetBox()->IsSolid() if you want them to agree. Invisible props ARE skipped, since something you cannot see should not be shootable.

method : public : Raycast(origin:Vector3, direction:Vector3, max_distance:Float) ~ RayHit

Parameters

Return

RaycastFrom #

Fire a ray from where the camera is, along where it is looking. The overwhelmingly common case -- a crosshair in the middle of the screen is exactly this ray.

method : public : RaycastFrom(camera:Camera, max_distance:Float) ~ RayHit

Parameters

Return

RaycastScreen #

Fire a ray through a point on the screen -- a mouse pick. The camera supplies the direction through that pixel and the scene answers what is along it. Pass the window so the ray is built from the same size the mouse coordinates were measured in. hit := scene->RaycastScreen(camera, window, window->GetMouseX(), window->GetMouseY(), 100.0);

method : public : RaycastScreen(camera:Camera, window:GLWindow, x:Int, y:Int, max_distance:Float) ~ RayHit

Parameters

Return

RemoveBatch #

Take one batch out of the scene. Here so that the three lists behave the same way. Clear drops all three; leaving two of them removable individually and the third not would be the sort of asymmetry nobody remembers.

method : public : RemoveBatch(batch:PropBatch) ~ Bool

Parameters

Return

RemoveBox #

Take one box out of the scene. Note this changes the index of every box after it, so a loop holding indices across a removal is holding the wrong ones.

method : public : RemoveBox(box:Box) ~ Bool

Parameters

Return

RemoveProp #

Take one prop out of the scene. Clear emptied everything and there was no way to remove a single thing, so anything that spawns and despawns -- an enemy, a pickup, a projectile -- had to rebuild the whole scene or hide the prop with SetVisible and leak it forever. Both are what this replaces.

method : public : RemoveProp(prop:Prop) ~ Bool

Parameters

Return

ReserveFar #

Make room for count transparent boxes, growing only when it is not enough.

method : private : ReserveFar() ~ Nil

Parameters

ResetMaterialState #

Undo whatever the last Material wrote, for geometry that has none. Only opacity was being reset, and Material->ApplyTo writes FOUR uniforms: tint, shininess, specular_strength and opacity. So one material'd object tinted every untextured object drawn after it -- in gl_lantern that meant the entire dungeon turned the relics' gold from the second frame onward, because the last material applied each frame was the glow shell. Specular goes back to the RIG's values rather than a hardcoded default, because that is what the scene asked for before any material overrode it.

method : private : ResetMaterialState() ~ Nil

SetCulling #

Whether to skip boxes that fall outside the view. On by default. The test is a few dozen arithmetic operations per box against a draw call plus a matrix multiply plus two uniform uploads, so it pays for itself almost immediately and costs almost nothing when it does not. Turn it off to measure what it is saving, or if a custom vertex shader moves geometry away from where its box says it is -- the test uses the box, and a shader that displaces vertices makes that a lie.

method : public : SetCulling(enabled:Bool) ~ Nil

Parameters

SetEye #

Tell the scene where the camera is, so transparency can be ordered. Transparent surfaces must be drawn back to front: a nearer one drawn first writes depth and hides what is behind it. That needs a distance, and a distance needs an eye. Call it every frame: scene->SetEye(camera->GetPosition()); Without it transparent boxes still draw, in insertion order -- which is correct only by luck.

method : public : SetEye(eye:Vector3) ~ Nil

Parameters

SetLight #

Light the scene. Pass Nil to go back to an unlit shader's own behaviour. The light's uniforms are written once per Draw, not per object, since a directional light is the same for everything in the frame.

method : public : SetLight(light:Light) ~ Nil

Parameters

SetLightRig #

Light the scene with several lights rather than one. Takes precedence over SetLight. A rig with a point light or two is what a scene with a lamp in it wants; SetLight remains the shorter way to say "one directional light".

method : public : SetLightRig(rig:LightRig) ~ Nil

Parameters

SetShader #

Draw with a different program from here on. Resets what was learned about the old shader's uniforms -- a Scene that cached "this shader has no model matrix" and then had a lit shader substituted would silently stop transforming normals.

method : public : SetShader(shader:Shader) ~ Nil

Parameters

SlideMove #

Move a camera through the scene, sliding along whatever it hits. The only program with collision could not use Camera->MoveForward or MoveRight, because collision has to test a candidate position BEFORE committing to it -- so it re-derived the ground basis, did the dot products by hand and called SetPosition, twenty lines that belong here. Each axis is applied separately, and that is the whole trick: testing the combined vector stops you dead against a wall you hit at an angle, while testing X and Z in turn lets the blocked component drop and the other one through, which is what sliding along a wall is. ## A step bigger than a wall goes through it This tests the DESTINATION, not the path swept to reach it. Ask it to move 2 units and the far side of a 1-unit wall is clear, so that is where you land -- no overlap is ever detected because the position that would have overlapped is never tested. Two things keep it from biting. GetDelta is clamped to 0.1, so the largest step a frame-rate hitch can produce is `speed * 0.1` rather than however long the machine stalled for. And the rule that follows: keep `speed * 0.1` comfortably under the thickness of your thinnest solid box. At a speed of 6 that is 0.6, so walls a unit thick are safe and paper-thin dividers are not. Also note what "solid" means. Blocked and this method both skip boxes marked SetSolid(false), and both ignore height entirely -- the test is a circle against a rectangle in plan view. A floor spans every (x,z) in the room, so a SOLID floor blocks every position in it and nothing can move at all. Mark floors and ceilings non-solid.

method : public : SlideMove(camera:Camera, forward:Float, strafe:Float, radius:Float) ~ Bool

Parameters

Return

SortFar #

Order the collected transparent boxes furthest-first. An insertion sort, which is the right choice rather than a lazy one: the count is small, and between frames the order barely changes, so a nearly sorted list costs close to one pass. Quicksort's advantage needs a size this will not reach, and a nearly sorted list is its worst case.

method : private : SortFar() ~ Nil

Parameters