The DrawPrimitive Methods

[Previous] [Next]

You might be starting to get the impression that there are a lot of different cases to deal with when rendering primitives. You've seen that vertices can be stored in three ways: user arrays, strided vertices, and vertex buffers. And you've seen that Direct3D can render three kinds of primitives: points, lines, and triangles. Lines can be specified in two ways: line lists and line strips. Triangles can be specified in three ways: lists, strips, and fans. Finally, primitives can be indexed or nonindexed. That adds up to a lot of different ways to render primitives! The six DrawPrimitive methods of the IDirect3DDevice7 interface can handle all these cases. Table 6-1 shows that a different method exists for each combination of vertex type and indexing type.

Table 6-1 Methods for Rendering Primitives

Type of Primitive Normal User Vertex Strided User Vertices Vertices Buffer
NonindexedDrawPrimitiveDrawPrimitiveStridedDrawPrimitiveVB
IndexedDrawIndexedPrimitiveDrawIndexedPrimitiveStridedDrawIndexedPrimitiveVB

Let's take a closer look at each of these methods.

DrawPrimitive

The IDirect3DDevice7::DrawPrimitive method renders the array of vertices you provide as a sequence of geometric primitives of whichever type you specify. Here's the function declaration for this method:

 HRESULT IDirect3DDevice7::DrawPrimitive(     D3DPRIMITIVETYPE dptPrimitiveType,     DWORD dwVertexTypeDesc,     LPVOID lpvVertices,     DWORD dwVertexCount,     DWORD dwFlags );    

ParameterDescription
dptPrimitiveTypeThe type of primitive that this command will render. This primitive type must be one of the members of the D3DPRIMITIVETYPE enumerated type.
dwVertexTypeDescHolds a combination of the flexible vertex format flags that defines the vertex format this set of primitives will use.
lpvVerticesA pointer to the array of vertices to use in the primitive sequence.
dwVertexCountHolds the number of vertices to draw in the array. The maximum value you can specify here is D3DMAXNUMVERTICES (65,535).
dwFlagsSet this parameter to 0 to render the primitive without waiting, or set it to D3DDP_WAIT to cause the method to wait until the polygons have been rendered before it returns. By default, the method returns as soon as it sends the polygons to the video card.

Use the D3DDP_WAIT flag for debugging. Applications shouldn't use the D3DDP_WAIT flag to wait for a scene to be up-to-date before rendering.

DrawPrimitiveStrided

The IDirect3DDevice7::DrawPrimitiveStrided method is used to render an array of strided vertices as a sequence of geometric primitives. You need to verify that the vertices you want rendered use the format you specify. Because Direct3D doesn't check whether the vertex size and stride match the specified flexible vertex format, you need to make sure they do or a memory fault error will probably occur.

Here's the function declaration for this method:

 HRESULT DrawPrimitiveStrided(     D3DPRIMITIVETYPE dptPrimitiveType,       DWORD  dwVertexTypeDesc,                 LPD3DDRAWPRIMITIVESTRIDEDDATA lpVertexArray,       DWORD  dwVertexCount,                    DWORD  dwFlags                       ); 

ParameterDescription
dptPrimitiveTypeType of primitive to be rendered by this command. This parameter must be one of the members of the D3DPRIMITIVETYPE enumerated type.
dwVertexTypeDescA combination of flexible vertex format flags that describes the vertex format.
lpVertexArrayAddress of a D3DDRAWPRIMITIVESTRIDEDDATA structure that contains pointers and memory strides for the vertex components for this primitive, in the format specified by the flags in dwVertexTypeDesc.
dwVertexCountNumber of vertices in the array at lpVertexArray. The maximum number of vertices allowed is D3DMAXNUMVERTICES (0xFFFF).
dwFlagsSet to 0 to render the primitive without waiting, or use the D3DDP_WAIT flag, which 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.

DrawPrimitiveVB

The IDirect3DDevice7::DrawPrimitiveVB method is used to render an array of vertices in a vertex buffer as a sequence of geometric primitives. Here's the function declaration for this method:

 HRESULT DrawPrimitiveVB(      D3DPRIMITIVETYPE        d3dptPrimitiveType,     LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,     DWORD dwStartVertex,     DWORD dwNumVertices,     DWORD dwFlags ); 

ParameterDescription
dptPrimitiveTypeType of primitive to be rendered by this command. This parameter must be one of the members of the D3DPRIMITIVETYPE enumerated type.
lpd3dVertexBufferAddress of the IDirect3DVertexBuffer7 interface for the vertex buffer that contains the array of vertices. Vertices can be transformed or untransformed, optimized or unoptimized.
dwStartVertexIndex value of the first vertex in the primitive. The highest possible starting index is D3DMAXNUMVERTICES (0xFFFF). In debug builds, specifying a starting index value that exceeds this limit causes the method to fail and return DDERR_INVALIDPARAMS.
dwNumVerticesNumber of vertices to be rendered. The maximum number of vertices allowed is D3DMAXNUMVERTICES (0xFFFF).
dwFlagsSet to 0 to render the primitive without waiting, or use the D3DDP_WAIT flag, which 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.

