D3D Animation Basis(4)

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.

HRESULT load_vertex_shader(IDirect3DVertexShader9 ** ret_vertex_shader,
                           IDirect3DDevice9 * device,
                            const char * filename,
                            const D3DVERTEXELEMENT9 * vertex_elements,
                           IDirect3DVertexDeclaration9 ** ret_vertex_decl)
{
     // error checking
     if (ret_vertex_shader == NULL || device == NULL || filename == NULL)
         return E_FAIL;

     // load and assemble the shader
    ID3DXBuffer * shader_buffer;
    HRESULT hr = D3DXAssembleShaderFromFile(filename, NULL, NULL, 0 , & shader_buffer, NULL);

     if (FAILED(hr))
         return hr;

    hr = device -> CreateVertexShader((DWORD * ) shader_buffer -> GetBufferPointer(), ret_vertex_shader);

     if (FAILED(hr))
         return hr;

    shader_buffer -> Release();

     // create the declaration interface if needed
     if (vertex_elements && ret_vertex_decl)
        device -> CreateVertexDeclaration(vertex_elements, ret_vertex_decl);

     return S_OK;
}

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.

D3D Animation Basis(4)