IDirect3DRMViewport

Applications use the methods of the IDirect3DRMViewport interface to work with viewport objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMViewport and IDirect3DRMViewportArray Interface.

The methods of the IDirect3DRMViewport 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
	Transform

The IDirect3DRMViewport 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 IDirect3DRMViewport 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 IDirect3DRM::CreateViewport method.

---

IDirect3DRMViewport::Clear

IDirect3DRMViewport

Clears the given viewport to the current background color.

HRESULT Clear( );

Return Values

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

---

IDirect3DRMViewport::Configure

IDirect3DRMViewport

Reconfigures the origin and dimensions of a viewport.

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 Values

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.

---

IDirect3DRMViewport::ForceUpdate

IDirect3DRMViewport

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

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 Values

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.

---

IDirect3DRMViewport::GetBack

IDirect3DRMViewport

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

D3DVALUE GetBack( );

Return Values

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

See Also

IDirect3DRMViewport::SetBack, Viewing Frustum

---

IDirect3DRMViewport::GetCamera

IDirect3DRMViewport

Retrieves the camera for a viewport.

HRESULT GetCamera(
  LPDIRECT3DRMFRAME *lpCamera
  );

Parameters

lpCamera

Pointer to the Direct3DRMFrame object representing the camera.

Return Values

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

See Also

IDirect3DRMViewport::SetCamera, Camera

---

IDirect3DRMViewport::GetDevice

IDirect3DRMViewport

Retrieves the device associated with a viewport.

HRESULT GetDevice(
  LPDIRECT3DRMDEVICE *lpD3DRMDevice
  );

Parameters

lpD3DRMDevice

Address of a variable that represents the Direct3DRMDevice object.

Return Values

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

---

IDirect3DRMViewport::GetDirect3DViewport

IDirect3DRMViewport

Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport.

HRESULT GetDirect3DViewport(
  LPDIRECT3DVIEWPORT * lplpD3DViewport
  );

Parameters

lplpD3DViewport

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

Return Values

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

---

IDirect3DRMViewport::GetField

IDirect3DRMViewport

Retrieves the field of view for a viewport.

D3DVALUE GetField( );

Return Values

Returns a value describing the field of view.

See Also

IDirect3DRMViewport::SetField, Viewing Frustum

---

IDirect3DRMViewport::GetFront

IDirect3DRMViewport

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

D3DVALUE GetFront( );

Return Values

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

See Also

IDirect3DRMViewport::SetFront, Viewing Frustum

---

IDirect3DRMViewport::GetHeight

IDirect3DRMViewport

Retrieves the height, in pixels, of the viewport.

DWORD GetHeight( );

Return Values

Returns the pixel height.

---

IDirect3DRMViewport::GetPlane

IDirect3DRMViewport

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

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 Values

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

See Also

IDirect3DRMViewport::SetPlane

---

IDirect3DRMViewport::GetProjection

IDirect3DRMViewport

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

D3DRMPROJECTIONTYPE GetProjection( );

Return Values

Returns one of the members of the D3DRMPROJECTIONTYPE enumerated type.

See Also

IDirect3DRMViewport::SetProjection

---

IDirect3DRMViewport::GetUniformScaling

IDirect3DRMViewport

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

BOOL GetUniformScaling( );

Return Values

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

See Also

IDirect3DRMViewport::SetUniformScaling

---

IDirect3DRMViewport::GetWidth

IDirect3DRMViewport

Retrieves the width, in pixels, of the viewport.

DWORD GetWidth( );

Return Values

Returns the pixel width.

---

IDirect3DRMViewport::GetX

IDirect3DRMViewport

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

LONG GetX( );

Return Values

Returns the x-offset.

---

IDirect3DRMViewport::GetY

IDirect3DRMViewport

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

LONG GetY( );

Return Values

Returns the y-offset.

---

IDirect3DRMViewport::Init

IDirect3DRMViewport

Initializes a Direct3DRMViewport object.

HRESULT Init(
  LPDIRECT3DRMDEVICE lpD3DRMDevice,
  LPDIRECT3DRMFRAME lpD3DRMFrameCamera,
  DWORD xpos,
  DWORD ypos,
  DWORD width,
  DWORD height
  );

Parameters

lpD3DRMDevice

Address of the DirectD3DRMDevice object associated with this viewport.

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 Values

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

---

IDirect3DRMViewport::InverseTransform

IDirect3DRMViewport

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

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 Values

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

---

IDirect3DRMViewport::Pick

IDirect3DRMViewport

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.

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 Values

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

---

IDirect3DRMViewport::Render

IDirect3DRMViewport

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.

HRESULT Render(
  LPDIRECT3DRMFRAME lpD3DRMFrame
  );

Parameters

lpD3DRMFrame

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

Return Values

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

---

IDirect3DRMViewport::SetBack

IDirect3DRMViewport

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

HRESULT SetBack(
  D3DVALUE rvBack
  );

Parameters

rvBack

Distance between the camera and the back clipping plane.

Return Values

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

IDirect3DRMViewport::GetBack, IDirect3DRMViewport::SetFront, Viewing Frustum

---

IDirect3DRMViewport::SetCamera

IDirect3DRMViewport

Sets a camera for a viewport.

HRESULT SetCamera(
  LPDIRECT3DRMFRAME lpCamera
  );

Parameters

lpCamera

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

Return Values

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

IDirect3DRMViewport::GetCamera, Camera

---

IDirect3DRMViewport::SetField

IDirect3DRMViewport

Sets the field of view for a viewport.

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 Values

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

IDirect3DRMViewport::GetField, Viewing Frustum

---

IDirect3DRMViewport::SetFront

IDirect3DRMViewport

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

HRESULT SetFront(
  D3DVALUE rvFront
  );

Parameters

rvFront

Distance from the camera to the front clipping plane.

Return Values

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

Remarks

The default position is 1.0. 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

IDirect3DRMViewport::GetFront, Viewing Frustum

---

IDirect3DRMViewport::SetPlane

IDirect3DRMViewport

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

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 Values

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

Remarks

Unlike the IDirect3DRMViewport::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

IDirect3DRMViewport::GetPlane, IDirect3DRMViewport::SetField

---

IDirect3DRMViewport::SetProjection

IDirect3DRMViewport

Sets the projection type for a viewport.

HRESULT SetProjection(
  D3DRMPROJECTIONTYPE rptType
  );

Parameters

rptType

One of the members of the D3DRMPROJECTIONTYPE enumerated type.

Return Values

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

See Also

IDirect3DRMViewport::GetProjection

---

IDirect3DRMViewport::SetUniformScaling

IDirect3DRMViewport

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

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 Values

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 IDirect3DRMViewport::SetPlane method to support banding.

See Also

IDirect3DRMViewport::GetUniformScaling

---

IDirect3DRMViewport::Transform

IDirect3DRMViewport

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

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 Values

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:

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page