Loading Vertex Shaders

Moving on in the list of helper functions, you'll find load_vertex_shader. You'll use this function to help you load your vertex shaders, as well as prepare your vertex shader declarations.

The actual code to the load_vertex_shader function is short, so instead of breaking it up to explain it, I'll give it to you all at once.

 

After first checking to make sure the parameters you have passed to the load_vertex_shader function are valid, execution continues by loading and assembling the vertex shader via a call to D3DXAssembleShaderFromFile.

Assemble a shader.

HRESULT D3DXAssembleShaderFromFile(
  LPCTSTR pSrcFile,
  CONST D3DXMACRO* pDefines,
  LPD3DXINCLUDE pInclude,
  DWORD Flags,
  LPD3DXBUFFER* ppShader,
  LPD3DXBUFFER * ppErrorMsgs
);

Parameters

pSrcFile

[in] Pointer to a string that specifies the filename. If the compiler settings require Unicode, the data type LPCTSTR resolves to LPCWSTR. Otherwise, the string data type resolves to LPCSTR. See Remarks.

pDefines

[in] An optional NULL terminated array of D3DXMACRO structures. This value may be NULL.

pInclude

[in] Optional interface pointer, ID3DXInclude, to use for handling #include directives. If this value is NULL, #includes will either be honored when compiling from a file or will cause an error when compiled from a resource or memory.

Flags

[in] Compile options identified by various flags. The Direct3D 10 HLSL compiler is now the default. See D3DXSHADER Flags for details.

ppShader

[out] Returns a buffer containing the created shader. This buffer contains the compiled shader code, as well as any embedded debug and symbol table information.

ppErrorMsgs

[out] Returns a buffer containing a listing of errors and warnings that were encountered during the compile. These are the same messages the debugger displays when running in debug mode. This value may be NULL.

Return Values

If the function succeeds, the return value is D3D_OK. If the function fails, the return value can be one of the following: D3DERR_INVALIDCALL, D3DXERR_INVALIDDATA, E_OUTOFMEMORY.

Remarks

The compiler setting also determines the function version. If Unicode is defined, the function call resolves to D3DXAssembleShaderFromFileW. Otherwise, the function call resolves to D3DXAssembleShaderFromFileA because ANSI strings are being used.

Using the D3DXBUFFER object returned from that function call, you then use the IDirect3DDevice::CreateVertexShader function to create your vertex shader object.

Finishing up load_vertex_shader, you'll see the call to CreateVertexDeclaration, which you use to create an IDirect3DVertexDeclaration9 interface from the supplied array of vertex elements (vertex_elements in the load_vertex_shader prototype). The vertex declaration object pointer is then stored in the ret_vertex_decl pointer you provide.

To use load_vertex_shader, pass it a pointer to an IDirect3DVertexShader9 object you want to create, along with a valid IDirect3DDevice9 object and file name of the vertex shader file. The last two parameters (vertex_elements and ret_vertex_decl) are optional. By passing a valid D3DVERTEXELEMENT9 array and the IDirect3DVertexDeclaration9 object pointer, you can prepare your vertex declarations for use with the vertex shader being loaded.

Let us see the define of D3DVERTEXELEMENT9:

Defines the vertex data layout. Each vertex can contain one or more data types, and each data type is described by a vertex element.

typedef struct D3DVERTEXELEMENT9 {
    WORD Stream;
    WORD Offset;
    BYTE Type;
    BYTE Method;
    BYTE Usage;
    BYTE UsageIndex;
} D3DVERTEXELEMENT9, *LPD3DVERTEXELEMENT9;

Members

Stream

Stream number.

Offset

Offset from the beginning of the vertex data to the data associated with the particular data type.

Type

The data type, specified as a D3DDECLTYPE. One of several predefined types that define the data size. Some methods have an implied type.

Method

The method specifies the tessellator processing, which determines how the tessellator interprets (or operates on) the vertex data. For more information, see D3DDECLMETHOD.

Usage

