Applications use the methods of the Direct3DRMViewport2 interface to work with viewport objects. Direct3DRMViewport2 supplies a flag parameter to the Clear method to indicate what should be cleared.
The methods of the Direct3DRMViewport2 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 Miscellaneous Clear Configure ForceUpdate GetDevice GetDirect3DViewport3 Pick Render Offsets GetX GetY Projection types GetProjection SetProjection Scaling GetUniformScaling SetUniformScaling Transformations InverseTransform Transform
The Direct3DRMViewport2 interface inherits the following methods from the Direct3DRMObject interface.
Obtain the Direct3DRMViewport object by using the Direct3DRM3.CreateViewport method.
Clears the given viewport to the current background color.
Syntax
object.Clear(flags As CONST_D3DRMVIEWPORTCLEARFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- flags
- Logical combination of values from the CONST_D3DRMVIEWPORTCLEARFLAGS enumerated type.
Error Values
If an error occurs, this method can return DDERR_INVALIDOBJECT or DDERR_INVALIDPARAMS.
For a complete list of possible errors, see Direct3D Retained Mode Error Values.
Reconfigures the origin and dimensions of a viewport.
Syntax
object.Configure(x As Long, y As Long, width As Long, height As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- x and y
- New position of the viewport.
- width and height
- New width and height of the viewport.
Error Values
This method returns D3DRMERR_BADVALUE if x + width or y + height are greater than the width or height of the device, or if any value of x, y, width, or height is less than zero. For a complete list of possible errors, see Direct3D Retained Mode Error Values.
Forces an area of the viewport to be updated. The specified area will be copied to the screen at the next call to the Direct3DRMDevice3.Update method.
Syntax
object.ForceUpdate(x1 As Long, y1 As Long, x2 As Long, y2 As Long)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- x1 and y1
- Upper-left corner of area to be updated.
- x2 and y2
- Lower-right corner of area to be updated.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
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.
Syntax
object.GetBack( ) As Single
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns a value describing the distance between the back clipping plane and the camera.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the camera for a viewport.
Syntax
object.GetCamera( ) As Direct3DRMFrame3
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the Direct3DRMFrame3 object representing the camera.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the device associated with a viewport.
Syntax
object.GetDevice( ) As Direct3DRMDevice3
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the Direct3DRMDevice3 object representing the device.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the Direct3D viewport corresponding to the current Direct3DRMViewport2 object.
Syntax
object.GetDirect3DViewport( ) As Direct3DViewport3
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the Direct3DViewport3 object.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the viewing frustum angle in radians.
Syntax
object.GetField( ) As Single
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns a value describing the field of view.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the position of the front clipping plane for a viewport.
Syntax
object.GetFront( ) As Single
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns a value describing the distance from the camera to the front clipping plane.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the height of the viewport.
Syntax
object.GetHeight( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the height, in pixels.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the dimensions of the viewport on the front clipping plane.
Syntax
object.GetPlane(l As Single, r As Single, b As Single, t As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- l, r, b, and t
- Left, right, bottom, and top dimensions of the viewport on the front clipping plane. Measurements are recorded in pixels.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.
Syntax
object.GetProjection( ) As CONST_D3DRMPROJECTIONTYPE
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns one of the members of the CONST_D3DRMPROJECTIONTYPE enumerated type.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the scaling property used to scale the viewing volume into the larger window dimension.
Syntax
object.GetUniformScaling( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns 1 if the viewport scales uniformly, or zero value otherwise.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
See Also
Retrieves the width of the viewport.
Syntax
object.GetWidth( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the width, in pixels.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the x-offset of the start of the viewport on a device.
Syntax
object.GetX( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the x-offset.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Retrieves the y-offset of the start of the viewport on a device.
Syntax
object.GetY( ) As Long
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
Return Value
Returns the y-offset.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Transforms the specified vector in screen coordinates to world coordinates, and returns the result.
Syntax
object.InverseTransform(d As D3DVECTOR, s As D3DRMVECTOR4D)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- d
- D3DVECTOR type that will be filled with the result of the operation when the method returns.
- s
- D3DRMVECTOR4D type that represents the source of the operation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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.
Syntax
object.Pick(x As Long, y As Long) As Direct3DRMPickArray
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- x and y
- The x- and y-coordinates used for picking.
Return Value
If the call succeeds, returns a Direct3DRMPickArray interface.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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.
Syntax
object.Render(rootFrame As Direct3DRMFrame3)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- rootFrame
- Direct3DRMFrame3 object that represents the frame hierarchy to be rendered.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
This method returns an error if you try to use the Direct3DRM3.SetOptions method to indicate right-handed support and at the same time use the older means (Direct3DRMViewport2.SetProjection) for providing right-handed support.
Sets the position of the back clipping plane for a viewport.
Syntax
object.SetBack(v As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- v
- Distance between the camera and the back clipping plane. The default value is 100. Reasonable values depend on other viewing frustum settings.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a back clipping plane position key to a Direct3DRMViewportInterpolator object.
See Also
Sets a camera for a viewport.
Syntax
object.SetCamera(f As Direct3DRMFrame3)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- f
- Direct3DRMFrame3 object that represents the camera.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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
Sets the viewing frustum angle in radians.
Syntax
object.SetField(v As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- v
- 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 2 times the arctangent of the front clipping plane over the distance from the camera.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a field of view key to a Direct3DRMViewportInterpolator object.
See Also
Sets the position of the front clipping plane for a viewport.
Syntax
object.SetFront(v As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- v
- Distance from the camera to the front clipping plane. The default value is 1.0. Reasonable values depend on other viewing frustum settings.
Error Values
If the value passed is less than or equal to zero, this method returns the D3DRMERR_BADVALUE error. For a complete list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is also used to add a front clipping plane position key to a Direct3DRMViewportInterpolator object.
See Also
Sets the dimensions of the viewport on the front clipping plane, relative to the camera's z-axis.
Syntax
object.SetPlane(Left As Single, Right As Single, Bottom As Single, Top As Single)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- Left, Right, Bottom, and Top
- Minimum x-, maximum x-, minimum y-, and maximum y-coordinates, respectively, of the four sides of the viewport.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
Unlike the Direct3DRMViewport2.SetField method, which specifies a centered proportional viewport, this method enables you to specify a viewport of arbitrary proportion and position. For example, you could use this method 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
Sets the projection type for a viewport.
Syntax
object.SetProjection(val As CONST_D3DRMPROJECTIONTYPE)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- val
- One of the members of the CONST_D3DRMPROJECTIONTYPE enumerated type.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
Use Direct3DRM3.SetOptions to specify right-handed geometry.
See Also
Sets the scaling property used to scale the viewing volume into the larger dimension of the window.
Syntax
object.SetUniformScaling(flag As CONST_DBOOLFLAGS)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- flag
- New scaling property. If this parameter is D_TRUE, the same horizontal and vertical scaling factor is used to scale the viewing volume. Otherwise, if the parameter is set to D_FALSE, different scaling factors are used to scale the viewing volume exactly into the window. The default setting is D_TRUE.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error Values.
Remarks
This method is typically used with the Direct3DRMViewport2.SetPlane method to support banding.
See Also
Transforms the specified vector in world coordinates to screen coordinates, and returns the result.
Syntax
object.Transform(d As D3DRMVECTOR4D, s As D3DVECTOR)
Parts
- object
- Object expression that resolves to a Direct3DRMViewport2 object.
- d
- D3DRMVECTOR4D type that acts as the destination for the transformation operation.
- s
- D3DVECTOR type that acts as the source for the transformation operation.
Error Values
For a list of possible errors, see Direct3D Retained Mode Error 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
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.