IDirect3DRMViewport2

Applications use the methods of the IDirect3DRMViewport2 interface to work with viewport objects. For a conceptual overview, see Viewports. Microsoft DirectX version 6.0 introduced the IDirect3DRMViewport2 interface. IDirect3DRMViewport2 extends the older IDirect3DRMViewport interface that it replaces by adding a flag parameter to the Clear method to indicate what should be cleared. For a history of the Direct3D Retained Mode interfaces, see Interface Changes.

The methods of the IDirect3DRMViewport2 interface can be organized into the following groups:

Camera GetCamera
SetCamera
Clipping planes GetBack
GetFront
GetPlane
SetBack
SetFront
SetPlane
Dimensions GetHeight
GetWidth
Field of view GetField
SetField
Initialization Init
Miscellaneous Clear
Configure
ForceUpdate
GetDevice
GetDirect3DViewport
Pick
Render
Offsets GetX
GetY
Projection types GetProjection
SetProjection
Scaling GetUniformScaling
SetUniformScaling
Transformations InverseTransform
InverseTransformVectors
Transform
TransformVectors

The IDirect3DRMViewport2 interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:
AddRef
QueryInterface
Release

In addition, the IDirect3DRMViewport2 interface inherits the following methods from the IDirect3DRMObject interface:
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMViewport object is obtained by using the IDirect3DRM3::CreateViewport method.

IDirect3DRMViewport2::Clear

IDirect3DRMViewport2

Clears the given viewport to the current background color. This is an enhanced version of IDirect3DRMViewport::Clear that provides flags that indicate what should be cleared. IDirect3DRMViewport::Clear takes no parameters.

Syntax

HRESULT Clear(
  DWORD dwFlags);

Parameters

dwFlags
The following flags are currently defined and can be logically combined.
D3DRMCLEAR_TARGET
Clear only the destination rendering surface.
D3DRMCLEAR_ZBUFFER
Clear only the z-buffer surface.
D3DRMCLEAR_DIRTYRECTS
Clear only the dirty rectangle list.
D3DRMCLEAR_ALL
Clear the target, z-buffer, and dirty rectangle list. This flag is analogous to using IDirect3DRMViewport::Clear.

Return Value

Returns one of the following values:
 
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

Remarks

This method was introduced with DirectX version 6.0.

IDirect3DRMViewport2::Configure

IDirect3DRMViewport2

Reconfigures the origin and dimensions of a viewport.

Syntax

HRESULT Configure(
  LONG lX,
  LONG lY,
  DWORD dwWidth,
  DWORD dwHeight
  );

Parameters

lX and lY
New position of the viewport.
dwWidth and dwHeight
New width and height of the viewport.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method returns D3DRMERR_BADVALUE if lX + dwWidth or lY + dwHeight are greater than the width or height of the device, or if any value of lX, lY, dwWidth, or dwHeight is less than zero.

IDirect3DRMViewport2::ForceUpdate

IDirect3DRMViewport2

Forces an area of the viewport to be updated. The specified area will be copied to the screen at the next call to the IDirect3DRMDevice3::Update method.

Syntax

HRESULT ForceUpdate(
  DWORD dwX1,
  DWORD dwY1,
  DWORD dwX2,
  DWORD dwY2
  );

Parameters

dwX1 and dwY1
Upper-left corner of area to be updated.
dwX2 and dwY2
Lower-right corner of area to be updated.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The system might update any region that is larger than the specified rectangle, possibly including the entire window.

IDirect3DRMViewport2::GetBack

IDirect3DRMViewport2

Retrieves the position of the back clipping plane for a viewport.

Syntax

D3DVALUE GetBack( );

Return Value

Returns a value describing the distance between the back clipping plane and the camera.

See Also

IDirect3DRMViewport2::SetBack, Viewing Frustum

IDirect3DRMViewport2::GetCamera

IDirect3DRMViewport2

Retrieves the camera for a viewport.

Syntax

HRESULT GetCamera(
  LPDIRECT3DRMFRAME3 *lpCamera
  );

