Vertex Declaration

Conceptually, the vertex declaration is a way of programming the vertex direct memory access (DMA) and the tessellator engine of the graphics pipe. It expresses the data layout and the tessellator operations concisely. To address the complexity and extensibility of declarations in Microsoft?DirectX?8.x, a new format for expressing vertex streams has been introduced.

Vertex shaders and vertex declarations are no longer bound together at CreateVertexShader time. The shader validation has been divided into two parts. One runs at the vertex shader creation time and the other runs at the DrawPrimitive time. Vertex shaders and vertex declarations are represented by objects.

Decls are no longer expressed as streams of DWORDs. They are expressed as an array of D3DVERTEXELEMENT9 structures. Each element of the array describes one vertex element.

Additionally, to address application programming interface (API) usability issues, there will be a separate SetFVF call that is equivalent to the SetVertexDeclaration call. This is a convenience function; when this call is made, it will clobber the currently set declaration and vice versa. If the driver is pre-DirectX 8.0 (NumStreams is set to 0), SetVertexDeclaration might fail for declarations that cannot be converted to flexible vertex format (FVF) with an error. SetFVF can be used with both the fixed function, as well as the programmable vertex pipeline. Internally, FVF is converted to a vertex shader declaration using the Mapping FVF to DirectX 9.0 Decl. DCL commands in vertex shader functions should be written with this in mind. Because of this conversion, all further discussion will be about vertex declarations only.

D3DVERTEXELEMENT9 Structure

The following are the fields in the D3DVERTEXELEMENT9 structure and their explanations.

Stream - Stream number this field is to be read from.
Offset - Offset, in bytes, that this field is being read from.
Type - Type of the input data and how the data is transformed when fed into the vertex shader registers. That is, float1,float2,short2n, etc. Type of the output is determined by the method. Some methods have an implied type.
Method - Any one predefined operations that would be performed by a tessellator (or any procedural geometry routine) on the input specified.
- D3DDECLMETHOD_DEFAULT: When a tessellator is used, this element is interpolated, else copied into the vertex processor's input register. The input type for this operation can be anything. The output type for this operation is the same as the input.
- D3DDECLMETHOD_PARTIALU: Computes the tangent at a point on the rectangular patch (R-patch) in the u-direction. The input type for this operation can be D3DDECLTYPE_FLOAT[43], D3DDECLTYPE_D3DCOLOR, D3DDECLTYPE_UBYTE4, D3DDECLTYPE_SHORT4. The output type for this operation is always D3DDECLTYPE_FLOAT3.
- D3DDECLMETHOD_PARTIALV: Computes the tangent at a point on the R-patch in the v-direction. The input type for this operation can be D3DDECLTYPE_FLOAT[43], D3DDECLTYPE_D3DCOLOR, D3DDECLTYPE_UBYTE4, D3DDECLTYPE_SHORT4. The output type for this operation is always D3DDECLTYPE_FLOAT3.
- D3DDECLMETHOD_CROSSUV: Computes the normal at a point on rect/tri patches (RT-patches) by taking a cross product of the two tangents. The input type for this operation can be D3DDECLTYPE_FLOAT[43], D3DDECLTYPE_D3DCOLOR, D3DDECLTYPE_UBYTE4, or D3DDECLTYPE_SHORT4. The output type for this operation is always D3DDECLTYPE_FLOAT3.
- D3DDECLMETHOD_UV: Copy out the U, V values at a point on an R-patch. Generates a 2-D float. The input type for this operation must be set to D3DDECLTYPE_UNUSED. The output data type is always D3DDECLTYPE_FLOAT2. The input stream and offset are also unused (but must be set to 0).
- D3DDECLMETHOD_LOOKUP: Look up a displacement map. The input type can be D3DDECLTYPE_FLOAT[234]. Only the .x and .y components are used for the texture map lookup. The output type for this operation is always D3DDECLTYPE_FLOAT4. It can be used only if the device supports displacement mapping. This method can be used only with D3DDECLUSAGE_SAMPLE.
- D3DDECLMETHOD_LOOKUPPRESAMPLED: Look up a pre-sampled displacement map. The input type, stream index, and stream offset are all unused (Type must be set to D3DDECLTYPE_UNUSED, and stream and offset must be set to 0). The output type for this operation is always D3DDECLTYPE_FLOAT4. It can be used only if the device supports displacement mapping. This method can be used only with D3DDECLUSAGE_SAMPLE.

