luma.gl/docs/api-guide/vertex-array.md

VertexArray

:::info Unless you are writing framework level code, it is usually not necessary to create VertexArray instances in luma.gl applications. It is often simpler to just provides attributes directly to the Model class. Still, it can be useful to review this documentation to understand how attributes are handled by luma.gl under the hood. :::

A VertexArray object lets the application map a set of GPU buffers to shader locations and the index buffer. By providing a vertexArray to a draw call, the buffers will be made available as input data to shaders,

Using multiple VertexArray makes it easy for applications to reuse the same shaders.

Remarks:

• WebGPU - WebGPU does not provide a native VertexArray type resource. This is just a convenience class that groups all attribute and index buffer bindings for a draw call.
• WebGL -
• WebGL2 - see the OpenGL Wiki.
• WebGL1 - If the OES_vertex_array_object extension is not available, VertexArrayObject is polyfilled (binding all buffers before each draw call). (This is the only WebGL extension that can be polyfilled on the client side).

Usage

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

import {VertexArray} from '@luma.gl/core';

Create a new VertexArray

const vertexArray = device.createVertexArray();
}

Adding attributes to a VertexArray

const vertexArray = device.createVertexArray();
vertexArray.setBuffer(location, buffer);

Deleting a VertexArray

vertexArrayObject.destroy();

Setting a constant vertex attribute

import {VertexArray} from '@luma.gl/core';
const vertexArray = device.createVertexArray();
vertexArray.setConstant(0, [0, 0, 0]);

To discover how many attribute locations are available on the current system

const maxVertesAttributes = device.limits.maxVertexAttributes;

Methods

VertexArray inherits from Resource.

constructor

device.createVertexArray(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 VertexArray.

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.

setConstant

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: number, constant: NumberArray) : VertexArray

• location - index of the attribute
• array - the constant value

Remarks:

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

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

setBuffer(location: number, 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

• location (GLuint | String) - index/ordinal number of the attribute

• buffer (WebGLBuffer|Buffer) - WebGL buffer to set as value

Remarks:

• WebGL APIs gl.vertexAttrib{I}Pointer, gl.vertexAttribDivisor

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) - WebGL 2 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) - WebGL 2 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.

Notes:

• The application can enable normalization by setting the normalized flag to true in the setBuffer call.
• WebGL 2 The application can disable integer to float conversion when running under WebGL 2, by setting the integer flag to true.
• glVertexAttribIPointer specifies integer data formats and locations of vertex attributes. Values are always left as integer values. Only accepts the integer types gl.BYTE, gl.UNSIGNED_BYTE, gl.SHORT, gl.UNSIGNED_SHORT, gl.INT, gl.UNSIGNED_INT

Notes about Instanced Rendering

• About setting divisor in attributes: Instanced attributes requires WebGL 2 or a (widely supported) WebGL 1 extension. Apps can use the luma.gl feature detection system to determine if instanced rendering is available, though the extension is so ubiquitously supported that many apps just make the assumption: instanced_arrays.
• An attribute is referred to as instanced if its divisor value is non-zero.
• The divisor modifies the rate at which vertex attributes advance when rendering multiple instances of primitives in a single draw call.
• If divisor is zero, the attribute at slot index advances once per vertex.
• If divisor is non-zero, the attribute advances once per divisor instances of the set(s) of vertices being rendered.