4 files changed, 103 insertions, 111 deletions

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.