DrawIndexedPrimitive

The IDirect3DDevice7::DrawIndexedPrimitive method is designed to render the geometric primitive you specify based on indexing into an array of vertices rather than on using an array of vertices directly. Here's the function declaration for this method:

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

ParameterDescription
d3dptPrimitiveTypeThe type of primitive that this command will render. (This primitive type must be one of the members of the D3DPRIMITIVETYPE enumerated type.) The D3DPT_POINTLIST member of D3DPRIMITIVETYPE isn't indexed, so you can't use it.
dwVertexTypeDescHolds a combination of the flexible vertex format flags that defines the vertex format this set of primitives will use.
lpvVerticesA pointer to an array of vertices you want to use in the primitive sequence.
dwVertexCountHolds the total number of vertices in the array the lpvVertices parameter points to.
lpwIndices A pointer to a list of WORDs used to index the vertex list when creating the geometry to render.
dwIndexCount Used to define the number of indices provided for creating the geometry. The maximum value you can use here is D3DMAXNUMVERTICES (65,535).
dwFlagsSet this parameter to 0 to render the primitive without waiting, or set it to D3DDP_WAIT to cause the method to wait until the polygons have been rendered before it returns. By default, the method returns as soon as it sends the polygons to the video card.

Use the D3DDP_WAIT flag for debugging. Applications shouldn't use the D3DDP_WAIT flag to wait for a scene to be up-to-date before rendering.

DrawIndexedPrimitiveStrided

The IDirect3DDevice7::DrawIndexedPrimitiveStrided method allows you to render a geometric primitive, based on indexing into an array of strided vertices. Here's the function declaration for this method:

 HRESULT DrawIndexedPrimitiveStrided(     D3DPRIMITIVETYPE d3dptPrimitiveType,       DWORD  dwVertexTypeDesc,                   LPD3DDRAWPRIMITIVESTRIDEDDATA lpVertexArray,       DWORD  dwVertexCount,                      LPWORD lpwIndices,                         DWORD  dwIndexCount,                       DWORD  dwFlags                         ); 

ParameterDescription
d3dptPrimitiveTypeType of primitive to be rendered by this command. This parameter must be one of the members of the D3DPRIMITIVETYPE enumerated type. The D3DPT_POINTLIST member of D3DPRIMITIVETYPE is not indexed.
dwVertexTypeDescA combination of flexible vertex format flags that describes the vertex format for this primitive.
lpVertexArrayAddress of a D3DDRAWPRIMITIVESTRIDEDDATA structure that contains pointers and memory strides for the vertex components of this primitive, in the format specified by the flags in dwVertexTypeDesc.
dwVertexCountDefines 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 lpVertexArray parameter. When you call IDirect3DDevice7::DrawIndexedPrimitiveStrided , you specify the number of vertices to draw in the dwIndexCount parameter.
lpwIndicesPointer to a list of WORDs that are to be used to index into the specified vertex list when creating the geometry to render.
dwIndexCountSpecifies the number of indices provided for creating the geometry. The maximum number of indices allowed is D3DMAXNUMVERTICES (0xFFFF).
dwFlagsSet to 0 to render the primitive without waiting, or use the D3DDP_WAIT flag, which 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.

DrawIndexedPrimitiveVB

The IDirect3DDevice7::DrawIndexedPrimitiveVB method is used to render a geometric primitive using indexing into an array of vertices within a vertex buffer. Here's the function declaration for this method:

 HRESULT DrawIndexedPrimitiveVB(     D3DPRIMITIVETYPE        d3dptPrimitiveType,     LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,     DWORD  dwStartVertex,     DWORD  dwNumVertices,     LPWORD lpwIndices,     DWORD  dwIndexCount,     DWORD  dwFlags ); 

ParameterDescription
d3dptPrimitiveTypeThe type of primitive to be rendered by this command. This parameter must be one of the members of the D3DPRIMITIVETYPE enumerated type. The D3DPT_POINTLIST member of D3DPRIMITIVETYPE is not indexed.
lpd3dVertexBufferThe address of the IDirect3DVertexBuffer7 interface for the vertex buffer that contains the array of vertices. Vertices can be transformed or untransformed, optimized or unoptimized.
dwStartVertexIndex of the first vertex in the vertex buffer to be rendered.
dwNumVerticesTotal number of vertices in the vertex buffer to be rendered.
lpwIndicesThe address of an array of WORDs that is used to index into the vertices in the vertex buffer. The values in the array must index vertices within the range [0, dwNumVertices - 1].
dwIndexCountThe number of indices in the array at lpwIndices. The maximum number of indices allowed is D3DMAXNUMVERTICES (0xFFFF).
dwFlagsSet to 0 to render the primitive without waiting, or use the D3DDP_WAIT flag, which 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.



Inside Direct3D
Inside Direct3D (Dv-Mps Inside)
ISBN: 0735606137
EAN: 2147483647
Year: 1999
Pages: 131

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net