Parameters

lpCamera
Pointer to the Direct3DRMFrame object representing the camera.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport2::SetCamera, Camera

IDirect3DRMViewport2::GetDevice

IDirect3DRMViewport2

Retrieves the device associated with a viewport.

Syntax

HRESULT GetDevice(
  LPDIRECT3DRMDEVICE3 *lpD3DRMDevice
  );

Parameters

lpD3DRMDevice
Address of a variable that represents the device object. For more information about devices, see Output Devices.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport2::GetDirect3DViewport

IDirect3DRMViewport2

Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport.

Syntax

HRESULT GetDirect3DViewport(
  LPDIRECT3DVIEWPORT *lplpD3DViewport
  );

Parameters

lplpD3DViewport
Address of a pointer that is initialized with a pointer to the Direct3DViewport object.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport2::GetField

IDirect3DRMViewport2

Retrieves the field of view for a viewport.

Syntax

D3DVALUE GetField( );

Return Value

Returns a value describing the field of view.

See Also

IDirect3DRMViewport2::SetField, Viewing Frustum

IDirect3DRMViewport2::GetFront

IDirect3DRMViewport2

Retrieves the position of the front clipping plane for a viewport.

Syntax

D3DVALUE GetFront( );

Return Value

Returns a value describing the distance from the camera to the front clipping plane.

See Also

IDirect3DRMViewport2::SetFront, Viewing Frustum

IDirect3DRMViewport2::GetHeight

IDirect3DRMViewport2

Retrieves the height, in pixels, of the viewport.

Syntax

DWORD GetHeight( );

Return Value

Returns the pixel height.

IDirect3DRMViewport2::GetPlane

IDirect3DRMViewport2

Retrieves the dimensions of the viewport on the front clipping plane.

Syntax

HRESULT GetPlane(
  D3DVALUE *lpd3dvLeft,
  D3DVALUE *lpd3dvRight,
  D3DVALUE *lpd3dvBottom,
  D3DVALUE *lpd3dvTop
  );

Parameters

lpd3dvLeft, lpd3dvRight, lpd3dvBottom, and lpd3dvTop
Addresses of variables that will be filled with the dimensions of the viewport on the front clipping plane.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2

Retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.

Syntax

D3DRMPROJECTIONTYPE GetProjection( );

Return Value

Returns one of the members of the D3DRMPROJECTIONTYPE enumerated type.

See Also

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2

Retrieves the scaling property used to scale the viewing volume into the larger window dimension.

Syntax

BOOL GetUniformScaling( );

Return Value

Returns TRUE if the viewport scales uniformly, or FALSE otherwise.

See Also

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2::GetWidth

IDirect3DRMViewport2

Retrieves the width, in pixels, of the viewport.

Syntax

DWORD GetWidth( );

Return Value

Returns the pixel width.

IDirect3DRMViewport2::GetX

IDirect3DRMViewport2

Retrieves the x-offset of the start of the viewport on a device.

Syntax

LONG GetX( );

Return Value

Returns the x-offset.

IDirect3DRMViewport2::GetY

IDirect3DRMViewport2

Retrieves the y-offset of the start of the viewport on a device.

Syntax

LONG GetY( );

Return Value

Returns the y-offset.

IDirect3DRMViewport2::Init

IDirect3DRMViewport2

Initializes a Direct3DRMViewport object.

Syntax

HRESULT Init(
  LPDIRECT3DRMDEVICE3 lpD3DRMDevice,
  LPDIRECT3DRMFRAME3 lpD3DRMFrameCamera,
  DWORD xpos,
  DWORD ypos,
  DWORD width,
  DWORD height
  );

Parameters

lpD3DRMDevice
Address of the device object associated with this viewport. For more information about devices, see Output Devices.
lpD3DRMFrameCamera
Address of the camera frame associated with this viewport.
xpos and ypos
The x- and y-coordinates of the upper-left corner of the viewport.
width and height
Width and height of the viewport.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2

