3D viewing volume class. More...

#include <Inventor/SbViewVolume.h>

Public Types
enum	ProjectionType { ORTHOGRAPHIC , PERSPECTIVE }
	Projection type. More...

enum	StereoMode { MONOSCOPIC , LEFT_VIEW , RIGHT_VIEW }
	Stereo Modes. More...

Public Member Functions
	SbViewVolume ()
	Default constructor.

	~SbViewVolume ()
	Destructor.

float	getMatrices (SbMatrix &affine, SbMatrix &proj) const
	Returns two matrices corresponding to the view volume.

SbMatrix	getMatrix () const
	Like the method above, but returns the affine and projection parts together in one matrix (i.e., affine.multRight(proj) ).

SbMatrix	getCameraSpaceMatrix () const
	Returns a matrix that transforms the view volume into camera space: it translates the view volume so the viewpoint is at the origin, and rotates it so the view direction is along the negative z axis.

void	projectPointToLine (const SbVec2f &pt, SbLine &line) const
	Maps a 2D point (in 0 <= x,y <= 1) to a 3D line.

void	projectPointToLine (const SbVec2f &pt, SbVec3f &line0, SbVec3f &line1) const
	Maps a 2D point (in 0 <= x,y <= 1) to a 3D line.

void	projectToScreen (const SbVec3f &src, SbVec3f &dst) const
	Maps a 3D point in world coordinates to a 2D point in normalized screen coordinates (0 <= x,y,z <= 1).

void	projectFromScreen (const SbVec3f &src, SbVec3f &dst) const
	Maps a 3D point in normalized screen coordinates (0 <= x,y,z <= 1) to a 3D world point.

SbPlane	getPlane (float distFromEye) const
	Returns a plane parallel to the near (or far) plane of the view volume at a given distance from the projection point (eye).

SbVec3f	getSightPoint (float distFromEye) const
	Returns the point along the line of sight at the given distance from the projection point (eye).

SbVec3f	getPlanePoint (float distFromEye, const SbVec2f &normPoint) const
	Maps a 2D point in normalized screen coordinates (0 <= x,y <= 1) to a 3D world coordinates point on the plane parallel to the near plane that is at distFromEye units from the eye.

SbRotation	getAlignRotation (SbBool rightAngleOnly=FALSE) const
	Returns a rotation that would align a viewed object so that its positive x-axis (of its object space) is to the right in the view and its positive y-axis is up.

float	getWorldToScreenScale (const SbVec3f &worldCenter, float normRadius) const
	Returns a scale factor that would scale a unit sphere centered at worldCenter so that it would appear to have the given radius in normalized screen coordinates when projected onto the near plane.

SbVec2f	projectBox (const SbBox3f &box) const
	Projects the given 3D bounding box onto the near plane and returns the size (in normalized screen coordinates) of the rectangular region that encloses it.

SbBox3f	getProjectedBbox (const SbBox3f &box) const
	Projects the given 3D bounding box onto the near plane and returns it (in normalized screen coordinates).

SbViewVolume	narrow (float left, float bottom, float right, float top) const
	Given a view volume, narrows the view to the given sub-rectangle of the near plane.

SbViewVolume	narrow (const SbBox3f &box) const
	Narrows a view volume by the given box.

void	ortho (float left, float right, float bottom, float top, float nearPlane, float farPlane)
	Sets up an orthographic view volume with the given sides.

void	perspective (float fovy, float aspect, float nearPlane, float farPlane)
	Sets up a perspective view volume with the given field of view and aspect ratio.

void	rotateCamera (const SbRotation &q)
	Rotate the camera view direction.

void	translateCamera (const SbVec3f &v)
	Translate the camera viewpoint.

SbVec3f	zVector () const
	Returns the positive z axis in eye space.

SbViewVolume	zNarrow (float nearPlane, float farPlane) const
	Returns a narrowed view volume which contains as tightly as possible the given interval on the z axis (in eye space).

void	scale (float factor)
	Scales width and height of view volume by given factor.

void	scaleWidth (float ratio)
	Scales view volume to be the given ratio of its current width, leaving the resulting view volume centered about the same point (in the near plane) as the current one.

void	scaleHeight (float ratio)
	Scales view volume to be the given ratio of its current height, leaving the resulting view volume centered about the same point (in the near plane) as the current one.

ProjectionType	getProjectionType () const
	Returns projection type.

const SbVec3f &	getProjectionPoint () const
	Returns projection point.

const SbVec3f &	getProjectionDirection () const
	Returns projection direction.

float	getNearDist () const
	Returns distance from projection point to near plane.