Semantic type - The element's usage, for example, is it a Normal? This is useful for N-patches and to enable greater interoperability between various data layouts and vertex shaders. TEXCOORDS semantic can be used for user defined fields (which don't have an existing semantic defined by Microsoft Direct3D?. The semantics are generally a binding mechanism between vertex declarations and vertex shaders. However, in some cases, they have a special interpretation. For example, an element that has NORMAL or POSITION semantic is used by the N-patch tessellator to set up tesselation.

The following are the allowed.

Semantics, usage index	Special interpretations
(D3DDECLUSAGE_POSITION, 0 )	Untransformed position in the fixed function vertex shader and the N-patch tessellator.
(D3DDECLUSAGE_POSITION, 1)	Untransformed position in the fixed function vertex shader for skinning.
(D3DDECLUSAGE_BLENDWEIGHT, 0)	Blend weights in the fixed function vertex shader.
(D3DDECLUSAGE_BLENDINDICES, 0)	Matrix indices for the fixed function vertex-shader-indexed paletted skinning.
(D3DDECLUSAGE_NORMAL, 0)	Vertex normal in the fixed function vertex shader and the N-patch tessellator.
(D3DDECLUSAGE_NORMAL, 1)	Vertex normal in the fixed function vertex shader for skinning.
(D3DDECLUSAGE_PSIZE, 0)	Point-size attribute that is used by the setup engine of the rasterizer to expand a point into a quad for the point-sprite functionality.
(D3DDECLUSAGE_TEXCOORD, n)	Texture coordinates in fixed function vertex shader and pre-3_0 pixel shader. These can be used to pass user defined data.
(D3DDECLUSAGE_TANGENT, n)	Tangent. It has no special interpretation.
(D3DDECLUSAGE_BINORMAL, n)	Binormal. It has no special interpretation.
(D3DDECLUSAGE_TESSFACTOR, 0)	Tessellation factor that is used in the tessellation unit to control the rate of tessellation.
(D3DDECLUSAGE_POSITIONT, 0)	Post-transformed position. When a declaration containing this is set, it bypasses the vertex processing.
(D3DDECLUSAGE_COLOR, 0)	Diffuse color in the fixed function vertex shader and pre-3_0 pixel shader.
(D3DDECLUSAGE_COLOR, 1)	Specular color in the fixed function vertex shader and pre-3_0 pixel shader.
(D3DDECLUSAGE_FOG, 0)	Fog blend value, that is used post pixel shader when a pre-3_0 pixel shader is set.
(D3DDECLUSAGE_DEPTH, n)	Depth. It has no special interpretation.
(D3DDECLUSAGE_SAMPLE, n)	Displacement value looked up. It can be used only with D3DDECLMETHOD_LOOKUPPRESAMPLED or D3DDECLMETHOD_LOOKUP.

A special value for the vertex element is considered the end of vertex shader declaration. This value is #define D3DDECL_END() {0xFF,0,0,0,0,0}.

UsageIndex is used in conjunction with Usage to specify the semantic of a vertex element. Instead of using D3DVSDE_POSITION2 as in DirectX 8.x, now user can specify D3DDECLUSAGE_POSITION as Usage and UsageIndex = 1.

A Decl specifies the input to the tessellator engine (or directly the vertex processing engine in case the tessellator is not used) as well as its output. The type field in the vertex element specifies the type of the input data to the decl. The output type is implied by the method.

There is a preamble in the vertex shader that has the form of {semantic, semantic index, register number}. The runtime matches up the declaration's semantic with the shader's semantic information, thus pairing up an input register with byte offset into a stream.

