Class SbViewVolume
 java.lang.Object

 com.openinventor.inventor.Inventor

 com.openinventor.inventor.SbViewVolume

public class SbViewVolume extends Inventor
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. See Also:
SbVec3f
,SbVec2f
,SbBox3f
,SbMatrix
,SbRotation
,SoViewVolumeElement


Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SbViewVolume.Matrices
static class
SbViewVolume.ProjectionTypes
Projection type.static class
SbViewVolume.StereoModes
Stereo Modes.
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand


Field Summary

Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle


Constructor Summary
Constructors Constructor Description SbViewVolume()
Default constructor.SbViewVolume(SbViewVolume copyFrom)

Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
equals(SbViewVolume v, float tolerance)
Equality comparison within given tolerance.SbRotation
getAlignRotation()
Calls getAlignRotation(false).SbRotation
getAlignRotation(boolean rightAngleOnly)
Returns a rotation that would align a viewed object so that its positive xaxis (of its object space) is to the right in the view and its positive yaxis is up.float
getBalanceAdjustment()
Queries the parallax balance.SbMatrix
getCameraSpaceMatrix()
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.float
getDepth()
Returns depth of viewing frustum.float
getHeight()
Returns height of viewing frustum.SbViewVolume.Matrices
getMatrices()
Returns two matrices corresponding to the view volume.SbMatrix
getMatrix()
Like the method above, but returns the affine and projection parts together in one matrix (i.e., affine.multRight(proj) ).float
getNearDist()
Returns distance from projection point to near plane.SbPlane
getPlane(float distFromEye)
Returns a plane parallel to the near (or far) plane of the view volume at a given distance from the projection point (eye).SbVec3f
getPlanePoint(float distFromEye, SbVec2f normPoint)
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.SbBox3f
getProjectedBbox(SbBox3f box)
Projects the given 3D bounding box onto the near plane and returns it (in normalized screen coordinates).SbBox3f
getProjectedBbox(SbMatrix affineProj, SbBox3f box)
Same as getProjectedBbox but takes a matrix (containing affine and projection parts) to use instead of the one returned by getMatrix.SbVec3f
getProjectionDirection()
Returns projection direction.SbVec3f
getProjectionPoint()
Returns projection point.SbViewVolume.ProjectionTypes
getProjectionType()
Returns projection type.SbVec3f
getSightPoint(float distFromEye)
Returns the point along the line of sight at the given distance from the projection point (eye).float
getStereoAdjustment()
Queries the stereo offset.SbViewVolume.StereoModes
getStereoMode()
Queries the stereo mode.float
getWidth()
Returns width of viewing frustum.float
getWorldToScreenScale(SbVec3f worldCenter, float normRadius)
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.boolean
isBalanceNearFraction()
Returns true if the stereo balance adjustement is defined as a fraction of the camera near distance.boolean
isStereoAbsoluteAdjustments()
Returns true if the stereo adjustments are absolute.SbViewVolume
narrow(float left, float bottom, float right, float top)
Given a view volume, narrows the view to the given subrectangle of the near plane.SbViewVolume
narrow(SbBox3f box)
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.SbVec2f
projectBox(SbBox3f box)
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.SbVec3f
projectFromScreen(SbVec3f src)
Maps a 3D point in normalized screen coordinates (0 <= x,y,z <= 1) to a 3D world point.SbLine
projectPointToLine(SbVec2f pt)
Maps a 2D point (in 0 <= x,y <= 1) to a 3D line.SbVec3f
projectToScreen(SbVec3f src)
Maps a 3D point in world coordinates to a 2D point in normalized screen coordinates (0 <= x,y,z <= 1).void
rotateCamera(SbRotation q)
Rotate the camera view direction.void
scale(float factor)
Scales width and height of view volume by given factor.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.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
setBalanceAdjustment(float adjustment)
Calls setBalanceAdjustment(adjustment, (boolean)false).void
setBalanceAdjustment(float adjustment, boolean nearFrac)
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.void
setStereoAbsoluteAdjustments(boolean absolute)
Specifies if stereo adjustments are absolute.void
setStereoAdjustment(float adjustment)
Sets the stereo offset (the distance of each eye from the camera position).void
setStereoMode(SbViewVolume.StereoModes mode)
Sets the stereo mode.void
setValue(SbViewVolume copyFrom)
static SbViewVolume[]
toArray(long nativeArray, long length)
void
translateCamera(SbVec3f v)
Translate the camera viewpoint.SbViewVolume
zNarrow(float nearPlane, float farPlane)
Returns a narrowed view volume which contains as tightly as possible the given interval on the z axis (in eye space).SbVec3f
zVector()
Returns the positive z axis in eye space.
Methods inherited from class com.openinventor.inventor.Inventor
dispose, getNativeResourceHandle




Constructor Detail

SbViewVolume
public SbViewVolume(SbViewVolume copyFrom)

SbViewVolume
public SbViewVolume()
Default constructor. The view volume is not initialized.


Method Detail

getAlignRotation
public SbRotation getAlignRotation()
Calls getAlignRotation(false).