float	getWidth () const
	Returns width of viewing frustum.

float	getHeight () const
	Returns height of viewing frustum.

float	getDepth () const
	Returns depth of viewing frustum.

void	setStereoAbsoluteAdjustments (SbBool absolute)
	Specifies if stereo adjustments are absolute.

SbBool	isStereoAbsoluteAdjustments () const
	Returns TRUE if the stereo adjustments are absolute.

void	setStereoAdjustment (float adjustment)
	Sets the stereo offset (the distance of each eye from the camera position).

float	getStereoAdjustment () const
	Queries the stereo offset.

void	setBalanceAdjustment (float adjustment, SbBool nearFrac=false)
	Sets the stereo balance (the position of the zero parallax plane) and specifies whether the balance value is defined as a fraction of the camera near distance.

float	getBalanceAdjustment () const
	Queries the parallax balance.

SbBool	isBalanceNearFraction () const
	Returns TRUE if the stereo balance adjustement is defined as a fraction of the camera near distance.

void	setStereoMode (StereoMode mode)
	Sets the stereo mode.

StereoMode	getStereoMode () const
	Queries the stereo mode.

SbBool	equals (const SbViewVolume &v, float tolerance)
	Equality comparison within given tolerance.

Static Public Member Functions
static SbBox3f	getProjectedBbox (const SbMatrix &affineProj, const SbBox3f &box)
	Same as getProjectedBbox but takes a matrix (containing affine and projection parts) to use instead of the one returned by getMatrix.

Detailed Description

3D viewing volume class.

Class used to represent a 3D viewing volume. This class is used to represent viewing frusta and picking volumes. For perspective projection, the view volume is a frustum. For orthographic (parallel) projection, the view volume is a rectangular prism.

The view volume used for rendering can be queried from an SoCamera node using its getViewVolume() method.

Member Enumeration Documentation

◆ ProjectionType

enum SbViewVolume::ProjectionType

Projection type.

Enumerator
ORTHOGRAPHIC	Orthographic projection.
PERSPECTIVE	Perspective projection.

Definition at line 303 of file SbViewVolume.h.

◆ StereoMode

enum SbViewVolume::StereoMode

Stereo Modes.

Enumerator
MONOSCOPIC	Monoscopic (i.e., non-stereo) viewing.
LEFT_VIEW	Left eye view.
RIGHT_VIEW	Right eye view.

Definition at line 436 of file SbViewVolume.h.

Constructor & Destructor Documentation

◆ SbViewVolume()

SbViewVolume::SbViewVolume ( )

Default constructor.

The view volume is not initialized.

◆ ~SbViewVolume()

SbViewVolume::~SbViewVolume ( )

inline

Destructor.

Definition at line 90 of file SbViewVolume.h.

Member Function Documentation

◆ equals()

SbBool SbViewVolume::equals	(	const SbViewVolume &	v,
		float	tolerance
	)

Equality comparison within given tolerance.

◆ getAlignRotation()

SbRotation SbViewVolume::getAlignRotation ( SbBool rightAngleOnly = FALSE ) const

Returns a rotation that would align a viewed object so that its positive x-axis (of its object space) is to the right in the view and its positive y-axis is up.

If rightAngleOnly is TRUE, it will come as close as it can to this goal by using only 90 degree rotations.

◆ getBalanceAdjustment()

float SbViewVolume::getBalanceAdjustment ( ) const

inline

Queries the parallax balance.

Definition at line 643 of file SbViewVolume.h.

◆ getCameraSpaceMatrix()

SbMatrix SbViewVolume::getCameraSpaceMatrix ( ) const

Returns a matrix that transforms the view volume into camera space: it translates the view volume so the viewpoint is at the origin, and rotates it so the view direction is along the negative z axis.

◆ getDepth()

float SbViewVolume::getDepth ( ) const

inline

Returns depth of viewing frustum.

Definition at line 347 of file SbViewVolume.h.

◆ getHeight()

float SbViewVolume::getHeight ( ) const

inline

Returns height of viewing frustum.

Definition at line 342 of file SbViewVolume.h.

◆ getMatrices()

float SbViewVolume::getMatrices	(	SbMatrix &	affine,
		SbMatrix &	proj
	)		const

Returns two matrices corresponding to the view volume.

The first is a viewing matrix, which is guaranteed to be an affine transformation. The second is suitable for use as a projection matrix in OpenGL. The return value is the stereo offset for a camera.

Prior to release 2.6, the return value was a void, not a float.

◆ getMatrix()

SbMatrix SbViewVolume::getMatrix ( ) const