Transforms the vector in the lprvSrc parameter in screen coordinates to world coordinates, and returns the result in the lprvDst parameter.

Syntax

HRESULT InverseTransform(
  D3DVECTOR *lprvDst,
  D3DRMVECTOR4D *lprvSrc
  );

Parameters

lprvDst
Address of a D3DVECTOR structure that will be filled with the result of the operation when the method returns.
lprvSrc
Address of a D3DRMVECTOR4D structure that represents the source of the operation.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

See Also

IDirect3DRMViewport2::InverseTransformVectors, IDirect3DRMViewport2::Transform

IDirect3DRMViewport2::InverseTransformVectors

IDirect3DRMViewport2

This transforms an array of vectors in the lpSrcVectors parameter in screen coordinates to world coordinates, and returns the result in the lprvDstVectors parameter

Syntax

HRESULT InverseTransformVectors(
   DWORD dwNumVectors,
   LPD3DVECTOR	lpDstVectors,
   LPD3DRMVECTOR4D lpSrcVectors);

Parameters

dwNumVectors
The number of vectors whose coordinates are to be transformed.
lpDstVectors
Destination of the transformation.
lpSrcVectors
Array of D3DRMVECTOR4D structures representing the vectors to transform.

Return Value

Returns one of the following values:
 
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

IDirect3DRMViewport2::TransformVectors, IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::Pick

IDirect3DRMViewport2

Finds a depth-sorted list of objects (and faces, if relevant) that includes the path taken in the hierarchy from the root down to the frame that contained the object.

Syntax

HRESULT Pick(
  LONG lX,
  LONG lY,
  LPDIRECT3DRMPICKEDARRAY *lplpVisuals
  );

Parameters

lX and lY
Coordinates used for picking.
lplpVisuals
Address of a pointer that is initialized with a valid pointer to the IDirect3DRMPickedArray interface if the call succeeds.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

IDirect3DRMViewport2::Render

IDirect3DRMViewport2

Renders a frame hierarchy to the given viewport. Only those visuals on the given frame and any frames below it in the hierarchy are rendered.

Syntax

HRESULT Render(
  LPDIRECT3DRMFRAME lpD3DRMFrame
  );

Parameters

lpD3DRMFrame
Address of a variable that represents the Direct3DRMFrame object that represents the frame hierarchy to be rendered.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values. This method returns an error if you try to use the IDirect3DRM3::SetOptions method to indicate right-handed support and at the same time use the older means (IDirect3DRMViewport2::SetProjection) for providing right-handed support.

IDirect3DRMViewport2::SetBack

IDirect3DRMViewport2

Sets the position of the back clipping plane for a viewport.

Syntax

HRESULT SetBack(
  D3DVALUE rvBack
  );

Parameters

rvBack
Distance between the camera and the back clipping plane. The default value is 100.0. Reasonable values depend on other viewing frustrum settings. For more information, see Viewports.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a back clipping plane position key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport2::GetBack, IDirect3DRMViewport2::SetFront, Viewing Frustum

IDirect3DRMViewport2::SetCamera

IDirect3DRMViewport2

Sets a camera for a viewport.

Syntax

HRESULT SetCamera(
  LPDIRECT3DRMFRAME3 lpCamera
  );

Parameters

lpCamera
Address of a variable that represents the Direct3DRMFrame object that represents the camera.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method sets a viewport's position, direction, and orientation to that of the given camera frame. The view is oriented along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.

See Also

IDirect3DRMViewport2::GetCamera, Camera

IDirect3DRMViewport2::SetField

IDirect3DRMViewport2

Sets the field of view for a viewport.

Syntax

HRESULT SetField(
  D3DVALUE rvField
  );

Parameters

rvField
New field of view. This value is a fraction of the viewing angle. The default value is 0.5. If this value is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error. The viewing angle is defined as the 2 times the arctangent of the front clipping plane over the distance from the camera. See Viewing Frustum for more information on the viewing angle. An rvField value of 0.5 would be one-half the viewing angle A shown in the Viewing Frustum section.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is also used to add a field of view key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport2::GetField, Viewing Frustum

