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.
Clears the given viewport to the current background color.
HRESULT Clear( );
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Reconfigures the origin and dimensions of a viewport.
HRESULT Configure(
LONG lX,
LONG lY,
DWORD dwWidth,
DWORD dwHeight
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The system might update any region that is larger than the specified rectangle, possibly including the entire window.
Retrieves the position of the back clipping plane for a viewport.
D3DVALUE GetBack( );
Returns a value describing the distance between the back clipping plane and the camera.
IDirect3DRMViewport::SetBack, Viewing Frustum
Retrieves the camera for a viewport.
HRESULT GetCamera(
LPDIRECT3DRMFRAME *lpCamera
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMViewport::SetCamera, Camera
Retrieves the device associated with a viewport.
HRESULT GetDevice(
LPDIRECT3DRMDEVICE *lpD3DRMDevice
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport.
HRESULT GetDirect3DViewport(
LPDIRECT3DVIEWPORT * lplpD3DViewport
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the field of view for a viewport.
D3DVALUE GetField( );
Returns a value describing the field of view.
IDirect3DRMViewport::SetField, Viewing Frustum
Retrieves the position of the front clipping plane for a viewport.
D3DVALUE GetFront( );
Returns a value describing the distance from the camera to the front clipping plane.
IDirect3DRMViewport::SetFront, Viewing Frustum
Retrieves the height, in pixels, of the viewport.
DWORD GetHeight( );
Returns the pixel height.
Retrieves the dimensions of the viewport on the front clipping plane.
HRESULT GetPlane(
D3DVALUE *lpd3dvLeft,
D3DVALUE *lpd3dvRight,
D3DVALUE *lpd3dvBottom,
D3DVALUE *lpd3dvTop
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.
D3DRMPROJECTIONTYPE GetProjection( );
Returns one of the members of the D3DRMPROJECTIONTYPE enumerated type.
IDirect3DRMViewport::SetProjection
Retrieves the scaling property used to scale the viewing volume into the larger window dimension.
BOOL GetUniformScaling( );
Returns TRUE if the viewport scales uniformly, or FALSE otherwise.
IDirect3DRMViewport::SetUniformScaling
Retrieves the width, in pixels, of the viewport.
DWORD GetWidth( );
Returns the pixel width.
Retrieves the x-offset of the start of the viewport on a device.
LONG GetX( );
Returns the x-offset.
Retrieves the y-offset of the start of the viewport on a device.
LONG GetY( );
Returns the y-offset.
Initializes a Direct3DRMViewport object.
HRESULT Init(
LPDIRECT3DRMDEVICE lpD3DRMDevice,
LPDIRECT3DRMFRAME lpD3DRMFrameCamera,
DWORD xpos,
DWORD ypos,
DWORD width,
DWORD height
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the position of the back clipping plane for a viewport.
HRESULT SetBack(
D3DVALUE rvBack
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a back clipping plane position key to a Direct3DRMViewportInterpolator object.
IDirect3DRMViewport::GetBack, IDirect3DRMViewport::SetFront, Viewing Frustum
Sets a camera for a viewport.
HRESULT SetCamera(
LPDIRECT3DRMFRAME lpCamera
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMViewport::GetCamera, Camera
Sets the field of view for a viewport.
HRESULT SetField(
D3DVALUE rvField
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a field of view key to a Direct3DRMViewportInterpolator object.
IDirect3DRMViewport::GetField, Viewing Frustum
Sets the position of the front clipping plane for a viewport.
HRESULT SetFront(
D3DVALUE rvFront
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMViewport::GetFront, Viewing Frustum
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMViewport::GetPlane, IDirect3DRMViewport::SetField
Sets the projection type for a viewport.
HRESULT SetProjection(
D3DRMPROJECTIONTYPE rptType
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMViewport::GetProjection
Sets the scaling property used to scale the viewing volume into the larger dimension of the window.
HRESULT SetUniformScaling(
BOOL bScale
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is typically used with the IDirect3DRMViewport::SetPlane method to support banding.
IDirect3DRMViewport::GetUniformScaling
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
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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:
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.