sophia/_Design/glossary.md

Glossary

ResourceRegistry

A ResourceRegistry owns GPU-backed resources on the caller's behalf and hands out lightweight Handles instead of pointers or ownership.

Internally it's a collection of per-type pools, each responsible for one resource type:

ResourceRegistry
 ├── MeshPool     → MeshHandle
 ├── TexturePool  → TextureHandle   (planned)
 └── MaterialPool → MaterialHandle  (planned)

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).

Typical lifecycle:

load<Mesh>(path) / create<Mesh>(...)  →  MeshHandle
                                        │
                        get<Mesh>(handle)  →  const Mesh&
                                        │
                        release<Mesh>(handle)

Think: "Where do I get 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 per-type pools use:

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?"