Mapping FVF to DirectX 9.0 Decl

FVF	Data type	Usage	Usage index
D3DFVF_XYZ	D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_POSITION	0
D3DFVF_XYZRHW	D3DDECLTYPE_FLOAT4	D3DDECLUSAGE_POSITIONT	0
D3DFVF_XYZW	D3DDECLTYPE_FLOAT4	D3DDECLUSAGE_POSITION	0
D3DFVF_XYZB5 and D3DFVF_LASTBETA_UBYTE4	D3DVSDT_FLOAT3 D3DVSDT_FLOAT4 D3DVSDT_UBYTE4	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT D3DDECLUSAGE_BLENDINDICES	0
D3DFVF_XYZB5 and D3DFVF_LASTBETA_D3DCOLOR	D3DVSDT_FLOAT3 D3DVSDT_FLOAT4 D3DVSDT_D3DCOLOR	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT D3DDECLUSAGE_BLENDINDICES	0
D3DFVF_XYZB5	D3DDECLTYPE_FLOAT3 D3DDECLTYPE_FLOAT4 D3DDECLTYPE_FLOAT1	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT D3DDECLUSAGE_BLENDINDICES	0
D3DFVF_XYZBn (n=1..4)	D3DDECLTYPE_FLOAT3 D3DDECLTYPE_FLOATn	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT	0
D3DFVF_XYZBn (n=1..4) and D3DFVF_LASTBETA_UBYTE4	D3DDECLTYPE_FLOAT3 D3DDECLTYPE_FLOAT(n-1) D3DDECLTYPE_UBYTE4	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT D3DDECLUSAGE_BLENDINDICES	0
D3DFVF_XYZBn (n=1..4) and D3DFVF_LASTBETA_D3DCOLOR	D3DDECLTYPE_FLOAT3 D3DDECLTYPE_FLOAT(n-1) D3DDECLTYPE_D3DCOLOR	D3DDECLUSAGE_POSITION D3DDECLUSAGE_BLENDWEIGHT D3DDECLUSAGE_BLENDINDICES	0
D3DFVF_NORMAL	D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_NORMAL	0
D3DFVF_PSIZE	D3DDECLTYPE_FLOAT1	D3DDECLUSAGE_PSIZE	0
D3DFVF_DIFFUSE	D3DDECLTYPE_D3DCOLOR	D3DDECLUSAGE_COLOR	0
D3DFVF_SPECULAR	D3DDECLTYPE_D3DCOLOR	D3DDECLUSAGE_COLOR	1
D3DFVF_TEXCOORDSIZEm(n)	D3DDECLTYPE_FLOATm	D3DDECLUSAGE_TEXCOORD	n

Vertex Declarations with D3DDECLUSAGE_POSITIONT

Presence of a vertex element with (D3DUSAGE_POSITIONT, 0) is used to indicate to the device that the vertex data coming in has already been through vertex processing (like an FVF with D3DFVF_XYZRHW bit set). At Draw time, if the currently set declaration has an element with the (D3DUSAGE_POSITIONT, 0) semantic, the entire vertex processing is skipped (just as if an FVF with D3DFVF_XYZRHW bit has been set).

There are some restrictions on vertex declarations with (D3DDECLUSAGE_POSITIONT, 0):

Only stream zero can be used is such declarations.
Vertex elements must be sorted by increasing stream offset.
Stream offset must be DWORD aligned.
The same (Usage, Usage Index) pair should be listed only once.
Only D3DDECLMETHOD_DEFAULT method can be used.
Other vertex elements cannot have (D3DDECLUSAGE_POSITION, 0) semantic.

In addition, there are some restrictions on such declaration, related to the device driver version. These restrictions are in effect because Direct3D sends such declarations directly to the driver without doing any conversion.

Pre-DirectX 9.0 Drivers

