glossary

_Design/glossary.md

@@ -0,0 +1,329 @@
+# Glossary
+
+## AssetRegistry
+
+An AssetRegistry owns GPU-backed assets 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
+asset type:
+
+```
+AssetRegistry
+ ├── 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 asset (or freed memory).
+
+Typical lifecycle:
+
+```
+load<Mesh>(path) / loadMesh(...)  →  MeshHandle
+                                        │
+                        get<Mesh>(handle)  →  const Mesh&
+                                        │
+                        release<Mesh>(handle)
+```
+
+Think: "Where do I get or release a GPU asset 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 AssetRegistry'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:
+
+```cpp
+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?"