Programmable Stream Model

This section describes shaders that can be used for the programmable stream model.

Using Streams

Microsoft?DirectX?8.0 introduced the notion of a stream to bind data to input registers for use by shaders. A stream is a uniform array of component data, where each component consists of one or more elements that represent a single entity such as position, normal, color, and so on. Streams enable graphic chips to perform a direct memory access (DMA) from multiple vertex buffers in parallel and also provide a more natural mapping from application data. They also enable trivial multitexture versus multipass. Think of it like this:

A vertex is composed of n streams.
A stream is composed of m elements.
An element is [position, color, normal, texture coordinate].

The IDirect3DDevice9::SetStreamSource method binds a vertex buffer to a device data stream, creating an association between the vertex data and one of several data stream ports that feed the primitive processing functions. The actual references to the stream data do not occur until a drawing method, such as IDirect3DDevice9::DrawPrimitive, is called.

The mapping of the input vertex elements to the vertex input registers for programmable vertex shaders is defined in the shader declaration, but the input vertex elements do not have specific semantics about their use. The interpretation of the input vertex elements is programmed using the shader instructions. The vertex shader function is defined by an array of instructions that are applied to each vertex. The vertex output registers are explicitly written to, using instructions in the shader function.

For this discussion, though, be less concerned with the semantic mapping of elements to registers and more concerned with the questions "why use streams?" and "what problem do streams solve?". The main benefit of streams is that they remove the vertex data costs previously associated with multitexturing. Before streams, a user had to either duplicate vertex data sets to handle the single and multitexture case with no unused data elements, or carry data elements that would be unused except in the multitexture case.

Here is an example of using two sets of vertex data, one for single texture and one for multitexturing.

 
struct CUSTOMVERTEX_TEX1
{
    FLOAT x, y, z;      // The untransformed position for the vertex
    DWORD diffColor;    // The vertex diffuse color    
    DWORD specColor;    // The vertex specular color
    float tu_1, tv_1;   // Texture coordinates for a single texture
};
 
struct CUSTOMVERTEX_TEX2
{
    FLOAT x, y, z;      // The untransformed position for the vertex
    DWORD diffColor;    // The vertex diffuse color    
    DWORD specColor;    // The vertex specular color
    float tu_2, tv_2;   // Texture coordinates for multitexturing
};

The alternative is to have a single vertex element that contained both sets of texture coordinates.

 
struct CUSTOMVERTEX_TEX2
{
    FLOAT x, y, z;      // The untransformed position for the vertex
    DWORD diffColor;    // The vertex diffuse color    
    DWORD specColor;    // The vertex specular color
    float tu_1, tv_1;   // Texture coordinates for a single texture
    float tu_2, tv_2;   // Texture coordinates for multitexturing
};

With this vertex data, only one copy of the position and color data are carried in memory, at the expense of carrying both sets of texture coordinates around for rendering even in the single texture case.

Now that the tradeoff is clear, streams provide an elegant fix to this dilemma. Here is a set of vertex definitions to support three streams: one with position and color, one with the first set of texture coordinates, and one with the second set of texture coordinates.

 
// multistream vertex
// stream 0, pos, diffuse, specular
struct POSCOLORVERTEX
{
    FLOAT x, y, z;
    DWORD diffColor, specColor;
};
#define D3DFVF_POSCOLORVERTEX (D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_SPECULAR)


// stream 1, tex coord 0
struct TEXC0VERTEX
{
    FLOAT tu1, tv1;
};
#define D3DFVF_TEXC0VERTEX (D3DFVF_TEX1)

// stream 2, tex coord 1
struct TEXC1VERTEX
{
    FLOAT tu2, tv2;
};
#define D3DFVF_TEXC1VERTEX (D3DFVF_TEX0)

The vertex declaration would be:

 
// multitexture - multistream

