From 0e3cddca04cc0ec9d3ea73debb1fa358e44aa538 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Tue, 11 Dec 2018 17:47:12 -0500
Subject: render: buffer: Improve docstrings.

---
 chickadee/render/buffer.scm | 71 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 7 deletions(-)

diff --git a/chickadee/render/buffer.scm b/chickadee/render/buffer.scm
index cf0a79b..702423b 100644
--- a/chickadee/render/buffer.scm
+++ b/chickadee/render/buffer.scm
@@ -56,7 +56,6 @@
             typed-buffer->buffer
             typed-buffer->vector
             typed-buffer-name
-            typed-buffer-view
             typed-buffer-offset
             typed-buffer-component-type
             typed-buffer-normalized?
@@ -150,14 +149,26 @@
                       (stride 0)
                       (target 'vertex)
                       (usage 'static))
-  "Upload BV, a bytevector of TYPE elements, to the GPU as a vertex
-buffer.
+  "Upload DATA, a bytevector, to the GPU.  By default, the entire
+bytevector is uploaded.  A subset of the data may be uploaded by
+specifying the OFFSET, the index of the first byte to be uploaded, and
+LENGTH, the number of bytes to upload.
 
-USAGE provides a hint to the GPU as to how the vertex buffer will be
-used:
+If DATA is #f, allocate LENGTH bytes of fresh GPU memory instead.
 
-- static: The vertex buffer will not be modified after creation.
-- stream: The vertex buffer will be modified frequently."
+TARGET and USAGE are hints that tell the GPU how the buffer is
+intended to be used.
+
+TARGET may be:
+- vertex: Vertex attribute data.
+- index: Index buffer data.
+
+USAGE may be:
+- static: The buffer data will not be modified after creation.
+- stream: The buffer data will be modified frequently.
+
+NAME is simply an arbitrary string for debugging purposes that is
+never sent to the GPU."
   ;; Weird bugs will occur when creating a new vertex buffer while a
   ;; vertex array is bound.
   (gpu-state-set! *vertex-array-state* null-vertex-array)
@@ -265,6 +276,36 @@ vertex buffer data back to the GPU."
                             min
                             sparse
                             divisor)
+  "Return a new typed buffer view for BUFFER starting at byte index
+OFFSET of LENGTH elements, where each element is of TYPE and composed
+of COMPONENT-TYPE values.
+
+Valid values for TYPE are:
+- scalar: single number
+- vec2: 2D vector
+- vec3: 3D vector
+- vec4: 4D vector
+- mat2: 2x2 matrix
+- mat3: 3x3 matrix
+- mat4: 4x4 matrix
+
+Valid values for COMPONENT-TYPE are:
+
+- byte
+- unsigned-byte
+- short
+- unsigned-short
+- int
+- unsigned-int
+- float
+- double
+
+DIVISOR is only needed for instanced rendering applications and
+represents how many instances each vertex element applies to.  A
+divisor of 0 means that a single element is used for every instance
+and is used for the data being instanced.  A divisor of 1 means that
+each element is used for 1 instance.  A divisor of 2 means that each
+element is used for 2 instances, and so on."
   (%make-typed-buffer name buffer offset component-type
                       normalized? length type max min sparse divisor))
 
@@ -502,6 +543,22 @@ which attributes advance when rendering multiple instances."
   (make-gpu-state apply-vertex-array null-vertex-array))
 
 (define* (make-vertex-array #:key indices attributes (mode 'triangles))
+  "Return a new vertex array using the index data within the typed
+buffer INDICES and the vertex attribute data within ATTRIBUTES, an
+alist mapping shader attribute indices to typed buffers containing
+vertex data.
+
+By default, the vertex array is interpreted as containing a series of
+triangles.  If another primtive type is desired, the MODE keyword
+argument may be overridden.  The following values are supported:
+
+- points
+- lines
+- line-loop
+- line-strip
+- triangles
+- triangle-strip
+- triangle-fan"
   (let ((array (gpu-guard
                 (%make-vertex-array (generate-vertex-array)
                                     indices
-- 
cgit v1.2.3