D3DVIEWPORT2

D3DVIEWPORT2

The D3DVIEWPORT2 structure defines the visible 3-D volume and the window dimensions that a 3-D volume projects onto. This structure is used by the methods of the IDirect3D2 and IDirect3DDevice2 interfaces, and in particular by the IDirect3DViewport2::GetViewport2 and IDirect3DViewport2::SetViewport2 methods. This structure was introduced in DirectX 5.

typedef struct _D3DVIEWPORT2 {

DWORD dwSize;

DWORD dwX;

DWORD dwY;

DWORD dwWidth;

DWORD dwHeight;

D3DVALUE dvClipX;

D3DVALUE dvClipY;

D3DVALUE dvClipWidth;

D3DVALUE dvClipHeight;

D3DVALUE dvMinZ;

D3DVALUE dvMaxZ;

} D3DVIEWPORT2, *LPD3DVIEWPORT2;

Members

dwSize

Size of this structure, in bytes. This member must be initialized before the structure is used.

dwX and dwY

Coordinates of the top-left corner of the viewport. Unless you want to render to a subset of the surface, these members can be set to 0.

dwWidth and dwHeight

Dimensions of the viewport.

dvClipX and dvClipY

Coordinates of the top-left corner of the clipping volume.

The relevant coordinates here are the nonhomogeneous coordinates that result from the perspective division that projects the vertices onto the w=1 plane.

dvClipWidth and dvClipHeight

Dimensions of the clipping volume projected onto the w=1 plane. Unless you want to render to a subset of the surface, these members can be set to the width and height of the destination surface.

dvMinZ and dvMaxZ

Values of the D3DVALUE type describing the maximum and minimum nonhomogeneous z-coordinates resulting from the perspective divide and projected onto the w=1 plane.

Remarks

The coordinates and dimensions of the viewport are given relative to the top left of the device; values increase in the y-direction as you descend the screen.

If you are using D3DVERTEX or D3DLVERTEX vertices ¾ that is, if Direct3D is performing the transformations ¾ you might want to set the last six members of this structure as follows:

float inv_aspect = (float)dwHeight/dwWidth;

dvClipX = -1.0f;

dvClipY = inv_aspect;

dvClipWidth = 2.0f;

dvClipHeight = 2.0f * inv_aspect;

dvMinZ = 0.0f;

dvMaxZ = 1.0f;

By taking the aspect ratio into account you are assured that as the surface is resized the angle of the horizontal field of view remains constant. This prevents unexpected distortions when the user pulls the window into an unusual shape. If distortion is not an issue in your application, set aspect to 1. Notice that dividing the height by the width produces an inverse aspect ratio; in Direct3D, the aspect ratio is defined by dividing the width by the height.

If you are using D3DTLVERTEX vertices ¾ that is, if your application is taking care of the transformations and lighting ¾ you can set up the clip space however is best for your application. If the x- and y-coordinates in your data already match pixels, you could set the last six members of D3DVIEWPORT2 as follows:

dvClipX = 0;

dvClipY = 0;

dvClipWidth = dwWidth;

dvClipHeight = dwHeight;

dvMinZ = 0.0f;

dvMaxZ = 1.0f;

Unlike the D3DVIEWPORT structure, D3DVIEWPORT2 specifies the relationship between the size of the viewport and the window.

When the viewport is changed, the driver builds a new transformation matrix.

For more information about working with viewports, see Viewports and Transformations.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in d3dtypes.h.