Direct3DDevice8.CreateVertexBuffer

Creates a vertex buffer.

object.CreateVertexBuffer( _ 
    LengthInBytes As Long, _ 
    Usage As Long, _ 
    FVF As Long, _ 
    Pool As CONST_D3DPOOL) As Direct3DVertexBuffer8

Parts

object

Object expression that resolves to a Direct3DDevice8 object.

LengthInBytes

Size of the vertex buffer, in bytes. For Flexible Vertex Format (FVF) 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 validated only for FVF buffers.

Usage

A combination of one or more of the following flags defined by the CONST_D3DUSAGEFLAGS enumeration, describing the usage controls for this resource.

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 0.

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 driver. 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 valid only 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_SOFTWAREPROCESSING

Set to indicate that the vertex buffer is to be used with software vertex processing.

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.

FVF

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 0 (zero), the vertex buffer is a non-FVF vertex buffer.

Pool

Member of the CONST_D3DPOOL enumeration, describing a valid memory class into which to place the resource.

Return Values

A Direct3DVertexBuffer8 object, representing the created vertex buffer resource.

Error Codes

If the method fails, an error is raised and Err.Number can be set to one of the following values.

For information on trapping errors, see the Microsoft® Visual Basic® Error Handling topic.

Remarks

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

When set to a nonzero 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.

The D3DUSAGE_SOFTWAREPROCESSING flag specifies that the vertex buffer is to be used with software vertex processing. For more information, see Device Types and Vertex Processing Requirements.

Non-FVF buffers can be used to interleave data during multipass rendering or multitexture rendering in a single pass. To do this, put geometry data in one buffer and texture coordinate data for each texture to be rendered in separate buffers. 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.

See Also

Direct3DVertexBuffer8.GetDesc, Direct3DDevice8.ProcessVertices