From ca9cfa9be4c70be879d5a2fb0cfef8a70ddda00d Mon Sep 17 00:00:00 2001 From: 3gg <3gg@shellblade.net> Date: Sat, 4 Feb 2023 17:53:07 -0800 Subject: Consolidate READMEs under one file. --- gfx/README.md | 133 +++++++++++++++++++++++++++++++--------- gfx/include/gfx/README.md | 3 - gfx/include/gfx/scene/README.md | 75 ---------------------- gfx/include/gfx/util/README.md | 3 - 4 files changed, 103 insertions(+), 111 deletions(-) delete mode 100644 gfx/include/gfx/README.md delete mode 100644 gfx/include/gfx/scene/README.md delete mode 100644 gfx/include/gfx/util/README.md diff --git a/gfx/README.md b/gfx/README.md index 97c6ce9..f0b103d 100644 --- a/gfx/README.md +++ b/gfx/README.md @@ -5,13 +5,13 @@ educational purposes. ## Guiding Principles -- Provide a minimal set of functionality necessary for indie games and graphics - applications. -- Provide a minimal interface; physically hide the implementation. -- Allow for additional future rendering backends (e.g. Vulkan). -- Strive for a minimal set of dependencies. -- All dependencies but system libraries should be compiled with the graphics - library for portability and ease of use. +- Provide enough functionality for graphics applications and indie games. +- Provide a minimal interface, physically hide the implementation. Make bindings + easy. +- Establish a clean separation from the render backend and the rest of the + library to allow for additional rendering backends (e.g. Vulkan). +- Strive for a minimal set of dependencies, all of which should ship and compile + with the graphics library for ease of use. - Rely on dynamic allocation as little as possible. Isolate dynamic allocation to where it is strictly needed. @@ -19,37 +19,105 @@ educational purposes. ### Gfx -The `Gfx` object represents the graphics subsystem and provides a high-level API -to render graphics. The `Gfx` object exposes a `Render` backend and a `Renderer` -, and allows the caller to create `Scene` objects. +The `Gfx` object represents the graphics subsystem and is at the center of the +library's high-level API. The `Gfx` object exposes a `Render` backend and a +`Renderer` and allows the caller to create `Scene`s. ### Render Backend -The `Render Backend` is a thin abstraction layer over low-level graphics APIs -(OpenGL, etc). It presents an immediate mode style of rendering, whereby callers -directly submit draw commands to the `Render Backend`. +The `Render` backend is a thin abstraction layer over low-level graphics APIs +like OpenGL or Vulkan. It holds GPU resources such as geometry, textures, +shaders, etc, and exposes functions to manipulate them. -The `Render Backend` holds GPU resources such as geometry, textures, shaders, -etc. - -Currently there is only one implementation of the `Render Backend` based on -OpenGL for simplicity and portability. +Currently there is only one implementation of the `Render` backend based on +OpenGL. #### Ownership -The `Render Backend` owns all rendering resources: buffers, geometries, +The `Render` backend owns all rendering resources: buffers, geometries, textures, shaders, etc. Even resources that point to other resources do not own -those other resources (geometries and buffers). +those other resources (geometries pointing to buffers). -There is no sophisticated resource sharing on the renderer side, like reference -counting or resource naming. Instead, it is up to the user to make appropriate -use of allocated resources and share them where appropriate. +There is no ownership tracking in the render backend. It is up to the client to +manage resource lifetime. ### Scene -A `Scene` is the top-level object of a scene graph. A scene graph is a -description of the scene and holds all of the elements that make up a scene: -nodes, cameras, lights, objects, etc. +A `Scene` encapsulates a scene graph. A scene graph contains the elements that +make up a scene: nodes, cameras, lights, objects, etc. The current scene graph +implementation includes: + +- Camera +- Light +- Material +- Mesh +- Node +- Object +- Scene + +#### Hierarchy and Parenting + +Scene graphs typically expose functions on nodes to add/remove objects, cameras, +lights, etc. This implementation forces the hierarchy to be a strict tree and +not a more general DAG. Given this, and to avoid confusion, we instead expose +functions to set the parent node of an object/camera/light. If we exposed the +former, the API could create the illusion that the hierarchy can be a DAG. + +The strict tree hierarchy should not be that restrictive in practice. Even the +glTF 2.0 spec [enforces this](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#nodes-and-hierarchy): + +> *For Version 2.0 conformance, the glTF node hierarchy is not a directed +> acyclic graph (DAG) or scene graph, but a disjoint union of strict trees. That +> is, no node may be a direct descendant of more than one node. This restriction +> is meant to simplify implementation and facilitate conformance.* + +#### Instancing + +Two use cases for instancing seem to be: + +1. Creating N identical clones, but each with a unique transform. (Ex: N +animated characters animated in unison but located in different locations.) +2. Creating N copies of a sub-tree, each now being their own unique tree. (Ex: +The same N animated characters, but each of them now being animated separately.) + +Some scene graphs +([Panda3D](https://docs.panda3d.org/1.10/python/programming/scene-graph/instancing)) +allow two or more nodes to point to the same child, or, in other words, a node +to have multiple parents. This turns the scene graph into a DAG and adds a +number of complications for us: + +1. Shared ownership of children. We would now need some sort of ref counting or +deferred GC to delete nodes and their subtrees. +2. Nodes no longer have a unique parent. +3. Given a node, we can no longer determine its location (which parent link do +you follow?), or any attribute that is derived from its parent(s). + +In our case, we stick to strict tree hierarchies. + +Use case (1), N identical clones with unique transforms, is not a problem for +us. This is because the bulk of the data -- geometry buffers, etc. -- is stored +in the render backend anyway. So creating a full copy of the node does not +present a significant overhead since we need a unique transform for each of the +clones anyway. + +Use case (2) does present a bit more overhead and we currently do not handle it. +This could be handled in the future by special-casing a node such as +`InstanceNode` that has one child subtree and N transforms (or other +attributes), one for each unique instance of that child subtree. + +Therefore, to visit the use cases again: + +1. N character clones animated in unison in different locations -> future + `InstanceNode`. +2. N unique character copies animated on their own -> copy the character subtree + (N unique skeletons; shared mesh data and textures stored in the render + backend.) + +#### Reading + +[Panda3D Scene Graph](https://docs.panda3d.org/1.10/python/programming/scene-graph/index) + +[Pixar's USD](https://graphics.pixar.com/usd/release/intro.html) ### Renderer @@ -57,10 +125,15 @@ The `Renderer` takes a `Render` backend and a `Scene` and renders the scene. Currently, only a forward renderer is provided, but additional renderers can be implemented in the future. -## Future Work +### Util + +Code under `util/` provides functionality that need not be in the core part +of the library (Gfx, render backend, scene or renderer). This includes functions +to compute irradiance maps, create procedural geometry, etc. + +## Ideas for Future Work -- Ideally, some way to customize the rendering pipeline to allow for custom - multi-pass rendering algorithms. +- Render graphs to allow for custom multi-pass rendering algorithms. ## Build (Ubuntu) @@ -68,4 +141,4 @@ implemented in the future. sudo apt install libbsd-dev libgl-dev libglfw3-dev zlib1g-dev ``` -TODO: Add GLFW and zlib to `contrib/`. +TODO: Add these libraries to `contrib/`. diff --git a/gfx/include/gfx/README.md b/gfx/include/gfx/README.md deleted file mode 100644 index 81f6759..0000000 --- a/gfx/include/gfx/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# GFX / include - -Public API of the graphics library. diff --git a/gfx/include/gfx/scene/README.md b/gfx/include/gfx/scene/README.md deleted file mode 100644 index c8cdadb..0000000 --- a/gfx/include/gfx/scene/README.md +++ /dev/null @@ -1,75 +0,0 @@ -# Scene Graph - -A scene graph implementation that includes: - -- Camera -- Light -- Material -- Mesh -- Node -- Object -- Scene - -## Hierarchy and Parenting - -Scene graphs typically expose functions on nodes to add/remove objects, cameras, -lights, etc. This implementation forces the hierarchy to be a strict tree and -not a more general DAG. Given this, and to avoid confusion, we instead expose -functions to set the parent node of an object/camera/light. If we exposed the -former, the API could create the illusion that the hierarchy can be a DAG. - -The strict tree hierarchy should not be that restrictive in practice. Even the -glTF 2.0 spec [enforces this](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#nodes-and-hierarchy): - -> *For Version 2.0 conformance, the glTF node hierarchy is not a directed -> acyclic graph (DAG) or scene graph, but a disjoint union of strict trees. That -> is, no node may be a direct descendant of more than one node. This restriction -> is meant to simplify implementation and facilitate conformance.* - -## Instancing - -Two use cases for instancing seem to be: - -1. Creating N identical clones, but each with a unique transform. (Ex: N -animated characters animated in unison but located in different locations.) -2. Creating N copies of a sub-tree, each now being their own unique tree. (Ex: -The same N animated characters, but each of them now being animated separately.) - -Some scene graphs -([Panda3D](https://docs.panda3d.org/1.10/python/programming/scene-graph/instancing)) -allow two or more nodes to point to the same child, or, in other words, a node -to have multiple parents. This turns the scene graph into a DAG and adds a -number of complications for us: - -1. Shared ownership of children. We would now need some sort of ref counting or -deferred GC to delete nodes and their subtrees. -2. Nodes no longer have a unique parent. -3. Given a node, we can no longer determine its location (which parent link do -you follow?), or any attribute that is derived from its parent(s). - -In our case, we stick to strict tree hierarchies. - -Use case (1), N identical clones with unique transforms, is not a problem for -us. This is because the bulk of the data -- geometry buffers, etc. -- is stored -in the render backend anyway. So creating a full copy of the node does not -present a significant overhead since we need a unique transform for each of the -clones anyway. - -Use case (2) does present a bit more overhead and we currently do not handle it. -This could be handled in the future by special-casing a node such as -`InstanceNode` that has one child subtree and N transforms (or other -attributes), one for each unique instance of that child subtree. - -Therefore, to visit the use cases again: - -1. N character clones animated in unison in different locations -> future - `InstanceNode`. -2. N unique character copies animated on their own -> copy the character subtree - (N unique skeletons; shared mesh data and textures stored in the render - backend.) - -## Reading - -[Panda3D Scene Graph](https://docs.panda3d.org/1.10/python/programming/scene-graph/index) - -[Pixar's USD](https://graphics.pixar.com/usd/release/intro.html) diff --git a/gfx/include/gfx/util/README.md b/gfx/include/gfx/util/README.md deleted file mode 100644 index 642cf24..0000000 --- a/gfx/include/gfx/util/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# GFX / util - -Various utilities on top of the core graphics library. -- cgit v1.2.3