IDirect3DDevice8::CreateVertexBuffer

Creates a vertex buffer.

HRESULT CreateVertexBuffer(
  UINT Length,
  DWORD Usage,
  DWORD FVF,
  D3DPOOL Pool,
  IDirect3DVertexBuffer8** ppVertexBuffer
);

Parameters

Length

[in] Size of the vertex buffer, in bytes. For flexible vertex format (FVF) vertex buffers, Length must be large enough to contain at least one vertex, but it need not be a multiple of the vertex size. Length is not validated for nonFVF buffers. See Remarks.

Usage

[in] A combination of one or more of the following flags, describing the type of data and whether the vertex buffer is processed by hardware or software.

Value	Description
D3DUSAGE_SOFTWAREPROCESSING	If this flag is used, vertex processing is done in software. If this flag is not used, vertex processing is done in hardware.
D3DUSAGE_DONOTCLIP	Set to indicate that the vertex buffer content will never require clipping. When rendering with buffers that have this flag set, the D3DRS_CLIPPING renderstate must be set to false.
D3DUSAGE_DYNAMIC	Set to indicate when the vertex or index buffer requires dynamic memory usage. This usage is useful for drivers because it enables them to decide where to place the buffer. In general, static vertex buffers will be placed in video memory and dynamic vertex buffers will be placed in AGP memory. Note that there is no separate static usage; if you do not specify D3DUSAGE_DYNAMIC the vertex buffer is made static. D3DUSAGE_DYNAMIC is strictly enforced through the D3DLOCK_DISCARD and D3DLOCK_NOOVERWRITE locking flags. As a result, D3DLOCK_DISCARD and D3DLOCK_NOOVERWRITE are only valid on vertex and index buffers created with D3DUSAGE_DYNAMIC; they are not valid flags on static vertex buffers. For more information about using dynamic vertex buffers, see Using Dynamic Vertex and Index Buffers. Note that D3DUSAGE_DYNAMIC cannot be specified on managed vertex and index buffers. For more information, see Managing Resources.
D3DUSAGE_RTPATCHES	Set to indicate when the vertex buffer is to be used for drawing high-order primitives.
D3DUSAGE_NPATCHES	Set to indicate when the vertex buffer is to be used for drawing N patches.
D3DUSAGE_POINTS	Set to indicate when the vertex buffer is to be used for drawing point sprites or indexed point lists.
D3DUSAGE_WRITEONLY	Informs the system that the application writes only to the vertex buffer. Using this flag enables the driver to choose the best memory location for efficient write operations and rendering. Attempts to read from a vertex buffer that is created with this capability will fail.

It is good practice to match the usage parameter in CreateVertexShader with the behavior flags in CreateDevice. See the Remarks section for more information.

FVF

[in] Combination of Flexible Vertex Format Flags, a usage specifier that describes the vertex format of the vertices in this buffer. When this parameter is set to a valid FVF code, the created vertex buffer is an FVF vertex buffer (see Remarks); otherwise, when this parameter is set to zero, the vertex buffer is a non-FVF vertex buffer.

Pool

[in] Member of the D3DPOOL enumerated type, describing a valid memory class into which to place the resource.

ppVertexBuffer

[out,retval] Address of a pointer to an IDirect3DVertexBuffer8 interface, representing the created vertex buffer resource.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values.

Remarks

A vertex buffer can be used with either hardware or software vertex processing. This is determined by how the device and the vertex buffer are created.

When a device is created, CreateDevice uses the behavior flag to determine whether to process vertices in hardware or software. There are three possibilities:

• Process vertices in hardware by setting D3DCREATE_HARDWARE_VERTEXPROCESSING.
• Process vertices in software by setting D3DCREATE_SOFTWARE_VERTEXPROCESSING.
• Process vertices in either hardware or software by setting D3DCREATE_MIXED_VERTEXPROCESSING.

  Mixed mode devices may need to switch between software and hardware processing after the device is created. In this case, set the D3DRS_SOFTWAREVERTEXPROCESSING render state using SetRenderState.

When a vertex buffer is created, CreateVertexBuffer uses the usage parameter to decide whether to process vertices in hardware or software.

• If CreateDevice uses D3DCREATE_HARDEWARE_VERTEXPROCESSING, CreateVertexBuffer must use 0.
• Else if CreateDevice uses D3DCREATE_SOFTWARE_VERTEXPROCESSING, CreateVertexBuffer must use either 0 or D3DUSAGE_SOFTWAREPROCESSING. For either value, vertices will be processed in software.
• Else If CreateDevice uses D3DCREATE_MIXED_VERTEXPROCESSING CreateVertexBuffer can use either 0 or D3DUSAGE_SOFTWAREPROCESSING.

  To use a vertex buffer with a mixed mode device, create a single vertex buffer which can be used for both hardware or software processing. Use SetStreamSource to set the current vertex buffer and use SetRenderState, if necessary, to change the device behavior to match. It is recommended that the vertex buffer usage matches the device behavior. Note: a vertex buffer created for software processing cannot be located in video memory.

The IDirect3DDevice8 interface supports rendering of primitives using vertex data stored in vertex buffer objects. Vertex buffers are created from the IDirect3DDevice8 interface, and are usable only with the IDirect3DDevice8 object from which they are created.

When set to a non-zero value, which must be a valid FVF code, the FVF parameter indicates that the buffer content is to be characterized by an FVF code. A vertex buffer that is created with an FVF code is referred to as an FVF vertex buffer. For more information, see FVF Vertex Buffers.

Non-FVF buffers can be used to interleave data during multipass rendering or multitexture rendering in a single pass. To do this, one buffer contains geometry data and the others contain texture coordinates for each texture to be rendered. When rendering, the buffer containing the geometry data is interleaved with each of the buffers containing the texture coordinates. If FVF buffers were used instead, each of them would need to contain identical geometry data in addition to the texture coordinate data specific to each texture rendered. This would result in either a speed or memory penalty, depending on the strategy used. For more information on texture coordinates, see Texture Coordinates.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.

See Also

IDirect3DVertexBuffer8::GetDesc, IDirect3DDevice8::ProcessVertices