Execute Buffers

In the past, all programming with Direct3D Immediate Mode was done using execute buffers. Now that the DrawPrimitive methods have been introduced, however, most new Immediate-Mode programs will not use execute buffers or the IDirect3DExecuteBuffer interface. For more information about the DrawPrimitive methods, see The DrawPrimitive Methods.

Execute buffers are similar to the display lists you may be familiar with if you have experience with OpenGL programming. Execute buffers contain a vertex list followed by an instruction stream. The instruction stream consists of operation codes, or opcodes, and the data that modifies those opcodes. Each execute buffer is bound to a single Direct3D device.

You can create an IDirect3DExecuteBuffer interface by calling the IDirect3DDevice::CreateExecuteBuffer method.

lpD3DDevice->CreateExecuteBuffer( 
    lpDesc,       // Address of a DIRECT3DEXECUTEBUFFERDESC structure 
    lplpDirect3DExecuteBuffer,  // Address to contain a pointer to the 
                                // Direct3DExecuteBuffer object 
    pUnkOuter);   // NULL 
 

Execute-buffers reside on a device list. You can use the IDirect3DDevice::CreateExecuteBuffer method to allocate space for the actual buffer, which may be on the hardware device.

The buffer is filled with two contiguous arrays of vertices and opcodes by using the following calls to the IDirect3DExecuteBuffer::Lock, IDirect3DExecuteBuffer::Unlock, and IDirect3DExecuteBuffer::SetExecuteData methods:

lpD3DExBuf->Lock( 
    lpDesc);.      // Address of a DIRECT3DEXECUTEBUFFERDESC structure 
//  . 
//  .  Store contents through the supplied address 
//  . 
lpD3DExBuf->Unlock(); 
lpD3DExBuf->SetExecuteData( 
    lpData);       // Address of a D3DEXECUTEDATA structure 
 

The last call in the preceding example is to the IDirect3DExecuteBuffer::SetExecuteData method. This method notifies Direct3D where the two parts of the buffer reside relative to the address that was returned by the call to the IDirect3DExecuteBuffer::Lock method.

You can use the IDirect3DExecuteBuffer interface to get and set execute data, and to lock, unlock, optimize, and validate the execute buffer.