Like the method above, but returns the affine and projection parts together in one matrix (i.e., affine.multRight(proj) ).

Note that this matrix transforms world coordinates into normalized clip space, -1 to 1, not directly to normalized screen coordinates, 0 to 1. To convert the result to normalized screen coordinates: dst = dst * 0.5f + SbVec3f(0.5f,0.5f,0.5f);

◆ getNearDist()

float SbViewVolume::getNearDist ( ) const

inline

Returns distance from projection point to near plane.

Definition at line 332 of file SbViewVolume.h.

◆ getPlane()

SbPlane SbViewVolume::getPlane ( float distFromEye ) const

Returns a plane parallel to the near (or far) plane of the view volume at a given distance from the projection point (eye).

◆ getPlanePoint()

SbVec3f SbViewVolume::getPlanePoint	(	float	distFromEye,
		const SbVec2f &	normPoint
	)		const

Maps a 2D point in normalized screen coordinates (0 <= x,y <= 1) to a 3D world coordinates point on the plane parallel to the near plane that is at distFromEye units from the eye.

(See also projectFromScreen().)

◆ getProjectedBbox() [1/2]

SbBox3f SbViewVolume::getProjectedBbox ( const SbBox3f & box ) const

Projects the given 3D bounding box onto the near plane and returns it (in normalized screen coordinates).

◆ getProjectedBbox() [2/2]

static SbBox3f SbViewVolume::getProjectedBbox	(	const SbMatrix &	affineProj,
		const SbBox3f &	box
	)

static

Same as getProjectedBbox but takes a matrix (containing affine and projection parts) to use instead of the one returned by getMatrix.

◆ getProjectionDirection()

const SbVec3f & SbViewVolume::getProjectionDirection ( ) const

inline

Returns projection direction.

Definition at line 327 of file SbViewVolume.h.

◆ getProjectionPoint()

const SbVec3f & SbViewVolume::getProjectionPoint ( ) const

inline

Returns projection point.

Definition at line 322 of file SbViewVolume.h.

◆ getProjectionType()

ProjectionType SbViewVolume::getProjectionType ( ) const

inline

Returns projection type.

Definition at line 317 of file SbViewVolume.h.

◆ getSightPoint()

SbVec3f SbViewVolume::getSightPoint ( float distFromEye ) const

Returns the point along the line of sight at the given distance from the projection point (eye).

◆ getStereoAdjustment()

float SbViewVolume::getStereoAdjustment ( ) const

inline

Queries the stereo offset.

Definition at line 630 of file SbViewVolume.h.

◆ getStereoMode()

StereoMode SbViewVolume::getStereoMode ( ) const

inline

Queries the stereo mode.

Definition at line 459 of file SbViewVolume.h.

◆ getWidth()

float SbViewVolume::getWidth ( ) const

inline

Returns width of viewing frustum.

Definition at line 337 of file SbViewVolume.h.

◆ getWorldToScreenScale()

float SbViewVolume::getWorldToScreenScale	(	const SbVec3f &	worldCenter,
		float	normRadius
	)		const

Returns a scale factor that would scale a unit sphere centered at worldCenter so that it would appear to have the given radius in normalized screen coordinates when projected onto the near plane.

◆ isBalanceNearFraction()

SbBool SbViewVolume::isBalanceNearFraction ( ) const

inline

Returns TRUE if the stereo balance adjustement is defined as a fraction of the camera near distance.

Definition at line 649 of file SbViewVolume.h.

◆ isStereoAbsoluteAdjustments()

SbBool SbViewVolume::isStereoAbsoluteAdjustments ( ) const

inline

Returns TRUE if the stereo adjustments are absolute.

Definition at line 618 of file SbViewVolume.h.

◆ narrow() [1/2]

SbViewVolume SbViewVolume::narrow ( const SbBox3f & box ) const

Narrows a view volume by the given box.

The box must lie inside the unit cube, and the view will be shrunk according to the size of the box.

◆ narrow() [2/2]

SbViewVolume SbViewVolume::narrow	(	float	left,
		float	bottom,
		float	right,
		float	top
	)		const

Given a view volume, narrows the view to the given sub-rectangle of the near plane.

The coordinates of the rectangle are between 0 and 1, where (0,0) is the lower-left corner of the near plane and (1,1) is the upper-right corner.

◆ ortho()

void SbViewVolume::ortho	(	float	left,
		float	right,
		float	bottom,
		float	top,
		float	nearPlane,
		float	farPlane
	)

Sets up an orthographic view volume with the given sides.

The parameters are the same as for the OpenGL glOrtho() routine.

◆ perspective()