Defines what the data will be used for; that is, the interoperability between vertex data layouts and vertex shaders. Each usage acts to bind a vertex declaration to a vertex shader. In some cases, they have a special interpretation. For example, an element that specifies D3DDECLUSAGE_NORMAL or D3DDECLUSAGE_POSITION is used by the N-patch tessellator to set up tessellation. See D3DDECLUSAGE for a list of the available semantics. D3DDECLUSAGE_TEXCOORD can be used for user-defined fields (which don't have an existing usage defined).

UsageIndex

Modifies the usage data to allow the user to specify multiple usage types.

Remarks

Vertex data is defined using an array of D3DVERTEXELEMENT9 structures. Use D3DDECL_END to declare the last element in the declaration.

Defines a vertex declaration data type.

typedef enum D3DDECLTYPE
{
    D3DDECLTYPE_FLOAT1 = 0,
    D3DDECLTYPE_FLOAT2 = 1,
    D3DDECLTYPE_FLOAT3 = 2,
    D3DDECLTYPE_FLOAT4 = 3,
    D3DDECLTYPE_D3DCOLOR = 4,
    D3DDECLTYPE_UBYTE4 = 5,
    D3DDECLTYPE_SHORT2 = 6,
    D3DDECLTYPE_SHORT4 = 7,
    D3DDECLTYPE_UBYTE4N = 8,
    D3DDECLTYPE_SHORT2N = 9,
    D3DDECLTYPE_SHORT4N = 10,
    D3DDECLTYPE_USHORT2N = 11,
    D3DDECLTYPE_USHORT4N = 12,
    D3DDECLTYPE_UDEC3 = 13,
    D3DDECLTYPE_DEC3N = 14,
    D3DDECLTYPE_FLOAT16_2 = 15,
    D3DDECLTYPE_FLOAT16_4 = 16,
    D3DDECLTYPE_UNUSED = 17,
} D3DDECLTYPE, *LPD3DDECLTYPE;

Constants

D3DDECLTYPE_FLOAT1

One-component float expanded to (float, 0, 0, 1).

D3DDECLTYPE_FLOAT2

Two-component float expanded to (float, float, 0, 1).

D3DDECLTYPE_FLOAT3

Three-component float expanded to (float, float, float, 1).

D3DDECLTYPE_FLOAT4

Four-component float expanded to (float, float, float, float).

D3DDECLTYPE_D3DCOLOR

Four-component, packed, unsigned bytes mapped to 0 to 1 range. Input is a D3DCOLOR and is expanded to RGBA order.

D3DDECLTYPE_UBYTE4

Four-component, unsigned byte.

D3DDECLTYPE_SHORT2

Two-component, signed short expanded to (value, value, 0, 1).

D3DDECLTYPE_SHORT4

Four-component, signed short expanded to (value, value, value, value).

D3DDECLTYPE_UBYTE4N

Four-component byte with each byte normalized by dividing with 255.0f.

D3DDECLTYPE_SHORT2N

Normalized, two-component, signed short, expanded to (first short/32767.0, second short/32767.0, 0, 1).

D3DDECLTYPE_SHORT4N

Normalized, four-component, signed short, expanded to (first short/32767.0, second short/32767.0, third short/32767.0, fourth short/32767.0).

D3DDECLTYPE_USHORT2N

Normalized, two-component, unsigned short, expanded to (first short/65535.0, short short/65535.0, 0, 1).

D3DDECLTYPE_USHORT4N

Normalized, four-component, unsigned short, expanded to (first short/65535.0, second short/65535.0, third short/65535.0, fourth short/65535.0).

D3DDECLTYPE_UDEC3

Three-component, unsigned, 10 10 10 format expanded to (value, value, value, 1).

D3DDECLTYPE_DEC3N

Three-component, signed, 10 10 10 format normalized and expanded to (v[0]/511.0, v[1]/511.0, v[2]/511.0, 1).

D3DDECLTYPE_FLOAT16_2

Two-component, 16-bit, floating point expanded to (value, value, 0, 1).

D3DDECLTYPE_FLOAT16_4

Four-component, 16-bit, floating point expanded to (value, value, value, value).

D3DDECLTYPE_UNUSED

Type field in the declaration is unused. This is designed for use with D3DDECLMETHOD_UV and D3DDECLMETHOD_LOOKUPPRESAMPLED.

Remarks

Vertex data is declared with an array of D3DVERTEXELEMENT9 structures. Each element in the array contains a vertex declaration data type.

Use the DirectX Caps Viewer Tool tool to see which types are supported on your device.

Identifies the intended use of vertex data.

typedef enum D3DDECLUSAGE
{
    D3DDECLUSAGE_POSITION = 0,
    D3DDECLUSAGE_BLENDWEIGHT = 1,
    D3DDECLUSAGE_BLENDINDICES = 2,
    D3DDECLUSAGE_NORMAL = 3,
    D3DDECLUSAGE_PSIZE = 4,
    D3DDECLUSAGE_TEXCOORD = 5,
    D3DDECLUSAGE_TANGENT = 6,
    D3DDECLUSAGE_BINORMAL = 7,
    D3DDECLUSAGE_TESSFACTOR = 8,
    D3DDECLUSAGE_POSITIONT = 9,
    D3DDECLUSAGE_COLOR = 10,
    D3DDECLUSAGE_FOG = 11,
    D3DDECLUSAGE_DEPTH = 12,
    D3DDECLUSAGE_SAMPLE = 13,
} D3DDECLUSAGE, *LPD3DDECLUSAGE;

Constants

D3DDECLUSAGE_POSITION

Position data ranging from (-1,-1) to (1,1). Use D3DDECLUSAGE_POSITION with a usage index of 0 to specify untransformed position for fixed function vertex processing and the n-patch tessellator. Use D3DDECLUSAGE_POSITION with a usage index of 1 to specify untransformed position in the fixed function vertex shader for vertex tweening.

D3DDECLUSAGE_BLENDWEIGHT

Blending weight data. Use D3DDECLUSAGE_BLENDWEIGHT with a usage index of 0 to specify the blend weights used in indexed and nonindexed vertex blending.

D3DDECLUSAGE_BLENDINDICES

Blending indices data. Use D3DDECLUSAGE_BLENDINDICES with a usage index of 0 to specify matrix indices for indexed paletted skinning.

D3DDECLUSAGE_NORMAL

Vertex normal data. Use D3DDECLUSAGE_NORMAL with a usage index of 0 to specify vertex normals for fixed function vertex processing and the n-patch tessellator. Use D3DDECLUSAGE_NORMAL with a usage index of 1 to specify vertex normals for fixed function vertex processing for vertex tweening.

D3DDECLUSAGE_PSIZE

Point size data. Use D3DDECLUSAGE_PSIZE with a usage index of 0 to specify the point-size attribute used by the setup engine of the rasterizer to expand a point into a quad for the point-sprite functionality.

D3DDECLUSAGE_TEXCOORD

Texture coordinate data. Use D3DDECLUSAGE_TEXCOORD, n to specify texture coordinates in fixed function vertex processing and in pixel shaders prior to ps_3_0. These can be used to pass user defined data.

D3DDECLUSAGE_TANGENT

Vertex tangent data.

D3DDECLUSAGE_BINORMAL

Vertex binormal data.

D3DDECLUSAGE_TESSFACTOR

Single positive floating point value. Use D3DDECLUSAGE_TESSFACTOR with a usage index of 0 to specify a tessellation factor used in the tessellation unit to control the rate of tessellation. For more information about the data type, see D3DDECLTYPE_FLOAT1.

D3DDECLUSAGE_POSITIONT

Vertex data contains transformed position data ranging from (0,0) to (viewport width, viewport height). Use D3DDECLUSAGE_POSITIONT with a usage index of 0 to specify transformed position. When a declaration containing this is set, the pipeline does not perform vertex processing.

D3DDECLUSAGE_COLOR

Vertex data contains diffuse or specular color. Use D3DDECLUSAGE_COLOR with a usage index of 0 to specify the diffuse color in the fixed function vertex shader and pixel shaders prior to ps_3_0. Use D3DDECLUSAGE_COLOR with a usage index of 1 to specify the specular color in the fixed function vertex shader and pixel shaders prior to ps_3_0.

D3DDECLUSAGE_FOG

Vertex data contains fog data. Use D3DDECLUSAGE_FOG with a usage index of 0 to specify a fog blend value used after pixel shading finishes. This applies to pixel shaders prior to version ps_3_0.

D3DDECLUSAGE_DEPTH

Vertex data contains depth data.

D3DDECLUSAGE_SAMPLE

Vertex data contains sampler data. Use D3DDECLUSAGE_SAMPLE with a usage index of 0 to specify the displacement value to look up. It can be used only with D3DDECLUSAGE_LOOKUPPRESAMPLED or D3DDECLUSAGE_LOOKUP.

Remarks

Vertex data is declared with an array of D3DVERTEXELEMENT9 structures. Each element in the array contains a usage type.

For more information about vertex declarations, see Vertex Declaration (Direct3D 9).

Here's a small example of using load_vertex_shader. First, I declare an array of vertex elements that are used to create the vertex declaration object.

// Declare the vertex shader declaration elements
D3DVERTEXELEMENT9 Elements[] =
{
{ 0, 0, D3DDECLTYPE_FLOAT3, D3DDECLMETHOD_DEFAULT, D3DDECLUSAGE_POSITION, 0 },
{ 0, 12, D3DDECLTYPE_FLOAT3, D3DDECLMETHOD_DEFAULT, D3DDECLUSAGE_NORMAL, 0 },
{ 0, 24, D3DDECLTYPE_FLOAT2, D3DDECLMETHOD_DEFAULT, D3DDECLUSAGE_TEXCOORD, 0 },
D3DDECL_END()
};

Then I instance the vertex shader and vertex declaration objects and call load_vertex_shader.

// Instance objects
IDirect3DVertexShader9 *pShader = NULL;
IDirect3DVertexDeclaration9 *pDecl = NULL;

// Load the vertex shader and create declaration interface
load_vertex_shader(&pShader, pDevice, "Shader.vsh", &Elements, &pDecl);

As you can see, it's a quick and simple function that gets the job done. From here on out, you can set the vertex shader (represented by pShader) using the IDirect3DDevice9::SetVertexShader function. To set the vertex declaration (represented by pDecl), you would call IDirect3DDevice9::SetVertexDeclaration.

pD3DDevice−>SetFVF(NULL); // Clear FVF usages
pD3DDevice−>SetVertexShader(pShader);
pD3DDevice−>SetVertexDeclaration(pDecl);

Okay, enough of initializing and loading vertex shaders, let's move on to the cool stuff, like loading and rendering meshes.