IDirect3DMobileDevice::CreateIndexBuffer

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method creates an index buffer.

Syntax

HRESULT CreateIndexBuffer(
  UINT Length,
  DWORD Usage,
  D3DMFORMAT Format,
  D3DMPOOL Pool,
  IDirect3DMobileIndexBuffer** ppIndexBuffer
);

Parameters

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

• Usage
  [in] Combination of one or more of the following flags, from the D3DMUSAGE Values, that describes the usage controls for this resource.

  Flag	Description
  D3DMUSAGE_DONOTCLIP	Set to indicate that the index buffer content will never require clipping.
  D3DMUSAGE_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 D3DMUSAGE_DYNAMIC the vertex buffer is made static. D3DMUSAGE_DYNAMIC is strictly enforced through the D3DMLOCK_DISCARD and D3DMLOCK_NOOVERWRITE locking flags (see D3DMLOCK Values). As a result, D3DMLOCK_DISCARD and D3DMLOCK_NOOVERWRITE are only valid on vertex and index buffers created with D3DMUSAGE_DYNAMIC; they are not valid flags on static vertex buffers. Note that D3DMUSAGE_DYNAMIC cannot be specified on managed vertex and index buffers.
  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 D3DMFORMAT enumerated type, describing the format of the index buffer. The valid settings are shown in the following table.

  Setting	Description
  D3DMFMT_INDEX16	Indices are 16 bits each.
  D3DMFMT_INDEX32	Indices are 32 bits each.

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

• ppIndexBuffer
  [out] Address of a pointer to an IDirect3DMobileIndexBuffer interface that represents the created index buffer resource.

Return Value

If the method succeeds, the return value is D3DM_OK (see D3DM Values).

If the method fails, the return value can be E_OUTOFMEMORY, or one of the following D3DMERR Values.

• D3DMERR_MEMORYPOOLEMPTY
• D3DMERR_INVALIDCAL

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 Mobile® 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 IDirect3DMobileDevice::SetIndices, set up the vertices, set up the vertex shader, and call IDirect3DMobileDevice::DrawIndexedPrimitive for rendering.

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

Requirements

See Also

Reference

IDirect3DMobileDevice
D3DMUSAGE Values
D3DMLOCK Values
D3DMFORMAT
D3DMPOOL
IDirect3DMobileIndexBuffer
IDirect3DMobileDevice::SetIndices
IDirect3DMobileDevice::DrawIndexedPrimitive
D3DMCAPS