moving dir name

2026-09-25 19:32:33 -07:00
parent 15932879e8
commit 86b36f27c6
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,379 @@
+# 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
+ ├── meshPool          Pool<Mesh, MeshHandle>
+ ├── renderTargetPool  RenderTargetPool → RenderTargetHandle
+ │                     (wraps Pool; waits for the GPU on release, applies resizes)
+ ├── texturePool       (planned)
+ └── materialPool      (planned)
+```
+
+Engine code (`Application`, `ImGuiRenderer`, `SceneRenderer`) uses the pools
+directly, e.g. `resources.renderTargetPool.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 wraps a `Pool<Panel, PanelHandle>` (the same generation-checked
+slot pool ResourceRegistry uses, in `sophia/util/pool.hpp`) and adds the
+Panel-specific parts: lookup by type or name, and the default dock layout:
+
+```
+PanelRegistry
+ └── Pool<Panel, PanelHandle>
+      └── 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?"
+
+## SceneRegistry
+
+A SceneRegistry owns Scenes on the caller's behalf and hands out lightweight
+SceneHandles instead of pointers or ownership. Like PanelRegistry, it is owned
+by Application and reached from frontend code directly (`scenes()`), rather than
+through ResourceRegistryRef: scenes are CPU-side entity data, not GPU resources.
+
+Internally it wraps a `Pool<Scene, SceneHandle>`:
+
+```
+SceneRegistry
+ └── Pool<Scene, SceneHandle>
+      └── Slot { Scene, generation }  →  SceneHandle
+```
+
+Typical lifecycle:
+
+```
+create()  →  SceneHandle
+                  │
+        get(handle)  →  Scene&
+                  │
+        release(handle)
+```
+
+Think: "Where do I create or look up a Scene 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?"