The input declaration must be translatable to a valid FVF (have the same order of vertex elements and their data types).
Gaps in texture coordinates are not allowed. This means that if there is a vertex element with (D3DDECLUSAGE_TEXCOORD, n) then there also should be a vertex element with (D3DDECLUSAGE_TEXCOORD, n-1).

DirectX 9.0 Drivers without Pixel Shader Version 3 Support

The input declaration must be translatable to a valid FVF (have the same order of vertex elements and their data types).
Gaps in texture coordinates are allowed.

DirectX 9.0 Drivers with Pixel Shader Version 3 Support

More general declarations are allowed.

Vertex elements can be in arbitrary order and can have any data types.
Multiple vertex elements can share the same stream offset and be of a different type in the same time when if D3DDEVCAPS2_VERTEXELEMENTSCANSHARESTREAMOFFSET is set by device.

Vertex Declarations without D3DDECLUSAGE_POSITIONT

Runtime validates the creation of declarations. Following are the general rules for what declarations are legal.

All vertex elements for a stream must be consecutive and sorted by offset.
Stream offset must be DWORD aligned.
The same (Usage, Usage Index) pair should be listed only once.
If the D3DDEVCAPS2_VERTEXELEMENTSCANSHARESTREAMOFFSET is set then the vertex elements can:
- Multiple vertex elements can share the same offset in a stream.
- They can all be of different types which can be of different sizes.
- They can overlap arbitrarily. For example, one element can start at a location of a stream that is, at the same time, in the middle of another element.
- Vertex element are allowed to have stream offset in any order.
Number of vertex elements cannot be greater than 64.
UsageIndex should be in the range [0-15].
Declaration, used with the DrawPrimitive API, should not have vertex elements other than D3DDECLMETHOD_DEFAULT, D3DDECLMETHOD_LOOKUPPRESAMPLED or D3DDECLMETHOD_LOOKUP.
Declaration, which contains D3DDECLMETHOD_LOOKUP or LOOKUPPRESAMPLED, should be used only with the programmable vertex pipeline.
Declaration, used with the DrawRectPatch/DrawTriPatch API, cannot have vertex elements with D3DDECLMETHOD_LOOKUPPRESAMPLED or D3DDECLMETHOD_LOOKUP.
Declaration should have only one element with D3DDECLMETHOD_LOOKUP or D3DDECLMETHOD_LOOKUPPRESAMPLED method.
Declaration with D3DDECLMETHOD_LOOKUP or D3DDECLMETHOD_LOOKUPPRESAMPLED should not have elements other than D3DDECLMETHOD_DEFAULT, because displacement mapping is done only for N-patches.
Vertex elements with D3DDECLMETHOD_LOOKUP or D3DDECLMETHOD_LOOKUPPRESAMPLED can only be used with (D3DDECLUSAGE_SAMPLE, n) semantic and vice versa.
If a vertex element with D3DDECLMETHOD_LOOKUP method has stream index and offset of already existing vertex element, this vertex element should have the same data type.
A vertex element with D3DDECLMETHOD_LOOKUP method should have data type D3DDECLTYPE_FLOAT2/3/4
Vertex elements with types D3DDECLMETHOD_CROSSUV, D3DDECLMETHOD_PARTIALU and D3DDECLMETHOD_PARTIALV should have an offset of a vertex element with compatible data type.
A vertex element with method D3DDECLMETHOD_UV or D3DDECLMETHOD_LOOKUPPRESAMPLED must have type D3DDECLTYPE_UNUSED, stream index zero and stream offset zero.
Declarations with methods D3DDECLMETHOD_UV, D3DDECLMETHOD_PARTIALU and D3DDECLMETHOD_PARTIALV can only be used with DrawRectPatch.
Usage D3DDECLUSAGE_TESSFACTOR should be used only with data type D3DDECLTYPE_FLOAT1 and usage index 0.
When a declaration is used for tessellation (DrawRectPatch, DrawTriPatch, N-patches) data type must be less or equal D3DDECLTYPE_SHORT4.
Decls that contain methods that require certain device capabilities (for example, displacement mapping, RT-patches) can only be created if the device supports them.
A vertex declaration, which is used to draw point and lines, cannot have methods other than D3DDECLMETHOD_DEFAULT.
Which decls can be created also depends on the driver capabilities.

