1 files changed, 152 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..491761d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# 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 (`GfxCore`)
+and a `Renderer`, and allows the caller to create `Scene`s.
+
+### Render Backend
+
+The render backend (`GfxCore`) 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 lifetime tracking in the render backend. It is up to the client to
+manage resource lifetime.
+
+### Low-level Renderer
+
+`ImmRenderer` is a low-level, immediate mode renderer.
+
+### Scene
+
+A `Scene` graph contains the elements that make up a scene. 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.
+
+### Memory management
+
+TODO
+
+## 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/`.