Direct3DRMViewport2

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.

Direct3DRMViewport2.Clear

Direct3DRMViewport2

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.

Direct3DRMViewport2.Configure

Direct3DRMViewport2

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.

Direct3DRMViewport2.ForceUpdate

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetBack

Direct3DRMViewport2

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

Direct3DRMViewport2.SetBack

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2

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

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2.GetDevice

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetDirect3DViewport

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetField

Direct3DRMViewport2

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

Direct3DRMViewport2.SetField

Direct3DRMViewport2.GetFront

Direct3DRMViewport2

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

Direct3DRMViewport2.SetFront

Direct3DRMViewport2.GetHeight

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2

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

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2

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

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2

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

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2.GetWidth

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetX

Direct3DRMViewport2

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.

Direct3DRMViewport2.GetY

Direct3DRMViewport2

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.

Direct3DRMViewport2.InverseTransform

Direct3DRMViewport2

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.

Direct3DRMViewport2.Pick

Direct3DRMViewport2

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.

Direct3DRMViewport2.Render

Direct3DRMViewport2

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.

Direct3DRMViewport2.SetBack

Direct3DRMViewport2

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

Direct3DRMViewport2.GetBack, Direct3DRMViewport2.SetFront

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2

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

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2.SetField

Direct3DRMViewport2

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

Direct3DRMViewport2.GetField

Direct3DRMViewport2.SetFront

Direct3DRMViewport2

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

Direct3DRMViewport2.GetFront

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2

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

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2

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

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2

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

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2.Transform

Direct3DRMViewport2

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

Direct3DRMViewport2.InverseTransform

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