mirror of https://github.com/visgl/luma.gl.git synced 2025-12-08 17:36:19 +00:00

2018-06-27 12:47:24 -07:00

10 KiB

Raw Blame History

VertexArray

A VertexArray object holds a map of "buffers" that will be made available as input data to shaders during a draw call, similar to how a TransformFeedback object holds a set of Buffer instances that will receive output data from shaders.

A properly configured VertexArray should contain one binding (to a Buffer object or a constant) for every named attribute in the shader (or for every layout declared location in the shader) representing the input data. For Buffer objects, the VertexArray also stores some additional information about how that data in the buffer should be accessed, such as offsets, strides, etc.

Note that it is usually not necessary to manipulate VertexArray directly in luma.gl applications. It is often simpler to just supply attributes to the Model class, and rely on that class to automatically manage the vertex attributes array and supply it to any draw calls (e.g. when rendering, picking etc). Still, it can be useful to review this documentation to understand how attributes are handled.

For more information on WebGL VertexArrayObjects, see OpenGL Wiki.

Notes:

VertexArrays are provided by a WebGL1 extension on some WebGL1 systems: vertex_array_objects extension. To make sure they are supported in all WebGL1 environments, import luma.gl/webgl1 before creating any WebGL contexts.

Usage

Import the VertexArray class so that your app can use it:

import {VertexArray} from 'luma.gl';

Getting the global VertexArray for a WebGL context

const vertexArray = VertexArray.global(gl);

Create a new VertexArray

const vao = new VertexArray(gl);
}

Adding attributes to a VertexArray

const vertexArray = new VertexArray(gl);
vertexArray.setBuffer(location, buffer);
vertexArray.setBuffer(name, buffer);

Deleting a VertexArray

vertexArrayObject.delete();

Setting a set of attributes and an elements array

const vertexArray = new VertexArray(gl, {
  elements:
    new Buffer({target: GL.ELEMENT_ARRAY_BUFFER, data: new Uint32Array([...])}),
  buffers: {
  	0: new Buffer({data: new Float32Array([...])})
  }
}

const vertexArray = new VertexArray(gl);
// Can only set buffers using location indices
vertexArray.setBuffers({
  0: new Buffer({data: new Float32Array([...]), ...})
});

Setting attribute metadata

// Register attribute info
const program = new Program(gl, ...);
vertexArray.initialize({attributeInfo: program.getAttributeInfo()});

// Now it is possible to set buffers using attribute names
vertexArray.setBuffers({
  aColor: new Buffer({size: 3, data: new Float32Array([...]), ...})
});

vertexArray.initialize({program: });

Setting a constant vertex attribute

import {VertexArray} from 'luma.gl';
const vao = new VertexArray(gl);
vao.setConstant(0, [0, 0, 0]);

Methods

VertexArray inherits from Resource.

VertexArray(gl : WebGLRenderingContext, props : Object)

Creates a new VertexArray

props (Object) - passed through to Resource superclass constructor and to initialize

VertexArray.getDefaultArray() : VertexArray

Returns the "global" VertexArray.

Note: The global VertexArray object is always available. Binds the null VertexArrayObject.

initialize(props : Object) : VertexArray

Reinitializes a VertexArray.

attributes={} (Object) - map of attributes, can be keyed by index or names, can be constants (small arrays), Buffer, arrays or typed arrays of numbers, or attribute descriptors.
elements=null (Buffer) - optional buffer representing elements array (i.e. indices)
program - Transfers information on vertex attribute locations and types to this vertex array.

setAttributes(attributes : Object) : VertexArray

Sets named uniforms from a map.

program.setAttributes(attributes : Object);

attributes - (object) An object with key value pairs matching a buffer name and its value respectively.

Attributes is an object with key-value pairs: {nameOrLocation: value, ....}.

nameOrLocation - (string|number) The name of the attribute as declared in the shader, or the location specified by a layout qualifier in the shader.
value - (Buffer|Array|typed array) An attribute value must be a Buffer or a typed array.

Each value can be an a Buffer, an Array starting with a Buffer or a typed array.

Typed Array - Sets a constant value as if .setConstant(value) was called.
Buffer - Binds the atttribute to a buffer, using buffer's accessor data as if .setBuffer(value) was called.
Array - Binds the atttribute to a buffer, with extra accessor data overrides. Expects a two element array with [buffer : Buffer, accessor : Object]. Binds the attribute to the buffer as if .setBuffer(buffer, accessor) was called.

setConstant(values : Array) : VertexArray

Sets a constant value for a vertex attribute. When this VertexArray is used in a Program.draw() call, all Vertex Shader invocations will get the same value.

VertexArray.setConstant(location, array);

gl (WebGLRenderingContext) - gl context
location (GLuint) - index of the attribute

WebGL APIs: vertexAttrib4[u]{f,i}v

setBuffer(nameOrLocation, buffer : Buffer [, accessor : Object]) : VertexArray

Binds the specified attribute in this vertex array to the supplied buffer

Set a location in vertex attributes array to a buffer, specifying
its data layout and integer to float conversion and normalization flags

setBuffer(location, buffer); setBuffer(location, buffer, {offset = 0, stride = 0, normalized = false, integer = false});

location (GLuint | String) - index/ordinal number of the attribute
buffer (WebGLBuffer|Buffer) - WebGL buffer to set as value

gl.vertexAttrib{I}Pointer, gl.vertexAttribDivisor

getParameter(pname, location) : *

Queries a vertex attribute location.

pname (GLenum) - Which parameter to query. See table of parameter constants below for values.
location (Number) - index of attributes

Note that in WebGL queries are generally slow and should be avoided in performance critical code sections.

Types, Constants, Enumarations

Attribute Accessors

When setting Buffer attributes, additional data can be provided to specify how the buffer should be accessed. This data can be stored directly on the Buffer accessor or supplied to .setBuffer.

target=buffer.target (GLuint, ) - which target to bind to
size (GLuint) - number of values (components) per element (1-4)
type (GLuint) - type of values (e.g. gl.FLOAT)
normalized (boolean, false) - normalize integers to [-1,1] or [0,1]
integer (boolean, false) - WebGL2 disable int-to-float conversion
stride (GLuint, 0) - supports strided arrays
offset (GLuint, 0) - supports strided arrays
layout.normalized=false (GLbool) - normalize integers to [-1,1], [0,1]
layout.integer=false (GLuint) - WebGL2 only, disable int-to-float conv.
divisor - Sets the frequency divisor used for instanced rendering (instances that pass between updates of attribute). Usually simply set to 1 or 0 to enable/disable instanced rendering. 0 disables instancing, >=1 enables it.