IDirect3DDevice8::CreateIndexBuffer

This method creates an index buffer.

HRESULT CreateIndexBuffer(
  UINT Length,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DIndexBuffer8** ppIndexBuffer
);

Parameters

• Length
  [in] Size of the index buffer, in bytes.

• Usage
  [in] Combination of one or more of the following flags, describing the usage controls for this resource.

  Flag	Description
  D3DUSAGE_DONOTCLIP	Set to indicate that the index buffer content will never require clipping.
  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 only valid on vertex and index buffers created with D3DUSAGE_DYNAMIC; they are not valid flags on static vertex buffers. Note that D3DUSAGE_DYNAMIC cannot be specified on managed vertex and index buffers. For more information, see Managing Resources.
  D3DUSAGE_RTPATCHES	Not supported.
  D3DUSAGE_NPATCHES	Not supported.
  D3DUSAGE_POINTS	Set to indicate when the index buffer is to be used for drawing point sprites or indexed point lists.
  D3DUSAGE_SOFTWAREPROCESSING	Set to indicate that the buffer is to be used with software processing.
  D3DUSAGE_WRITEONLY	Informs the system that the application writes only to the index buffer. Using this flag enables the driver to select the best memory location for efficient write operations and rendering. Attempts to read from an index buffer that is created with this capability can result in degraded performance.

• Format
  [in] Member of the D3DFORMAT enumerated type, describing the format of the index buffer. The valid settings are shown in the following table.

  Setting	Description
  D3DFMT_INDEX16	Indices are 16 bits each.
  D3DFMT_INDEX32	Indices are 32 bits each.

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

• ppIndexBuffer
  [out, retval] Address of a pointer to an IDirect3DIndexBuffer8 interface, representing the created index 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:

• D3DERR_INVALIDCALL
• D3DERR_OUTOFVIDEOMEMORY
• D3DXERR_INVALIDDATA
• E_OUTOFMEMORY

Remarks

Index buffers are memory resources used to hold indices, they are similar to both surfaces and vertex buffers. The use of index buffers enables Microsoft® Direct3D® to avoid unnecessary data copying and to place the buffer in the optimal memory type for the expected usage.

To use index buffers, create an index buffer, lock it, fill it with indices, unlock it, pass it to IDirect3DDevice8::SetIndices, set up the vertices, set up the vertex shader, and call IDirect3DDevice8::DrawIndexedPrimitive for rendering.

The MaxVertexIndex member of the D3DCAPS8 structure indicates the types of index buffers that are valid for rendering.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: D3d8.h.
Link Library: D3d8.lib.

See Also

Managing Resources | D3DFORMAT | D3DPOOL | IDirect3DIndexBuffer8 | IDirect3DDevice8::SetIndices | IDirect3DIndexBuffer8::GetDesc | D3DCAPS8 | IDirect3DDevice8

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.