VertexBuffer::EstablishVertexBuffer

Defined in: C4Renderable.h

Establishes the size of a vertex buffer and initializes it.

Prototype

void EstablishVertexBuffer(uint32 size, const void *data = nullptr);

Parameters

`size`	The size, in bytes, of the data that will be stored in the vertex buffer.
`dat`	A pointer to the data that should initially be loaded into the vertex buffer.

Description

The EstablishVertexBuffer function establishes the size of a vertex buffer and initializes its internal resources. This function must be called before data is written to the vertex buffer with the VertexBuffer::BeginUpdate or VertexBuffer::UpdateBuffer functions.

If the data parameter is not nullptr, then size bytes are copied from the memory to which data points into the vertex buffer. Otherwise, the contents of the vertex buffer are initially undefined. For a static vertex buffer, performance is best when the buffer data is supplied with the EstablishVertexBuffer function.

The size parameter should specify the maximum number of bytes of data that will be stored in the buffer. If the size parameter is zero, then the vertex buffer's internal resources are deallocated, and the vertex buffer returns to the state it was in before the EstablishVertexBuffer function was first called. If the size parameter is equal to the same value that was specified for a preceding call to the EstablishVertexBuffer function for the same vertex buffer, then the function quickly returns without reallocating any internal resources.

The EstablishVertexBuffer function can be called from any thread, but the caller must use synchronization mechanisms to ensure that the EstablishVertexBuffer function is not called for the same vertex buffer from multiple threads simultaneously.