D3DVERTEXELEMENT9 dwDecl3[] = 
{
	{ 0, 0,  D3DDECLTYPE_FLOAT3,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_POSITION, 0 },
	{ 0, 12, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  0 },
	{ 0, 28, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  1 },
	{ 1, 36, D3DDECLTYPE_FLOAT2,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_TEXCOORD, 0 },
	{ 2, 44, D3DDECLTYPE_FLOAT2,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_TEXCOORD, 0 },
	D3DDECL_END()
};

Now create the vertex declaration object and set it as shown:

 
LPDIRECT3DVERTEXDECLARATION9 m_pVertexDeclaration;
g_d3dDevice->CreateVertexDeclaration( dwDecl3, &m_pVertexDeclaration );

m_pd3dDevice->SetVertexDeclaration( m_pVertexDeclaration );

Examples of Combinations

One Stream Diffuse Color

The vertex declaration and stream settings for diffuse color rendering would look like this:

 
D3DVERTEXELEMENT9 dwDecl3[] = 
{
	{ 0, 0,  D3DDECLTYPE_FLOAT3,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_POSITION, 0 },
	{ 0, 12, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  0 },
	{ 0, 28, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  1 },
	D3DDECL_END()
};


   m_pd3dDevice->SetStreamSource( 0, m_pVBVertexShader0, 0,
                                      sizeof(CUSTOMVERTEX) );
   m_pd3dDevice->SetStreamSource( 1, NULL, 0, 0);
   m_pd3dDevice->SetStreamSource( 2, NULL, 0, 0);

Two Streams with Color and Texture

The vertex declaration and stream settings for single texture rendering would look like this:

 
D3DVERTEXELEMENT9 dwDecl3[] = 
{
	{ 0, 0,  D3DDECLTYPE_FLOAT3,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_POSITION, 0 },
	{ 0, 12, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  0 },
	{ 0, 28, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  1 },

	{ 1, 36, D3DDECLTYPE_FLOAT2,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_TEXCOORD, 0 },

	D3DDECL_END()
};


   m_pd3dDevice->SetStreamSource( 0, m_pVBPosColor, 0,
                                           sizeof(POSCOLORVERTEX) );
   m_pd3dDevice->SetStreamSource( 1, m_pVBTexC0, 0,
                                           sizeof(TEXC0VERTEX) );
   m_pd3dDevice->SetStreamSource( 2, NULL, 0, 0);

Two Streams with Color and two Textures

The vertex declaration and stream settings for two-texture multi-texture rendering would look like this:

 
D3DVERTEXELEMENT9 dwDecl3[] = 
{
	{ 0, 0,  D3DDECLTYPE_FLOAT3,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_POSITION, 0 },
	{ 0, 12, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  0 },
	{ 0, 28, D3DDECLTYPE_D3DCOLOR, D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_COLOR,  1 },

	{ 1, 36, D3DDECLTYPE_FLOAT2,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_TEXCOORD, 0 },

	{ 2, 44, D3DDECLTYPE_FLOAT2,   D3DDECLMETHOD_DEFAULT, 
	                                  D3DDECLUSAGE_TEXCOORD, 0 },
	
	D3DDECL_END()
};
 
m_pd3dDevice->SetStreamSource( 0, m_pVBPosColor, 0, 
                                          sizeof(POSCOLORVERTEX) );
m_pd3dDevice->SetStreamSource( 1, m_pVBTexC0, 0, 
                                          sizeof(TEXC0VERTEX) );
m_pd3dDevice->SetStreamSource( 2, m_pVBTexC1, 0, 
                                          sizeof(TEXC1VERTEX) );

In every case, the following IDirect3DDevice9::DrawPrimitive invocation suffices.

 
       m_pd3dDevice->DrawPrimitive( D3DPT_TRIANGLEFAN, 0, NUM_TRIS );

This shows the flexibility of streams in solving the problem of data duplication/redundant data transmission across the bus (that is, of wasting bandwidth).