void SbViewVolume::perspective	(	float	fovy,
		float	aspect,
		float	nearPlane,
		float	farPlane
	)

Sets up a perspective view volume with the given field of view and aspect ratio.

The parameters are the same as for the OpenGLgluPerspective() routine, except that the field of view angle is specified in radians.

◆ projectBox()

SbVec2f SbViewVolume::projectBox ( const SbBox3f & box ) const

Projects the given 3D bounding box onto the near plane and returns the size (in normalized screen coordinates) of the rectangular region that encloses it.

◆ projectFromScreen()

void SbViewVolume::projectFromScreen	(	const SbVec3f &	src,
		SbVec3f &	dst
	)		const

Maps a 3D point in normalized screen coordinates (0 <= x,y,z <= 1) to a 3D world point.

The resulting Z coordinate represents the normalized distance at which the point would be back projected, ranging from 0 at the near clipping plane to 1 at the far clipping plane. This method is simply the inverse of projectToScreen(). See also getPlanePoint().

Note: This is a convenience function that calls the getMatrix() method and apply inverse() on it, then transforms the point. The getMatrix() and inverse() calls are somewhat expensive, so if you need to project a large number of points you should call the getMatrix() and inverse() methods just once and apply the matrix to each point using SbMatrix::multVecMatrix().

◆ projectPointToLine() [1/2]

void SbViewVolume::projectPointToLine	(	const SbVec2f &	pt,
		SbLine &	line
	)		const

Maps a 2D point (in 0 <= x,y <= 1) to a 3D line.

◆ projectPointToLine() [2/2]

void SbViewVolume::projectPointToLine	(	const SbVec2f &	pt,
		SbVec3f &	line0,
		SbVec3f &	line1
	)		const

Maps a 2D point (in 0 <= x,y <= 1) to a 3D line.

◆ projectToScreen()

void SbViewVolume::projectToScreen	(	const SbVec3f &	src,
		SbVec3f &	dst
	)		const

Maps a 3D point in world coordinates to a 2D point in normalized screen coordinates (0 <= x,y,z <= 1).

The resulting Z screen coordinate represents the homogeneous Z coordinate which goes (nonlinearly) from 0 at the near clipping plane to 1 at the far clipping plane.

NOTE: This is a convenience function that calls the getMatrix() method, then transforms the point. The getMatrix() call is somewhat expensive, so if you need to project a large number of points you should call the getMatrix() method just once and apply the matrix to each point using SbMatrix::multVecMatrix().
However be aware that this matrix transforms world coordinates into normalized clip space, -1 to 1, not directly to normalized screen coordinates, 0 to 1. To convert the result to normalized screen coordinates: dst = dst * 0.5f + SbVec3f(0.5f,0.5f,0.5f);

◆ rotateCamera()

void SbViewVolume::rotateCamera ( const SbRotation & q )

Rotate the camera view direction.

Note that this accomplishes the reverse of doing an OpenGL glRotate() command after defining a camera, which rotates the scene viewed by the camera.

◆ scale()

void SbViewVolume::scale ( float factor )

Scales width and height of view volume by given factor.

◆ scaleHeight()

void SbViewVolume::scaleHeight ( float ratio )

Scales view volume to be the given ratio of its current height, leaving the resulting view volume centered about the same point (in the near plane) as the current one.

◆ scaleWidth()

void SbViewVolume::scaleWidth ( float ratio )

Scales view volume to be the given ratio of its current width, leaving the resulting view volume centered about the same point (in the near plane) as the current one.

◆ setBalanceAdjustment()

void SbViewVolume::setBalanceAdjustment	(	float	adjustment,
		SbBool	nearFrac = `false`
	)

inline

Sets the stereo balance (the position of the zero parallax plane) and specifies whether the balance value is defined as a fraction of the camera near distance.

Note: Since the projection matrix always depends on the camera's near plane, in some cases it may be necessary to detect changes to the camera near plane and adjust by setting a new stereo balance value. Open Inventor will make these adjustments automatically if the nearFrac parameter is set to TRUE. In this case the stereo balance value is defined as a fraction of the camera near distance.

Default balance is 1.0. The default can be set using the OIV_STEREO_BALANCE environment variable. Default nearFrac is FALSE. The default can be set using the OIV_STEREO_BALANCE_NEAR_FRAC environment variable.

Definition at line 636 of file SbViewVolume.h.

◆ setStereoAbsoluteAdjustments()

void SbViewVolume::setStereoAbsoluteAdjustments ( SbBool absolute )

inline

Specifies if stereo adjustments are absolute.

FALSE by default.