IDirect3DRMViewport2::SetFront

IDirect3DRMViewport2

Sets the position of the front clipping plane for a viewport.

Syntax

HRESULT SetFront(
  D3DVALUE rvFront
  );

Parameters

rvFront
Distance from the camera to the front clipping plane. The default value is 1.0. Reasonable values depend on other viewing frustrum settings. For more information, see Viewports.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

If the value passed is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error.

This method is also used to add a front clipping plane position key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport2::GetFront, Viewing Frustum

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2

Sets the dimensions of the viewport on the front clipping plane, relative to the camera's z-axis.

Syntax

HRESULT SetPlane(
  D3DVALUE rvLeft,
  D3DVALUE rvRight,
  D3DVALUE rvBottom,
  D3DVALUE rvTop
  );

Parameters

rvLeft, rvRight, rvBottom, and rvTop
Minimum x-, maximum x-, minimum y-, and maximum y-coordinates, respectively, of the four sides of the viewport.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

Unlike the IDirect3DRMViewport2::SetField method, which specifies a centered proportional viewport, this method allows you to specify a viewport of arbitrary proportion and position. For example, this method could be used to construct a sheared viewing frustum to implement a right- or left-eye stereo view.

This method is also used to add a plane key to a Direct3DRMViewportInterpolator object.

See Also

IDirect3DRMViewport2::GetPlane, IDirect3DRMViewport2::SetField

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2

Sets the projection type for a viewport.

Syntax

HRESULT SetProjection(
  D3DRMPROJECTIONTYPE rptType
  );

Parameters

rptType
One of the members of the D3DRMPROJECTIONTYPE enumerated type.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

With DirectX version 6.0 or later, use IDirect3DRM3::SetOptions to specify right-handed geometry.

See Also

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2

Sets the scaling property used to scale the viewing volume into the larger dimension of the window.

Syntax

HRESULT SetUniformScaling(
  BOOL bScale
  );

Parameters

bScale
New scaling property. If this parameter is TRUE, the same horizontal and vertical scaling factor is used to scale the viewing volume. Otherwise, different scaling factors are used to scale the viewing volume exactly into the window. The default setting is TRUE.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

This method is typically used with the IDirect3DRMViewport2::SetPlane method to support banding.

See Also

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2::Transform

IDirect3DRMViewport2

Transforms the vector in the lprvSrc parameter in world coordinates to screen coordinates, and returns the result in the lprvDst parameter.

Syntax

HRESULT Transform(
  D3DRMVECTOR4D *lprvDst,
  D3DVECTOR *lprvSrc
  );

Parameters

lprvDst
Address of a D3DRMVECTOR4D structure that acts as the destination for the transformation operation.
lprvSrc
Address of a D3DVECTOR structure that acts as the source for the transformation operation.

Return Value

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

Remarks

The result of the transformation is a four-element homogeneous vector. The point represented by the resulting vector is visible if the following equations are true:

Equations for testing whether the point is visible

See Also

IDirect3DRMViewport2::TransformVectors, IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::TransformVectors

IDirect3DRMViewport2

Transforms an array of vectors in the lprvSrcVectors parameter in world coordinates to screen coordinates, and returns the result in the lprvDstVectors parameter.

Syntax

HRESULT TransformVectors(
  DWORD dwNumVectors,
  LPD3DRMVECTOR4D lpDstVectors,
  LPD3DVECTOR lpSrcVectors);

Parameters

dwNumVectors
The number of vectors to be transformed.
lpDstVectors
Array of D3DRMVECTOR4D structures representing the vectors transformed to screen coordinates.
lpSrcVectors
Array of vectors to transform.

Return Value

Returns one of the following values:
 
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

Remarks

This method was introduced with DirectX version 6.0.

See Also

IDirect3DRMViewport2::Transform, IDirect3DRMViewport2::InverseTransformVectors


Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.