Usage with the Programmable Vertex Pipeline

At draw time Direct3D looks for the same "usage - usage index" combination in the current vertex declaration and the current vertex shader function. When the combination is found the register from shader function DCL is used as destination for the vertex element.
When a vertex element in the current vertex declaration has a usage which is not found in the current vertex shader, that vertex element is ignored.
When using vertex shaders version less than 2.0, all semantics, mentioned in the shader code, need to be present in the declaration bound at the draw time. When using vertex shaders 2.0 and above this restriction does not exist, which allows applications to use different vertex declarations with the same vertex shader. This is useful when a vertex shader reads input data based on static conditions. Vertex shader registers, which are not initialized because of this, will have undefined values.

There are additional restrictions when using with hardware vertex processing on a DirectX 8.x driver :

Vertex elements cannot overlap or share the same offset.
Data types are limited to what DirectX 8.x driver can understand.

The CreateVertexDeclaration might fail if the declaration provided cannot be converted to a DirectX 8.x-style decl. For mixed mode device this failure will happen at Draw* time because that is the only time it can be known whether this shader is being used with hardware or software vertex processing.

Usage with the Fixed Function Vertex Pipeline

Only declarations that adhere to the following rules can be used:

There should be no gaps between vertex elements (SKIP was not allowed in a DirectX 8.x declaration, which is used for the fixed function pipeline).
Semantic (D3DDECLUSAGE_POSITION, 0) must be specified and should have D3DDECLTYPE_FLOAT3 data type.
A vertex element with method D3DDECLMETHOD_UV must specify usage D3DDECLUSAGE_TEXCOORD or D3DDECLUSAGE_BLENDWEIGHT.
A vertex element with method D3DDECLMETHOD_PARTIALU, _PARTIALV, or _CROSSUV can only be used with the usages: D3DDECLUSAGE_POSITION, _NORMAL, _BLENDWEIGHT or _TEXCOORD, and must use input type D3DDECLTYPE_FLOAT3.

When a declaration is used with hardware vertex processing on a DirectX 8.x driver, the Direct3D runtime converts it to a DirectX 8.x-style declaration with the following rules.

Vertex elements cannot share the same offset in a stream and they cannot overlap.
Data type must be less or equal D3DDECLTYPE_SHORT4
Only the following methods are allowed: D3DDECLMETHOD_DEFAULT, D3DDECLMETHOD_CROSSUV, D3DDECLMETHOD_UV
Usage and UsageIndex are converted to a register value according to Mapping DirectX 9.0 Declaration to DirectX 8.x.
Mapping DirectX 9.0 Declaration to DirectX 8.x shows which DirectX 9.0 semantics could be converted to DirectX 8.x-style declaration.
If there are n vertex elements in a declaration and 0 - m (m < n), map to an FVF (elements described in the Mapping DirectX 9.0 Declaration to FVF Bits), but m+1 does not, then:
- If any of m+2 until n-1 vertex elements map to FVF/dx8decl, the decl is invalid.
- The elements 0 to m are converted (by the runtime for DirectX 8.0 and older drivers, and by the DirectX 9.0 drivers) using the Mapping DirectX 9.0 Declaration to FVF Bits, m+1, m+2 until n-1 become mapped to contiguous texcoord(k), texcoord(k+1), starting from any texcoord in elements 0 - m.
- The data type at a mapped texcoord is assumed to be float[1234] replacing whatever data type the current element contains (but the same size). So it is ok for the existing data type to be something that is not in Mapping DirectX 9.0 Declaration to FVF Bits.
- If k reaches 8, then the decl is invalid for FVF/dx8decl
- If any mappings to texcoords have occurred, then the entire declaration is required to have no elements with generation method other than DEFAULT.. else, the decl is invalid for FVF/dx8decl.

