From 9b6c5e3ba42eace457ce96600fecd31109e976ab Mon Sep 17 00:00:00 2001 From: David Thompson Date: Tue, 24 Aug 2021 16:16:35 -0400 Subject: doc: Update to reflect renaming of buffer views to vertex attributes. --- doc/api.texi | 92 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 46 insertions(+), 46 deletions(-) (limited to 'doc') diff --git a/doc/api.texi b/doc/api.texi index 68cffef..f6333d6 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -3168,21 +3168,21 @@ float is 4 bytes in length, so the buffer's stride is 16. Within a VBO, one or more ``attributes'', as OpenGL calls them, may be present. Attributes are subregions within the buffer that have a particular data type. In this case, there are two attributes packed -into the buffer. To provided a typed view into a buffer, the -@code{make-buffer-view} procedure is needed: +into the buffer. To define vertex attributes, the +@code{make-vertex-attribute} procedure is needed: @example (define vertices - (make-buffer-view #:buffer buffer - #:type 'vec2 - #:component-type 'float - #:length 4)) + (make-vertex-attribute #:buffer buffer + #:type 'vec2 + #:component-type 'float + #:length 4)) (define texcoords - (make-buffer-view #:buffer buffer - #:type 'vec2 - #:component-type 'float - #:length 4 - #:offset 8)) + (make-vertex-attribute #:buffer buffer + #:type 'vec2 + #:component-type 'float + #:length 4 + #:offset 8)) @end example To render a square, the GPU needs to draw two triangles, which means @@ -3197,21 +3197,20 @@ created. (make-buffer (u32vector 0 3 2 0 2 1) #:target 'index) (define indices - (make-buffer-view #:type 'scalar - #:component-type 'unsigned-int - #:buffer index-buffer)) + (make-vertex-attribute #:type 'scalar + #:component-type 'unsigned-int + #:buffer index-buffer)) @end example Note the use of the @code{#:target} keyword argument. It is required because the GPU treats index data in a special way and must be told which data is index data. -Now that the buffer views representing each attribute have been -created, all that's left is to bind them all together in a ``vertex -array object'', or VAO. Vertex arrays associate each buffer view -with an attribute index on the GPU. The indices that are chosen must -correspond with the indices that the shader (@pxref{Shaders}) expects -for each attribute. +Now that the vertex attributes have been created, all that's left is +to bind them all together in a vertex array. Vertex arrays associate +each vertex attribute with an attribute index on the GPU. The indices +that are chosen must correspond with the indices that the shader +(@pxref{Shaders}) expects for each attribute. @example (define vertex-array @@ -3325,11 +3324,11 @@ This form is useful for streaming buffers that need to update their contents dynamically, such as a sprite batch. @end deffn -@deffn {Procedure} make-buffer-view #:buffer #:type @ +@deffn {Procedure} make-vertex-attribute #:buffer #:type @ #:component-type #:length [#:offset @code{0}] [#:divisor @code{1}] @ [#:name @code{"anonymous"}] -Return a new buffer view for @var{buffer} starting at byte index +Return a new vertex attribute for @var{buffer} starting at byte index @var{offset} of @var{length} elements, where each element is of @var{type} and composed of @var{component-type} values. @@ -3382,53 +3381,54 @@ used for 1 instance. A divisor of 2 means that each element is used for 2 instances, and so on. @end deffn -@deffn {Procedure} buffer-view? obj -Return @code{#t} if @var{obj} is a buffer view. +@deffn {Procedure} vertex-attribute? obj +Return @code{#t} if @var{obj} is a vertex attribute. @end deffn -@deffn {Procedure} buffer-view->buffer buffer-view -Return the buffer that @var{buffer-view} is using. +@deffn {Procedure} vertex-attribute->buffer vertex-attribute +Return the buffer that @var{vertex-attribute} is using. @end deffn -@deffn {Procedure} buffer-view-name buffer-view -Return the name of @var{buffer-view}. +@deffn {Procedure} vertex-attribute-name vertex-attribute +Return the name of @var{vertex-attribute}. @end deffn -@deffn {Procedure} buffer-view-offset buffer-view -Return the byte offset of @var{buffer-view}. +@deffn {Procedure} vertex-attribute-offset vertex-attribute +Return the byte offset of @var{vertex-attribute}. @end deffn -@deffn {Procedure} buffer-view-type buffer-view -Return the data type of @var{buffer-view}. +@deffn {Procedure} vertex-attribute-type vertex-attribute +Return the data type of @var{vertex-attribute}. @end deffn -@deffn {Procedure} buffer-view-component-type buffer-view -Return the component data type of @var{buffer-view} +@deffn {Procedure} vertex-attribute-component-type vertex-attribute +Return the component data type of @var{vertex-attribute} @end deffn -@deffn {Procedure} buffer-view-divisor buffer-view -Return the instance divisor for @var{buffer-view}. +@deffn {Procedure} vertex-attribute-divisor vertex-attribute +Return the instance divisor for @var{vertex-attribute}. @end deffn -@deffn {Syntax} with-mapped-buffer-view buffer-view body @dots{} +@deffn {Syntax} with-mapped-vertex-attribute vertex-attribute body @dots{} -Evaluate @var{body} in the context of @var{buffer-view} having its -data synced from GPU memory to RAM. See @code{with-mapped-buffer} for -more information. +Evaluate @var{body} in the context of @var{vertex-attribute} having +its data synced from GPU memory to RAM. See @code{with-mapped-buffer} +for more information. @end deffn @deffn {Procedure} make-vertex-array #:indices #:attributes @ [#:mode @code{triangles}] -Return a new vertex array using the index data within the buffer view -@var{indices} and the vertex attribute data within @var{attributes}. +Return a new vertex array using the index data within the vertex +attributes @var{indices} and the vertex attribute data within +@var{attributes}. -@var{attributes} is an alist mapping shader attribute indices to typed -buffers containing vertex data: +@var{attributes} is an alist mapping shader attribute indices to +vertex attributes: @example -`((1 . ,buffer-view-a) - (2 . ,buffer-view-b) +`((1 . ,vertex-attribute-a) + (2 . ,vertex-attribute-b) @dots{}) @end example -- cgit v1.2.3