setBalanceAdjustment
public void setBalanceAdjustment(float adjustment)
Calls setBalanceAdjustment(adjustment, (boolean)false).

equals
public boolean equals(SbViewVolume v, float tolerance)
Equality comparison within given tolerance.

getMatrices
public SbViewVolume.Matrices getMatrices()
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.

setValue
public void setValue(SbViewVolume copyFrom)

narrow
public SbViewVolume narrow(float left, float bottom, float right, float top)
Given a view volume, narrows the view to the given subrectangle of the near plane. The coordinates of the rectangle are between 0 and 1, where (0,0) is the lowerleft corner of the near plane and (1,1) is the upperright corner.

toArray
public static SbViewVolume[] toArray(long nativeArray, long length)

narrow
public SbViewVolume narrow(SbBox3f box)
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.

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

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

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

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

zVector
public SbVec3f zVector()
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.

getProjectionDirection
public SbVec3f getProjectionDirection()
Returns projection direction.

getWorldToScreenScale
public float getWorldToScreenScale(SbVec3f worldCenter, float normRadius)
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.

getHeight
public float getHeight()
Returns height of viewing frustum.

translateCamera
public void translateCamera(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.

getWidth
public float getWidth()
Returns width of viewing frustum.

projectFromScreen
public SbVec3f projectFromScreen(SbVec3f src)
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 ofprojectToScreen()
. See alsogetPlanePoint()
.Note: This is a convenience function that calls the
getMatrix()
method and apply inverse() on it, then transforms the point. ThegetMatrix()
and inverse() calls are somewhat expensive, so if you need to project a large number of points you should call thegetMatrix()
and inverse() methods just once and apply the matrix to each point usingSbMatrix.multVecMatrix()
.

scaleWidth
public 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.

getPlanePoint
public SbVec3f getPlanePoint(float distFromEye, SbVec2f normPoint)
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 alsoprojectFromScreen()
.)

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

getAlignRotation
public SbRotation getAlignRotation(boolean rightAngleOnly)
Returns a rotation that would align a viewed object so that its positive xaxis (of its object space) is to the right in the view and its positive yaxis is up. If rightAngleOnly is true, it will come as close as it can to this goal by using only 90 degree rotations.

scaleHeight
public 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.

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

getProjectionPoint
public SbVec3f getProjectionPoint()
Returns projection point.

zNarrow
public SbViewVolume zNarrow(float nearPlane, float farPlane)
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 ofzVector()
: this means that near > far must hold.

getProjectionType
public SbViewVolume.ProjectionTypes getProjectionType()
Returns projection type.

getBalanceAdjustment
public float getBalanceAdjustment()
Queries the parallax balance.

perspective
public 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. The parameters are the same as for the OpenGLgluPerspective() routine, except that the field of view angle is specified in radians.

setBalanceAdjustment
public void setBalanceAdjustment(float adjustment, boolean nearFrac)
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.

getCameraSpaceMatrix
public SbMatrix getCameraSpaceMatrix()
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.

isBalanceNearFraction
public boolean isBalanceNearFraction()
Returns true if the stereo balance adjustement is defined as a fraction of the camera near distance.

ortho
public void 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.

getStereoMode
public SbViewVolume.StereoModes getStereoMode()
Queries the stereo mode.

getMatrix
public SbMatrix getMatrix()
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.multiply(0.5f); dst.plus(newSbVec3f
(0.5f,0.5f,0.5f));

setStereoMode
public void setStereoMode(SbViewVolume.StereoModes mode)
Sets the stereo mode.

setStereoAbsoluteAdjustments
public void setStereoAbsoluteAdjustments(boolean absolute)
Specifies if stereo adjustments are absolute. false by default.The default nonabsolute 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 pseudocode:
StereoCameraOffset = getStereoAdjustment(); FrustumAsymmetry = getBalanceAdjustment(); glTranslated (StereoCameraOffset, 0, 0); glFrustum (FrustumLeft + FrustumAsymmetry, FrustumRight + FrustumAsymmetry, FrustumBottom, FrustumTop, NearClipDistance, FarClipDistance); When absolute mode is false, stereo offset and balance for the right eye view are used as in the following pseudocode:
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);

isStereoAbsoluteAdjustments
public boolean isStereoAbsoluteAdjustments()
Returns true if the stereo adjustments are absolute.

getDepth
public float getDepth()
Returns depth of viewing frustum.

projectToScreen
public SbVec3f projectToScreen(SbVec3f src)
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. ThegetMatrix()
call is somewhat expensive, so if you need to project a large number of points you should call thegetMatrix()
method just once and apply the matrix to each point usingSbMatrix.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.multiply(0.5f); dst.plus(newSbVec3f
(0.5f,0.5f,0.5f));

rotateCamera
public void rotateCamera(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.

getStereoAdjustment
public float getStereoAdjustment()
Queries the stereo offset.

projectBox
public SbVec2f projectBox(SbBox3f box)
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.

setStereoAdjustment
public void setStereoAdjustment(float adjustment)
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.