Mapping DirectX 9.0 Declaration to DirectX 8.x

DirectX 9.0 Usage	DirectX 9.0 Usage Index	DirectX 8.0
D3DDECLUSAGE_POSITION	0	D3DVSDE_POSITION
D3DDECLUSAGE_POSITION	1	D3DVSDE_POSITION2
D3DDECLUSAGE_NORMAL	0	D3DVSDE_NORMAL
D3DDECLUSAGE_NORMAL	1	D3DVSDE_NORMAL2
D3DDECLUSAGE_BLENDWEIGHT	0	D3DVSDE_BLENDWEIGHT
D3DDECLUSAGE_BLENDINDICES	0	D3DVSDE_BLENDINDICES
D3DDECLUSAGE_PSIZE	0	D3DVSDE_PSIZE
D3DDECLUSAGE_COLOR	0	D3DVSDE_DIFFUSE
D3DDECLUSAGE_COLOR	1	D3DVSDE_SPECULAR
D3DDECLUSAGE_TEXCOORD	n	D3DVSDE_TEXCOORDn

When a declaration is used with hardware vertex processing on a DirectX 7.0 driver, the Direct3D runtime converts it to an FVF with the following rules.

Only stream 0 should be used (evident from the MaxStreams cap).
The order of vertex elements should be the same as order of FVF bits.
Gaps in texture coordinates are not allowed
Any vertex element not described in the Mapping DirectX 9.0 Declaration to FVF Bits cannot be converted into a valid FVF for all pre-DirectX 8.0 drivers and hence not be used on those drivers.
Only D3DDECLTYPE_FLOAT2 is allowed for vertex elements with D3DDECLUSAGE_TEXCOORD if device does not set any of the following caps: D3DPTEXTURECAPS_PROJECTED or D3DPTEXTURECAPS_CUBEMAP.

Mapping DirectX 9.0 Declaration to FVF Bits

Data type	Usage	Usage index	FVF
D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_POSITION	0	D3DFVF_XYZ
D3DDECLTYPE_FLOAT4	D3DDECLUSAGE_POSITIONT	0	D3DFVF_XYZRHW
D3DDECLTYPE_FLOATn	D3DDECLUSAGE_BLENDWEIGHT	0	D3DFVF_XYZBn
D3DDECLTYPE_UBYTE4	D3DDECLUSAGE_BLENDINDICES	0	D3DFVF_XYZB (nWeights+1)
D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_NORMAL	0	D3DFVF_NORMAL
D3DDECLTYPE_FLOAT1	D3DDECLUSAGE_PSIZE	0	D3DFVF_PSIZE
D3DDECLTYPE_D3DCOLOR	D3DDECLUSAGE_COLOR	0	D3DFVF_DIFFUSE
D3DDECLTYPE_D3DCOLOR	D3DDECLUSAGE_COLOR	1	D3DFVF_SPECULAR
D3DDECLTYPE_FLOATm	D3DDECLUSAGE_TEXCOORD	n	D3DFVF_TEXCOORDSIZEm(n)
D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_POSITION	1	N/A
D3DDECLTYPE_FLOAT3	D3DDECLUSAGE_NORMAL	1	N/A

Using Vertex Declarations with ProcessVertices

A vertex declaration could be used to describe the output of ProcessVertices. Such declaration should adhere to the following rules.

Only stream 0 must be used.
Vertex elements cannot share the same offset or overlap with each other.
Only D3DDECLMETHOD_DEFAULT methods are allowed.
Only D3DDECLTYPE_FLOATn or D3DDECLTYPE_D3DCOLOR data types can be used.
Vertex elements with (D3DDECLUSAGE_POSITION, 0) or (D3DDECLUSAGE_POSITIONT,0) are not required.
Vertex elements with (D3DDECLUSAGE_POSITION, 0) and (D3DDECLUSAGE_POSITIONT,0) cannot be present in the same declaration.
Current vertex shader must be version 3.0 or higher when such declaration is used.