Restructure projectHEADmain

1 files changed, 144 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f0b103d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# GFX - 3D Rendering Library
+
+A portable 3D rendering library with minimal dependencies written for
+educational purposes.
+
+## Guiding Principles
+
+- 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.
+
+## Design
+
+### Gfx
+
+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
+like OpenGL or Vulkan. It holds GPU resources such as geometry, textures,
+shaders, etc, and exposes functions to manipulate them.
+
+Currently there is only one implementation of the `Render` backend based on
+OpenGL.
+
+#### Ownership
+
+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 pointing to buffers).
+
+There is no ownership tracking in the render backend. It is up to the client to
+manage resource lifetime.
+
+### Scene
+
+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
+
+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.
+
+### 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
+
+- Render graphs to allow for custom multi-pass rendering algorithms.
+
+## Build (Ubuntu)
+
+```
+sudo apt install libbsd-dev libgl-dev libglfw3-dev zlib1g-dev
+```
+
+TODO: Add these libraries to `contrib/`.