The Viewport

[Previous] [Next]

As you saw earlier in this chapter, the last stage of the T&L pipeline is to transform the vertices from projection space into screen space based on the viewport. In screen space, the x and y coordinates of the vertices correspond to pixels, and the z coordinate is the value that will be stored in the z-buffer. Before sending any vertices through the T&L pipeline, you need to pass Direct3D a structure that specifies the viewport parameters.

Creating the Viewport

With DirectX 7, the viewport rectangle is defined using the D3DVIEWPORT7 structure. This structure, shown earlier, is used by the viewport manipulation methods of the IDirect3DDevice7 interface: IDirect3DDevice7::SetViewport and IDirect3DDevice7::GetViewport.

The D3DVIEWPORT7 structure, specified as the only parameter of the IDirect3DDevice7::SetViewport method, describes the viewport parameters and is defined as follows:

 typedef struct _D3DVIEWPORT7 {     DWORD       dwX;     DWORD       dwY;     DWORD       dwWidth;     DWORD       dwHeight;     D3DVALUE    dvMinZ;     D3DVALUE    dvMaxZ; } D3DVIEWPORT7, *LPD3DVIEWPORT7; 

Parameter	Description
dwX and dwY	The pixel coordinates of the top-left corner of the viewport on the render-target surface. Set these members to 0 unless you want to render to a subset of the surface.
dwWidth and dwHeight	The dimensions, in pixels, of the viewport on the render-target surface. Set these members to the dimensions of the render-target surface unless you're rendering only to a subset of the surface.
dvMinZ and dvMaxZ	These members define the maximum and minimum nonhomogeneous z coordinates that result from the perspective divide and are projected onto the w = 1 plane.

The dwX, dwY, dwWidth, and dwHeight members (defined as screen coordinates that are relative to the upper-left corner of the render-target surface) of the D3DVIEWPORT7 structure define the area of the render-target surface into which the scene will be rendered. This is known as the viewport rectangle or the destination rectangle.

Setting Up the Viewport

The following code sets up the viewport by setting various members of the D3DVIEWPORT7 structure:

 // // Set up the viewport for a reasonable viewing area. //  D3DVIEWPORT7 viewData; memset(&viewData, 0, sizeof(D3DVIEWPORT7)); viewData.dwSize = sizeof(D3DVIEWPORT7); viewData.dwX = viewData.dwY = 0; viewData.dwWidth = w; viewData.dwHeight = h; viewData.dvMinZ = 0.0f; viewData.dvMaxZ = 1.0f; 

Once you've set the D3DVIEWPORT7 structure's members, you can pass the structure to Direct3D by using the IDirect3DDevice7::SetViewport method, which has the following function declaration:

 HRESULT IDirect3DDevice7::SetViewport(     LPD3DVIEWPORT7 lpViewport ); 

IDirect3DDevice7::SetViewport has one parameter, lpViewport, which holds the address of a D3DVIEWPORT7 structure containing the new viewport.

Clearing the Viewport

Once the viewport is prepared, you can clear it to reset the contents of the viewport rectangle on the render-target surface and the rectangles in the depth and stencil buffer surfaces if it was specified. IDirect3DDevice7 provides the IDirect3DDevice7::Clear method to clear the viewport. Because our focus is on real-time 3D games and simulations, we usually need to update the entire viewport rectangle—after all, every portion of the scene is changing. However, this method can accept one or more rectangles describing the area or areas on the surfaces being cleared if you need to clear only portions of the viewport, which is the case when you're using a portion of the display to represent a HUD or a game-scoring frame around the viewport.

Here's the declaration for this method:

 HRESULT IDirect3DDevice7::Clear(     DWORD dwCount,     LPD3RECT lpRects,     DWORD dwFlags,     DWORD dwColor,     D3DVALUE dvZ,     DWORD dwStencil ); 

Parameter	Description
dwCount	The number of rectangles in the array lpRects.
lpRects	An array of D3DRECT structures defining the rectangles to be cleared. Each rectangle contains screen coordinates that correspond to points on the render-target surface.
dwFlags	Holds the flags defining how the surface will be cleared. At least one of the following flags (or a combination of them) must be used: D3DCLEAR_TARGET Clears the rendering target to the color in the dwColor parameter. D3DCLEAR_ZBUFFER Clears the depth buffer to the value in the dvZ parameter. D3DCLEAR_STENCIL Clears the stencil buffer to the value in the dwStencil parameter.
dwColor	A 32-bit RGBA color value the render-target surface will be cleared to.
dvZ	The new z value that this method stores in the depth buffer. This parameter can range from 0.0 (closest) through 1.0 (farthest).
dwStencil	The value to store in each stencil-buffer entry, with a valid range from 0 through 2n - 1 inclusive, where n is the bit depth of the stencil buffer.

You can specify the D3DCLEAR_TARGET flag so that the viewport is cleared using an RGBA color specified in the dwColor parameter. You can use the D3DCLEAR_ZBUFFER flag to clear the depth buffer to a depth specified in dvZ. This value can range between 0.0 (the closest distance) through 1.0 (the farthest distance). Finally, you can use the D3DCLEAR_STENCIL flag to reset the stencil bits to the value specified in the dwStencil parameter. This value can range in value from 0 through 2ⁿ - 1, where n is the stencil buffer's bit depth.