IDirect3DDevice3::Begin

The IDirect3DDevice3::Begin method indicates the start of a sequence of rendered primitives. This method defines the type of these primitives and the type of vertices on which they are based. The only method you can legally call between calls to IDirect3DDevice3::Begin and IDirect3DDevice3::End is IDirect3DDevice3::Vertex.

HRESULT Begin(
  D3DPRIMITIVETYPE d3dpt,  
  DWORD dwVertexTypeDesc,  
  DWORD dwFlags         
);
 

Parameters

d3dpt

One of the members of the D3DPRIMITIVETYPE enumerated type.

dwVertexTypeDesc

A combination of flexible vertex format flags that describe the vertex format used. Only vertices that match this description will be accepted before the corresponding IDirect3DDevice3::End.

dwFlags

One or more of the following flags defining how the primitive is drawn:

D3DDP_DONOTCLIP

The application has already done the required clipping, so the system should not necessarily clip the primitives. (This flag is a hint; the system may clip the primitive even when this flag is specified, under some circumstances.)

D3DDP_DONOTLIGHT

Disables the Direct3D lighting engine. The system uses the diffuse and specular components at each vertex for shading when it rasterizes the set of primitives. If a diffuse or specular component is not specified, the system uses the default color for the missing component (0xFFFFFFFF for diffuse and 0x00000000 for specular ).

D3DDP_DONOTUPDATEEXTENTS

Disables the updating of the screen rectangle affected by this rendering call. Using this flag can potentially help performance, but the extents returned by IDirect3DDevice3::GetClipStatus will not have been updated to account for the data rendered by this call.

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 is an error. The method returns DDERR_INVALIDPARAMS if one of the arguments is invalid.

Remarks

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.

This method fails if it is called after a call to the IDirect3DDevice3::Begin or IDirect3DDevice3::BeginIndexed method that has no bracketing call to IDirect3DDevice3::End method. Rendering calls that specify the wrong vertex type or that perform state changes will cause rendering of this primitive to fail.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in d3d.h.
  Import Library: Use ddraw.lib.

See Also

IDirect3DDevice3::BeginIndexed, IDirect3DDevice3::End, IDirect3DDevice3::Vertex