VertexBuffer::BeginUpdate

Maps a vertex buffer and returns a pointer to its storage.

template <typename type> volatile type *BeginUpdate(void);

template <typename type> volatile type *BeginUpdateSync(void);

type	The type to which the return value points.

The BeginUpdate function maps a vertex buffer's storage into CPU-accessible memory and returns a pointer to the storage buffer. This function should only be called after the VertexBuffer::EstablishVertexBuffer function has been called for the vertex buffer with a nonzero size parameter, and the maximum number of bytes that can be written to the buffer returned by BeginUpdate is the number that was specified by the size parameter.

The BeginUpdateSync variant of the BeginUpdate function should normally be called to ensure that the GPU driver is being accessed properly in multithreaded contexts. The BeginUpdate function should only be called if it's a certainty that it is being called from the main thread. Both functions have the same effect.

When a vertex buffer is mapped into CPU-accessible memory with either the BeginUpdate or BeginUpdateSync function, the data in the vertex buffer is completely destroyed. Any vertex data that will be later read from the vertex buffer by the GPU must be written to the buffer in its entirety. It is thus not possible to update only the texture coordinates for a vertex array without also rewriting the vertex positions, for example. In the case that vertices contain some data that is static and some data that is dynamic, two separate vertex buffers should be used. (The vertex buffer data is destroyed as an optimization that prevents an expensive copy of the existing data into the CPU-accessible buffer.)

Once the data has been written to a vertex buffer, the VertexBuffer::EndUpdate must be called to unmap the storage buffer before any rendering commands referencing the vertex buffer are issued.

For a static vertex buffer, the BeginUpdate function should be called at most one time and only if no buffer data was supplied with the VertexBuffer::EstablishVertexBuffer function. Otherwise, performance may be degraded. Dynamic vertex buffers can be updated as often as needed without any performance penalty. Data should be written to the buffer returned by the BeginUpdate function contiguously and in order. This promotes the most efficient writeback performance for memory that is possibly write-combined. The pointer returned by the BeginUpdate function is declared volatile to prevent the compiler from changing the program order of individual writes.

Since the vertex buffer cannot be accessed through any pointers other than the one returned by the BeginUpdate function, the variable to which it's assigned should be declared restrict in order to allow the compiler to perform optimizations that it may not otherwise be able to perform with respect to reads from ordinary program data. For example, the following code should be used to cast the return value of the BeginUpdateSync function, called for a VertexBuffer object named vertexBuffer, to a pointer to Point3D and declare it as restricted.

VertexBuffer::EndUpdate

VertexBuffer::UpdateBuffer