IDirect3DDevice8::CreateVertexShader

Creates a vertex shader.

HRESULT CreateVertexShader(
  CONST DWORD* pDeclaration,
  CONST DWORD* pFunction,
  DWORD* pHandle,
  DWORD Usage
);

Parameters

pDeclaration

[in] Pointer to the vertex shader declaration token array. This parameter defines the inputs to the shader, including how the vertex elements within the input data streams are used by the shader.

pFunction

[in] Pointer to the vertex shader function token array. This parameter defines the operations to apply to each vertex. If this parameter is set to NULL, a shader is created for the fixed-function pipeline. Otherwise, the shader is programmable.

pHandle

[out] Pointer to the returned vertex shader handle. This value cannot be set as NULL.

Usage

[in] Usage controls whether vertices are processed by hardware or software.

Value	Description
0	Vertex processing is done in hardware.
D3DUSAGE_SOFTWAREPROCESSING	Vertex processing is done in software.

It is good practice to match the usage parameter in CreateVertexShader with the behavior flags in CreateDevice. See the Remarks section for more information.

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

A vertex shader can be used with either hardware or software vertex processing. This is determined by how the device and the vertex shader are created.

When a device is created, CreateDevice uses the behavior flag to determine whether to process vertices in hardware or software. There are three possibilities:

• Process vertices in hardware by setting D3DCREATE_HARDWARE_VERTEXPROCESSING.
• Process vertices in software by setting D3DCREATE_SOFTWARE_VERTEXPROCESSING.
• Process vertices in either hardware or software by setting D3DCREATE_MIXED_VERTEXPROCESSING.

  Mixed-mode devices may need to switch between software and hardware processing after the device is created. In this case, set the D3DRS_SOFTWAREVERTEXPROCESSING render state using SetRenderState.

When a vertex shader is created, CreateVertexShader uses the usage parameter to decide whether to process vertices in hardware or software.

• If CreateDevice uses D3DCREATE_HARDEWARE_VERTEXPROCESSING, CreateVertexShader must use 0.
• Else if CreateDevice uses D3DCREATE_SOFTWARE_VERTEXPROCESSING, CreateVertexShader must use D3DUSAGE_SOFTWAREPROCESSING.
• Else if CreateDevice uses D3DCREATE_MIXED_VERTEXPROCESSING CreateVertexShader can use either 0 or D3DUSAGE_SOFTWAREPROCESSING.

  To use a vertex shader with a mixed-mode device, create separate shaders for hardware and software processing. Use SetVertexShader to set the current shader and use SetRenderState, if necessary, to change the device behavior to match. It is recommended that the shader usage matches the device behavior.

A vertex shader is defined by two token arrays that specify the declaration and function of the shader. The token arrays are composed of single or multiple DWORD tokens terminated by a special 0xFFFFFFFF token value.

The shader declaration defines the static external interface of the shader, including binding of stream data to vertex register inputs and values loaded into the shader constant memory. The shader function defines the operation of the shader as an array of instructions that are executed in order for each vertex processed during the time the shader is bound to a device. Shaders created without a function array apply the fixed function vertex processing when that shader is current.

See D3d8types.h for a definition of the macros used to generate the declaration token array.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.

See Also

DeleteVertexShader, D3DXAssembleShader, D3DXAssembleShaderFromFile, D3DXDeclaratorFromFVF, CreateDevice.