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 introduces 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::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::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::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::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::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::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::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::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::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::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
Beginning with DirectX version 6.0, use IDirect3DRM3::SetOptions to specify right-handed geometry.
See Also
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::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:
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
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.