Accessing the Contents of a Vertex Buffer

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

Vertex buffer objects enable applications to directly access the memory allocated for vertex data. You can retrieve a pointer to vertex buffer memory by calling the IDirect3DMobileVertexBuffer::Lock method, and then accessing the memory as needed to fill the buffer with new vertex data or to read any data it already contains. The Lock method accepts four parameters. The first, OffsetToLock, is the offset into the vertex data. The second parameter is the size, measured in bytes, of the vertex data. The third parameter accepted by the Lock method, ppbData, is the address of a BYTE pointer that points to the vertex data, if the call succeeds.

The last parameter, Flags, tells the system how the memory should be locked. You can use it to indicate how the application will access the data in the buffer. Specify constants for the Flags parameter according to the way the vertex data will be accessed. This allows the driver to lock the memory and provide the best performance, given the requested access type. Use D3DMLOCK_READONLY flag (see D3DMLOCK Values) if your application will read only from the vertex buffer memory. Including this flag enables Microsoft® Direct3D Mobile® to optimize its internal procedures to improve efficiency, given that access to the memory will be read-only.

After you finish filling or reading the vertex data, call the IDirect3DMobileVertexBuffer::Unlock method, as shown in the following code example.

// This code example assumes the g_pVB is a pointer to an
// IDirect3DMobileVertexBuffer interface and that g_Vertices has
// been properly initialized with vertices.

// To fill the vertex buffer, you need to lock the buffer to
// gain access to the vertices. This mechanism is required because 
// vertex buffers may be in device memory.
VOID* pVertices;

if( FAILED( g_pVB->Lock( 0,                  // Fill from the start of 
                                             // the buffer.
                         sizeof(g_Vertices), // Size of the data to 
                                             // load.
                         (BYTE**)&pVertices, // Returned vertex data.
                         0 ) ) )             // Send default flags to 
                                             // the lock.
    return E_FAIL;

memcpy( pVertices, g_Vertices, sizeof(g_Vertices) );
g_pVB->Unlock();

Because you directly access the memory allocated for the vertex buffer, make sure your application properly accesses the allocated memory. Otherwise, you risk rendering that memory invalid. Use the stride of the vertex format that your application uses to move from one vertex in the allocated buffer to another. The vertex buffer memory is a simple array of vertices specified in flexible vertex format. Use the stride of whatever vertex format structure you define. You can calculate the stride of each vertex at run time by examining the flexible vertex format flags (see D3DMFVF Values) contained in the vertex buffer description. The following table shows the size for each vertex component.

The number of texture coordinates present in the vertex format is described by the D3DMFVF_TEXn flags (where n is a value from 0 to 8). Multiply the number of texture coordinate sets by the size of one set of texture coordinates, which can range from one to four floats, to calculate the memory required for that number of texture coordinates.

Use the total vertex stride to increment and decrement the memory pointer as needed to access particular vertices.

See Also

Concepts

Using Vertex Buffers