Creating a Vertex Buffer

The following figure illustrates the steps necessary to create a single vertex buffer.

You create a vertex buffer object by calling the IDirect3D3::CreateVertexBuffer method, which accepts four parameters. The first parameter is the address of a D3DVERTEXBUFFERDESC structure that describes the desired vertex format, buffer size, and general capabilities. These capabilities are detailed in Vertex Buffer Descriptions. Normally, the system automatically determines the best memory location (system or display memory) for the vertex buffer. However, software devices can only be used with explicit system-memory vertex buffers. For more information, see Vertex Buffers and Device Types.

The second parameter that CreateVertexBuffer accepts is the address of a variable that will be filled with a pointer to the new IDirect3DVertexBuffer interface of the vertex buffer object if the call succeeds. The third parameter determines if the vertex buffer will be capable of containing clipping information—in the form of clip flags—for vertices that exist outside the viewing area. Set this to 0 to create a "clipping-capable" vertex buffer, or include the D3DDP_DONOTCLIP flag to create a vertex buffer that cannot contain clip flags. The D3DDP_DONOTCLIP flag is only applied if you also indicate that the vertex buffer will contain transformed vertices (the D3DFVF_XYZRHW flag is included in the dwFVF member of the description structure). The CreateVertexBuffer method ignores the D3DDP_DONOTCLIP flag if you indicate that the buffer will contain untransformed vertices (the D3DFVF_XYZ flag). Clipping flags occupy additional memory, making a clipping-capable vertex buffer slightly larger than a vertex buffer incapable of containing clipping flags. Because these resources are allocated when the vertex buffer is created, you must request a clipping-capable vertex buffer ahead of time.

Note  Creating a vertex buffer that can contain clip flags does not necessarily mean that you must request that clip flags be generated during vertex processing or applied during rendering. Each vertex buffer rendering method accepts the D3DDP_DONOTCLIP flag to bypass clipping during rendering, and the IDirect3DVertexBuffer::ProcessVertices method accepts the D3DVOP_CLIP flag, which can be omitted to prevent the system from generating clip flags while it processes vertices.

There is no way to produce clip flags for a vertex buffer that was created without support for them. Attempts to use the IDirect3DVertexBuffer::ProcessVertices method to do this will fail in debug builds, returning D3DERR_INVALIDVERTEXFORMAT. Rendering methods will ignore clipping requests when rendering from a transformed vertex buffer that does not contain clip flags.

The last parameter that CreateVertexBuffer accepts is provided for future compatibility with COM aggregation features. Currently, aggregation isn't supported, so this parameter must be set to NULL.

The following example shows what creating a vertex buffer might look like in code:

    /*
     * For the purposes of this example, the g_lpD3D variable is the 
     * address of an IDirect3D3 interface exposed by a Direct3D
     * object, and the fIsAHardwareDevice variable is a BOOL variable
     * that is assumed to be set during application initialization.
     */
 
    D3DVERTEXBUFFERDESC vbdesc;
    ZeroMemory(&vbdesc, sizeof(D3DVERTEXBUFFERDESC));
    vbdesc.dwSize        = sizeof(D3DVERTEXBUFFERDESC);
    vbdesc.dwCaps        = 0L;
    vbdesc.dwFVF         = D3DFVF_VERTEX;
    vbdesc.dwNumVertices = NUM_FLAG_VERTICES;
    
    // If this isn't a hardware device, make sure the 
    // vertex buffer uses system memory.
    if( !fIsAHardwareDevice )
        vbdesc.dwCaps |= D3DVBCAPS_SYSTEMMEMORY;
    
    // Create a clipping-capable vertex buffer.
    if(FAILED(g_lpD3D->CreateVertexBuffer(&vbdesc,
                                          &g_pvbVertexBuffer, 0L,
                                          NULL)))
        return E_FAIL;