8.1 KiB
Glossary
ResourceRegistry
A ResourceRegistry owns GPU-backed resources on the caller's behalf and hands out lightweight Handles instead of pointers or ownership. It is engine-internal: frontend code never sees it, and reaches it through a ResourceRegistryRef.
Internally it's a collection of per-type pools, each a Pool<T, Handle>
(a generation-checked slot pool). A type that needs extra behaviour wraps its
pool in a thin class instead:
ResourceRegistry
├── meshes Pool<Mesh, MeshHandle>
├── renderTargets RenderTargetPool → RenderTargetHandle
│ (wraps Pool; waits for the GPU on release, applies resizes)
├── scenes Pool<Scene, SceneHandle>
├── textures (planned)
└── materials (planned)
Engine code (Application, ImGuiRenderer, SceneRenderer) uses the pools
directly, e.g. resources.renderTargets.get(handle).
A Handle is a small (index, generation) pair. The index locates the slot in the pool; the generation is bumped when that slot is released, so a Handle kept around after release() is detected as stale instead of resolving to someone else's resource (or freed memory).
Think: "Where does the engine keep every GPU resource, and how does it look one up by handle?"
ResourceRegistryRef
A ResourceRegistryRef is the frontend's non-owning, cheap-to-copy view of the
ResourceRegistry, returned by Application::resources(). It exposes only what
frontend code needs and hands out no pools, so no Vulkan-facing types leak
through the public API:
create<T>(...) load<T>(path) release<T>(handle)
requestResize(target, w, h) getExtent(target) isAlive(handle)
Typical lifecycle:
load<Mesh>(path) / create<Mesh>(...) → MeshHandle
│
release<Mesh>(handle)
Think: "How do I create or release a GPU resource by handle, without owning its lifetime directly?"
Buffer
A Buffer is a linear region of GPU memory used to store arbitrary data.
Unlike an Image, which is designed for multidimensional image data, a buffer is essentially:
[ byte byte byte byte byte byte ... ]
Buffers commonly contain:
Vertex data Index data Uniform data Storage data Indirect draw commands
For example:
Vertex Buffer
┌─────────────────────────────────┐
│ Vertex │ Vertex │ Vertex │ ... │
└─────────────────────────────────┘
In Vulkan, VkBuffer / vk::Buffer is a fundamental resource.
Think: "A linear chunk of GPU-accessible data."
Camera
A Camera defines how the scene is viewed and projected onto the screen.
It generally contains:
Position Orientation Projection parameters View matrix Projection matrix
For example:
Camera
├── Position
├── Rotation
├── Projection
│ ├── Perspective
│ └── Orthographic
├── View Matrix
└── Projection Matrix
Think: "From where and how am I looking at the scene?"
Canvas
A Canvas is a coordinate/rendering space onto which things are drawn.
For UI, for example:
Canvas
┌──────────────────────────────┐
│ │
│ ┌──────────────┐ │
│ │ Panel │ │
│ └──────────────┘ │
│ │
│ Button │
│ │
└──────────────────────────────┘
A canvas establishes things such as:
Dimensions Coordinate system Origin Scaling Potentially clipping
In a UI system, a Canvas is essentially:
The space in which UI elements are laid out and rendered.
Frame
Frame is context-dependent, but in a renderer it usually means one iteration of rendering the scene to produce one displayed image.
Layer
A Layer is a logical ordering/grouping of content.
For example:
Layer 0: Background Layer 1: World Layer 2: Characters Layer 3: Effects Layer 4: UI
Higher layers can be rendered over lower layers.
In a 2D engine, layers might determine draw order:
Background
↓
Tiles
↓
Player
↓
Particles
↓
UI
However, Layer is very engine-specific. In a 3D renderer it could instead represent a rendering category, visibility mask, or render-pass grouping.
Material
A Material describes how a surface should be rendered.
It usually combines:
Shader/pipeline configuration Textures Colors Numerical parameters
For example:
Material
├── Shader
├── Albedo Texture
├── Normal Texture
├── Roughness
├── Metallic
└── Base Color
Then:
Mesh + Material + Transform
↓
Renderer
↓
GPU
A useful conceptual distinction is:
Mesh = what the object is shaped like. Material = how that shape should look.
Mesh
A Mesh is the geometric data used to describe the shape of an object.
Typically contains:
Vertex positions Normals Texture coordinates (UVs) Tangents Indices
For example, a cube mesh contains the vertices and triangles necessary to describe a cube.
Mesh
├── Vertices
├── Indices
└── Vertex attributes
├── Position
├── Normal
├── UV
└── Tangent
Think: "What shape is this object?"
Panel
A Panel is a rectangular UI region/container.
For example:
┌──────────────────────────────┐
│ Toolbar │
├───────────┬──────────────────┤
│ │ │
│ Scene │ Viewport │
│ │ │
├───────────┼──────────────────┤
│ Inspector │ Console │
└───────────┴──────────────────┘
Each of those regions could be a panel.
A panel generally has:
Position Size Child elements UI contents Potentially its own rendering/context
This is primarily a UI concept, rather than a GPU concept.
PanelRegistry
A PanelRegistry owns Panels on the caller's behalf and hands out lightweight PanelHandles instead of pointers or ownership.
Internally it's a generation-checked slot pool, the same shape ResourceRegistry's
Pool<T, Handle> uses:
PanelRegistry
└── Slot { Panel, generation } → PanelHandle
Typical lifecycle:
add(panel) / emplace<T>(...) → PanelHandle
│
get(handle) / get<T>(handle) → Panel& / T&
│
remove(handle)
Each frame, update(frameInfo) calls onUpdate on every visible Panel it holds.
Think: "Where do I register or look up a UI panel by handle, without owning its lifetime directly?"
Sprite
A Sprite is a 2D renderable representation of an image, usually a rectangular region of a texture.
For example:
Texture Atlas
┌─────────────────────┐
│ Player │ Enemy │
│ │ │
├────────┼────────────┤
│ Tree │ Rock │
└─────────────────────┘
A sprite might reference only the Player region of that texture.
A useful engine abstraction might be:
Sprite {
Texture* texture;
Rect uv;
}
Think: "Which 2D picture/region am I drawing?"
Texture
A Texture is image data intended to be used by a shader.
It can represent:
Color/albedo Normal maps Roughness Metallic values Masks Height maps etc.
A texture doesn't necessarily have to be displayed directly.
Texture → Shader → Material/Object
Think: "What image/data does the shader sample?"