IDirect3DDevice7::DrawIndexedPrimitive

The IDirect3DDevice7::DrawIndexedPrimitive method renders the specified geometric primitive, based on indexing into an array of vertices.

HRESULT DrawIndexedPrimitive(
  D3DPRIMITIVETYPE d3dptPrimitiveType,  
  DWORD  dwVertexTypeDesc,              
  LPVOID lpvVertices,                   
  DWORD  dwVertexCount,                 
  LPWORD lpwIndices,                    
  DWORD  dwIndexCount,                  
  DWORD  dwFlags                        
);

Parameters

d3dptPrimitiveType

Type of primitive to be rendered by this command. This must be one of the members of the D3DPRIMITIVETYPE enumerated type.

The D3DPT_POINTLIST member of D3DPRIMITIVETYPE is not indexed.

dwVertexTypeDesc

A combination of flexible vertex format flags that describes the vertex format for this set of primitives.

lpvVertices

Pointer to the list of vertices to be used in the primitive sequence.

dwVertexCount

Defines the number of vertices in the list.

This parameter is used differently from the dwVertexCount parameter in the IDirect3DDevice7::DrawPrimitive method. In that method, the dwVertexCount parameter gives the number of vertices to draw, but here it gives the total number of vertices in the array pointed to by the lpvVertices parameter. When you call IDirect3DDevice7::DrawIndexedPrimitive, you specify the number of vertices to draw in the dwIndexCount parameter.

lpwIndices

Pointer to a list of WORDs that are to be used to index into the specified vertex list when creating the geometry to render.

dwIndexCount

Specifies the number of indices provided for creating the geometry. The maximum number of indices allowed is D3DMAXNUMVERTICES (0xFFFF).

dwFlags

Zero to render the primitive without waiting, or the following flag:

D3DDP_WAIT

Causes the method to wait until the polygons have been rendered before it returns, instead of returning as soon as the polygons have been sent to the card. (On scene-capture cards, the method returns as soon as the card responds.) This flag is typically used for debugging. Applications should not attempt to use this flag to ensure that a scene is up to date before continuing.

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

Make sure that the vertices being rendered match the vertex format that you specify. For performance reasons, Direct3D does not attempt to verify that vertex size and stride match the provided flexible vertex format. If a mismatch occurs, a memory fault is likely to result.

This method should not be used when rendering from a vertex buffer, use a vertex buffer method instead.

This method, unlike its predecessor in previous interfaces, does not accept the D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, and D3DDP_DONOTUPDATEEXTENTS flags in the dwFlags parameter. The functionality offered by these flags is now available through the D3DRENDERSTATE_CLIPPING, D3DRENDERSTATE_LIGHTING, and D3DRENDERSTATE_EXTENTS render states.

Do not use this method to render very small subsets of vertices from extremely large vertex arrays. This method transforms every vertex in the provided buffer, regardless of the location or number of vertices being rendered. Thus, if you pass an array that contains thousands of vertices, but only intend to render hundreds, your application's performance suffers dramatically. If you need to render a small number of vertices from a large buffer, use the Direct3D vertex buffer rendering methods. For more information, see Vertex Buffers.

This method differs from its counterpart in the IDirect3DDevice2 interface in that it accepts a flexible vertex format descriptor, rather than a member of the D3DVERTEXTYPE enumerated type as the second parameter. If you attempt to use one of the members of D3DVERTEXTYPE, the method fails, returning DDERR_INVALIDPARAMS. For more information, see Vertex Formats.

In current versions of DirectX, IDirect3DDevice7::DrawIndexedPrimitive can sometimes generate an update rectangle that is larger than it needs to be. If a large number of vertices need to be processed, this can have a negative impact on the performance of your application. If you are using D3DTLVERTEX vertices and the system is processing more vertices than you need, use the D3DDP_DONOTCLIP and D3DDP_DONOTUPDATEEXTENTS flags to solve the problem.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Version: Requires DirectX 7.0.
  Header: Declared in d3d.h.

See Also

IDirect3DDevice7::DrawPrimitive, IDirect3DDevice7::DrawPrimitiveStrided, IDirect3DDevice7::DrawPrimitiveVB, IDirect3DDevice7::DrawIndexedPrimitiveStrided, IDirect3DDevice7::DrawIndexedPrimitiveVB