Clarify doc

5 files changed, 120 insertions, 0 deletions

diff --git a/include/gfx/core.h b/include/gfx/core.h
index 2a29003..0cf4465 100644
--- a/include/gfx/core.h
+++ b/include/gfx/core.h
@@ -474,6 +474,9 @@ void gfx_deactivate_shader_program(const ShaderProgram*);
 ///
 /// This function should be called after setting all of the uniform variables
 /// and prior to issuing a draw call.
+///
+/// The given program must have been activated prior to this call with
+/// gfx_activate_shader_program().
 void gfx_apply_uniforms(const ShaderProgram*);
 
 /// Set the texture uniform.
diff --git a/include/gfx/scene/light.h b/include/gfx/llr/light.h
index 132e344..132e344 100644
--- a/include/gfx/scene/light.h
+++ b/include/gfx/llr/light.h
diff --git a/include/gfx/llr/llr.h b/include/gfx/llr/llr.h
new file mode 100644
index 0000000..49b7706
--- /dev/null
+++ b/include/gfx/llr/llr.h
@@ -0,0 +1,117 @@
+#pragma once
+
+#include <math/aabb2.h>
+#include <math/aabb3.h>
+#include <math/camera.h>
+#include <math/mat4.h>
+#include <math/vec3.h>
+#include <math/vec4.h>
+
+typedef struct Anima    Anima;
+typedef struct Light    Light;
+typedef struct Mesh     Mesh;
+typedef struct Skeleton Skeleton;
+
+typedef struct ImmRenderer ImmRenderer;
+
+/// Prepare the graphics systems for immediate-mode rendering.
+///
+/// Call this before issuing any immediate-mode rendering draws.
+void gfx_imm_start(ImmRenderer*);
+
+/// End immediate mode rendering.
+///
+/// Call this after issuing immediate-mode rendering draws and before swapping
+/// buffers.
+void gfx_imm_end(ImmRenderer*);
+
+// -----------------------------------------------------------------------------
+// Immediate-mode rendering of scene elements.
+//
+// This renders models and meshes under lighting. It is up to the client to
+// determine visibility, sort the calls optimally, etc.
+
+/// Push a light into the lights stack.
+void gfx_imm_push_light(ImmRenderer*, Light*);
+
+/// Pop the last light from the lights stack.
+void gfx_imm_pop_light(ImmRenderer*);
+
+/// Load a skeleton.
+///
+/// If a skeleton is loaded, subsequent meshes are rendered with joint data
+/// passed to the shader. This has a cost, so if subsequent meshes are not
+/// animated, unload the skeleton prior to rendering them.
+void gfx_imm_set_skeleton(ImmRenderer*, const Anima*, const Skeleton*);
+
+/// Unload the loaded skeleton.
+void gfx_imm_unset_skeleton(ImmRenderer*);
+
+/// Render the mesh.
+void gfx_imm_render_mesh(ImmRenderer*, const Mesh*);
+
+// -----------------------------------------------------------------------------
+// Immediate-mode rendering of primitives.
+//
+// This is rather inefficient and should be reserved for debug rendering. It
+// also does not support lighting; the primitives are rendered with a constant
+// colour.
+
+/// Draw a set of triangles.
+void gfx_imm_draw_triangles(ImmRenderer*, const vec3[], size_t num_triangles);
+
+/// Draw a triangle.
+void gfx_imm_draw_triangle(ImmRenderer*, const vec3[3]);
+
+/// Draw a bounding box.
+void gfx_imm_draw_aabb2(ImmRenderer*, aabb2);
+
+/// Draw a bounding box.
+void gfx_imm_draw_aabb3(ImmRenderer*, aabb3);
+
+/// Draw a box.
+///
+/// The vertices must be given in the following order:
+///
+///     7 ----- 6
+///    /       /|
+///   3 ----- 2 |
+///   |       | |
+///   | 4 ----- 5
+///   |/      |/
+///   0 ----- 1
+void gfx_imm_draw_box3(ImmRenderer* renderer, const vec3 vertices[8]);
+
+/// Set the render colour.
+void gfx_imm_set_colour(ImmRenderer*, vec4 colour);
+
+// -----------------------------------------------------------------------------
+// Matrix stack manipulation.
+//
+// Common to both scene and and primitive rendering.
+
+/// Load an identity model matrix. Clears the matrix stack.
+void gfx_imm_load_identity(ImmRenderer* renderer);
+
+/// Push the given matrix to the matrix stack.
+void gfx_imm_push_matrix(ImmRenderer* renderer, const mat4* matrix);
+
+/// Pop the top of the matrix stack.
+void gfx_imm_pop_matrix(ImmRenderer* renderer);
+
+/// Push a translation matrix to the matrix stack.
+void gfx_imm_translate(ImmRenderer* renderer, vec3 offset);
+
+/// Set the model matrix. Clears the matrix stack.
+void gfx_imm_set_model_matrix(ImmRenderer*, const mat4*);
+
+// -----------------------------------------------------------------------------
+// Camera
+//
+// Common to both scene and and primitive rendering.
+
+/// Set the camera.
+void gfx_imm_set_camera(ImmRenderer*, const Camera*);
+
+/// Set the view-projection matrix.
+// void gfx_imm_set_view_projection_matrix(ImmRenderer*, const mat4*);
diff --git a/include/gfx/scene/material.h b/include/gfx/llr/material.h
index bca664e..bca664e 100644
--- a/include/gfx/scene/material.h
+++ b/include/gfx/llr/material.h
diff --git a/include/gfx/scene/mesh.h b/include/gfx/llr/mesh.h
index 0d3b4d4..0d3b4d4 100644
--- a/include/gfx/scene/mesh.h
+++ b/include/gfx/llr/mesh.h