Documentation
¶
Overview ¶
Package render manages the draw call list and bucket-based sorting for the g3d forward renderer. It operates on primitives only and has no dependency on the root g3d package.
Index ¶
- type DrawCall
- type RenderBucket
- type RenderList
- func (rl *RenderList) Add(dc DrawCall)
- func (rl *RenderList) Background() []DrawCall
- func (rl *RenderList) Clear()
- func (rl *RenderList) Opaque() []DrawCall
- func (rl *RenderList) Sort()
- func (rl *RenderList) TotalCount() int
- func (rl *RenderList) Transmissive() []DrawCall
- func (rl *RenderList) Transparent() []DrawCall
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DrawCall ¶
type DrawCall struct {
// PipelineKey identifies the render pipeline (derived from Material.ShaderID).
// Pipeline state changes are the most expensive GPU operation, so this is
// the primary sort key for opaque draw calls.
PipelineKey string
// MaterialID uniquely identifies a material instance. Bind group changes are
// the second-most expensive GPU operation (after pipeline switches), so this
// is the secondary sort key for opaque draw calls.
MaterialID uint64
// Distance is the squared distance from the camera to the object's center.
// Used as the tertiary sort key: front-to-back for opaque (early Z rejection),
// back-to-front for transparent (correct alpha compositing).
Distance float32
// Bucket determines which render pass draws this call.
Bucket RenderBucket
// MeshIndex is an opaque handle that the Renderer uses to look up the
// associated mesh, geometry, material, and world transform. The render
// package does not interpret this value.
MeshIndex int
}
DrawCall represents a single object to be drawn. Sort keys are extracted by the Renderer from g3d public types; the render package never imports g3d.
type RenderBucket ¶
type RenderBucket uint8
RenderBucket determines render order. Four buckets follow the Three.js validated pattern (see PHASE1-ARCHITECTURE-VALIDATION.md, correction C3).
Phase 1 uses Opaque and Transparent only. Background and Transmissive buckets exist for forward-compatibility but are not rendered until Phase 4.
const ( // BucketBackground is drawn first. Used for skyboxes and image-based lighting. BucketBackground RenderBucket = iota // BucketOpaque is drawn second with depth testing and no blending. // Sorted front-to-back within pipeline/material groups to minimize overdraw. BucketOpaque // BucketTransmissive is drawn third. Used for transparent objects that still // write to the depth buffer (e.g., refraction effects). Added in Phase 4. BucketTransmissive // BucketTransparent is drawn last with alpha blending enabled. // Sorted back-to-front for correct alpha compositing. BucketTransparent )
func (RenderBucket) String ¶
func (b RenderBucket) String() string
String returns a human-readable name for the bucket.
type RenderList ¶
type RenderList struct {
// contains filtered or unexported fields
}
RenderList collects and sorts visible meshes for rendering. It maintains separate slices per bucket so that sorting strategies can differ.
Phase 1 uses Opaque and Transparent. Background and Transmissive slices are allocated lazily when the first draw call targets them.
All slices are reused across frames via Clear() to avoid GC pressure.
func NewRenderList ¶
func NewRenderList() *RenderList
NewRenderList creates an empty RenderList ready for draw call collection.
func (*RenderList) Add ¶
func (rl *RenderList) Add(dc DrawCall)
Add inserts a draw call into the appropriate bucket based on dc.Bucket.
func (*RenderList) Background ¶
func (rl *RenderList) Background() []DrawCall
Background returns the background draw calls. Valid until the next Clear().
func (*RenderList) Clear ¶
func (rl *RenderList) Clear()
Clear resets all buckets for the next frame. Slice capacity is preserved to avoid allocation on subsequent frames (zero-alloc render path).
func (*RenderList) Opaque ¶
func (rl *RenderList) Opaque() []DrawCall
Opaque returns the sorted opaque draw calls. The returned slice must not be modified by the caller; it is valid until the next Clear() or Add().
func (*RenderList) Sort ¶
func (rl *RenderList) Sort()
Sort sorts each bucket by its strategy.
Opaque uses a 3-key sort validated against Three.js PR #15484:
- PipelineKey ascending — minimize pipeline state changes (most expensive)
- MaterialID ascending — minimize bind group changes (second most expensive)
- Distance ascending — front-to-back for early Z rejection (minimize overdraw)
Transparent uses distance descending (back-to-front) for correct alpha blending.
Background and Transmissive use insertion order (no sort) in Phase 1.
func (*RenderList) TotalCount ¶
func (rl *RenderList) TotalCount() int
TotalCount returns the total number of draw calls across all buckets.
func (*RenderList) Transmissive ¶
func (rl *RenderList) Transmissive() []DrawCall
Transmissive returns the transmissive draw calls. Valid until the next Clear().
func (*RenderList) Transparent ¶
func (rl *RenderList) Transparent() []DrawCall
Transparent returns the sorted transparent draw calls. The returned slice must not be modified by the caller; it is valid until the next Clear() or Add().
Source Files