The default non-absolute mode allows the stereo settings to be valid over a range of different view volume settings. If you chose absolute mode, you are responsible for modifying the stereo settings (if necessary) when the view volume changes.

When absolute mode is TRUE, stereo offset and balance for the right eye view are used as in the following pseudo-code:

StereoCameraOffset = getStereoAdjustment();
FrustumAsymmetry   = getBalanceAdjustment();
 
glTranslated (-StereoCameraOffset, 0, 0);
glFrustum (FrustumLeft + FrustumAsymmetry, FrustumRight + FrustumAsymmetry,
           FrustumBottom, FrustumTop, NearClipDistance, FarClipDistance);

The left eye view is symmetric.

When absolute mode is FALSE, stereo offset and balance for the right eye view are used as in the following pseudo-code:

Xrange is right minus left (i.e., first two arguments of glFrustum) and multiply that difference by the ratio of the distance to the desired plane of zero parallax to the near clipping plane distance.

StereoCameraOffset   = Xrange * 0.035 * getStereoAdjustment();
FrustumAsymmetry     = -StereoCameraOffset * getBalanceAdjustment();
ZeroParallaxDistance = (NearClipDistance + FarClipDistance)/0.5;
 
FrustumAsymmetry *= NearClipDistance / ZeroParallaxDistance;
 
glTranslated (-StereoCameraOffset, 0, 0);
glFrustum (FrustumLeft + FrustumAsymmetry, FrustumRight + FrustumAsymmetry,
           FrustumBottom, FrustumTop, NearClipDistance, FarClipDistance);

The left eye view is symmetric.

Definition at line 655 of file SbViewVolume.h.

◆ setStereoAdjustment()

void SbViewVolume::setStereoAdjustment ( float adjustment )

inline

Sets the stereo offset (the distance of each eye from the camera position).

The right eye is moved plus offset and the left eye is moved minus offset. Default is 0.7. The default can be set using OIV_STEREO_OFFSET environment variable.

Definition at line 624 of file SbViewVolume.h.

◆ setStereoMode()

void SbViewVolume::setStereoMode ( StereoMode mode )

inline

Sets the stereo mode.

Definition at line 454 of file SbViewVolume.h.

◆ translateCamera()

void SbViewVolume::translateCamera ( const SbVec3f & v )

Translate the camera viewpoint.

Note that this accomplishes the reverse of doing an OpenGL glTranslate() command after defining a camera, which translates the scene viewed by the camera.

◆ zNarrow()

SbViewVolume SbViewVolume::zNarrow	(	float	nearPlane,
		float	farPlane
	)		const

Returns a narrowed view volume which contains as tightly as possible the given interval on the z axis (in eye space).

The returned view volume will never be larger than the current volume, however. near and far are given in terms of zVector(): this means that near > far must hold.

◆ zVector()

SbVec3f SbViewVolume::zVector ( ) const

Returns the positive z axis in eye space.

In this coordinate system, the z value of the near plane should be greater than the z value of the far plane.

The documentation for this class was generated from the following file:

Inventor/SbViewVolume.h

Open Inventor Release 2023.2.3

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

SEE ALSO

Member Enumeration Documentation

◆ ProjectionType

◆ StereoMode

Constructor & Destructor Documentation

◆ SbViewVolume()

◆ ~SbViewVolume()

Member Function Documentation

◆ equals()

◆ getAlignRotation()

◆ getBalanceAdjustment()

◆ getCameraSpaceMatrix()

◆ getDepth()

◆ getHeight()

◆ getMatrices()

◆ getMatrix()

◆ getNearDist()

◆ getPlane()

◆ getPlanePoint()

◆ getProjectedBbox() [1/2]

◆ getProjectedBbox() [2/2]

◆ getProjectionDirection()

◆ getProjectionPoint()

◆ getProjectionType()

◆ getSightPoint()

◆ getStereoAdjustment()

◆ getStereoMode()

◆ getWidth()

◆ getWorldToScreenScale()

◆ isBalanceNearFraction()

◆ isStereoAbsoluteAdjustments()

◆ narrow() [1/2]

◆ narrow() [2/2]

◆ ortho()

◆ perspective()

◆ projectBox()

◆ projectFromScreen()

◆ projectPointToLine() [1/2]

◆ projectPointToLine() [2/2]

◆ projectToScreen()

◆ rotateCamera()

◆ scale()

◆ scaleHeight()

◆ scaleWidth()

◆ setBalanceAdjustment()

◆ setStereoAbsoluteAdjustments()

◆ setStereoAdjustment()

◆ setStereoMode()

◆ translateCamera()

◆ zNarrow()

◆ zVector()