com.openinventor.inventor.vrmlnodes

Class SoVRMLViewpoint

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.misc.SoBase

com.openinventor.inventor.fields.SoFieldContainer

com.openinventor.inventor.nodes.SoNode

com.openinventor.inventor.vrmlnodes.SoVRMLNode

com.openinventor.inventor.vrmlnodes.SoVRMLViewpoint

All Implemented Interfaces:

SafeDisposable

Direct Known Subclasses:

SoVRMLGeoViewpoint

Deprecated.

As of Open Inventor 9500 See documentation for more details

public class SoVRMLViewpoint
extends SoVRMLNode

Specifies position from which the user might view the scene. The SoVRMLViewpoint node defines a specific location in a local coordinate system from which the user might view the scene.

<font color="#0000FF">NOTE:</font> This class does not exist in Open Inventor 10.0 and later.

Note: The binding behavior and associated eventIns and eventOuts are not implemented.

VRML97 SPECIFICATION

This section describes the expected behavior of the node in a conforming VRML97 browser application. In some cases, the application is responsible for implementing portions of the expected behavior. Open Inventor viewer classes and IVF classes implement some of the application behaviors.

This section may reference portions of the VRML97 specification that are not present in this help file. The complete VRML97 spec is available at http://www.web3d.org.

The SoVRMLViewpoint node defines a specific location in a local coordinate system from which the user might view the scene. SoVRMLViewpoints are bindable children nodes and thus there exists an SoVRMLViewpoint stack in the browser in which the top-most SoVRMLViewpoint on the stack is the currently active SoVRMLViewpoint. If a true value is sent to the set_bind eventIn of an SoVRMLViewpoint, it is moved to the top of the SoVRMLViewpoint stack and thus activated. When an SoVRMLViewpoint is at the top of the stack, the user's view is conceptually reparented as a child of the SoVRMLViewpoint. All subsequent changes to the SoVRMLViewpoint's coordinate system change the user's view (e.g. changes to any parent transformation nodes or to the SoVRMLViewpoint's position or orientation fields). Sending a set_bind false event removes the SoVRMLViewpoint from the stack and results in isBound false and bindTime events. If the popped SoVRMLViewpoint is at the top of the viewpoint stack the user's view is reparented to the next entry in the stack. See "Concepts - Bindable Children Nodes" for more details on the the binding stacks. When an SoVRMLViewpoint is moved to the top of the stack, the existing top of stack Viewpoint sends an isBound false event and is pushed onto the stack.

SoVRMLViewpoints have the additional requirement from other binding nodes in that they store the relative transformation from the user view to the current SoVRMLViewpoint when they are moved to the top of stack. This is needed by the jump field, described below.

An author can automatically move the user's view through the world by binding the user to an SoVRMLViewpoint and then animating either the SoVRMLViewpoint or the transformations above it. Browsers must allow the user view to be navigated relative to the coordinate system defined by the SoVRMLViewpoint (and the transformations above it), even if the SoVRMLViewpoint or its parent transformations are being animated.

The bindTime eventOut sends the time at which the SoVRMLViewpoint is bound or unbound. This can happen during loading, when a set_bind event is sent to the SoVRMLViewpoint, or when the browser binds to the SoVRMLViewpoint via its user interface (see below).

The position and orientation fields of the SoVRMLViewpoint node specify relative locations in the local coordinate system. Position is relative to the coordinate system's origin (0,0,0), while orientation specifies a rotation relative to the default orientation; the default orientation has the user looking down the -Z axis with +X to the right and +Y straight up. SoVRMLViewpoints are affected by the transformation hierarchy.

Navigation types (see SoVRMLNavigationInfo) that require a definition of a down vector (e.g. terrain following) will use the negative Y-axis of the coordinate system of the currently bound SoVRMLViewpoint. Likewise navigation types (see SoVRMLNavigationInfo) that require a definition of an up vector will use the positive Y-axis of the coordinate system of the currently bound SoVRMLViewpoint. Note that the orientation field of the SoVRMLViewpoint does not affect the definition of the down or up vectors. This allows the author to separate the viewing direction from the gravity direction.

The jump field specifies whether the user's view `jumps' (or animates) to the position and orientation of a bound SoVRMLViewpoint. Regardless of the value of jump at bind time, the relative viewing transformation between the user's view and the current SoVRMLViewpoint will be stored with the current SoVRMLViewpoint for later use when un-jumping . The following is a re-write of the general bind stack rules described in "Concepts - Bindable Child Nodes, Bind Stack Behavior" with additional rules regarding Viewpoints (in bold ):

1. During read:
   • the first encountered SoVRMLViewpoint is bound by pushing it to the top of the SoVRMLViewpoint stack,
     • nodes contained within SoVRMLInline are not candidates for the first encountered SoVRMLViewpoint,
     • the first node within a prototype is a valid candidate for the first encountered SoVRMLViewpoint
   • the first encountered SoVRMLViewpoint sends an isBound true event.
2. When a set_bind true eventIn is received by an SoVRMLViewpoint:
   • if it is not on the top of the stack:
     • the relative transformation from the current top of stack SoVRMLViewpoint to the user's view is stored with the current top of stack SoVRMLViewpoint,
     • the current top of stack node sends an isBound eventOut false,
     • the new node is moved to the top of the stack and becomes the currently bound SoVRMLViewpoint,
     • the new SoVRMLViewpoint (top of stack) sends an isBound true eventOut,
     • if jump is true for the new SoVRMLViewpoint, then the user's view is `jumped' (or animated) to match the values in the position and orientation fields of the new SoVRMLViewpoint;
   • else if the node is already at the top of the stack, then this event has no effect.
3. When a set_bind false eventIn is received by an SoVRMLViewpoint:
   • it is removed from the stack,
   • if it is on the top of the stack:
     • it sends an isBound eventOut false,
     • the next node in the stack becomes the currently bound SoVRMLViewpoint (i.e., pop) and issues an isBound true eventOut,
     • if its jump is true the user's view is 'jumped' (or animated) to the position and orientation of the next SoVRMLViewpoint in the stack with the stored relative transformation for with this next SoVRMLViewpoint applied,
4. If a set_bind false eventIn is received by a node not in the stack, the event is ignored and isBound events are not sent.
5. When a node replaces another node at the top of the stack, the isBound true and false eventOuts from the two nodes are sent simultaneously (i.e., identical timestamps).
6. If a bound node is deleted then it behaves as if it received a set_bind false event (see #3).

Note that the jump field may change after an SoVRMLViewpoint is bound - the rules described above still apply. If jump was true when the SoVRMLViewpoint is bound, but changed to false before the set_bind false is sent, then the SoVRMLViewpoint does not un-jump during unbind. If jump was false when the SoVRMLViewpoint is bound, but changed to true before the set_bind false is sent, then the SoVRMLViewpoint does perform the un-jump during unbind.

The fieldOfView field specifies a preferred field of view from this viewpoint, in radians. A small field of view roughly corresponds to a telephoto lens; a large field of view roughly corresponds to a wide-angle lens. The field of view should be greater than zero and smaller than pi; the default value corresponds to a 45 degree field of view. The value of fieldOfView represents the maximum viewing angle in any direction axis of the view. For example, a browser with a rectangular viewing projection will use an angle of fieldOfView for the larger direction (depending on aspect ratio) and fieldOfView times aspect ratio in the smaller direction. If the aspect ratio is 2x1 (i.e., horizontal twice the vertical) and the fieldOfView is 1.0, then the horizontal viewing angle would be 1.0 and the vertical viewing angle would be 0.5. fieldOfView is a hint to the browser and may be ignored.

The description field identifies SoVRMLViewpoints that are recommended to be publicly accessible through the browser's user interface (e.g. SoVRMLViewpoints menu). The string in the description field should be displayed if this functionality is implemented. If description is empty, then the SoVRMLViewpoint should not appear in any public user interface. It is recommended that the browser bind and move to an SoVRMLViewpoint when its description is selected, either animating to the new position or jumping directly there. Once the new position is reached both the isBound and bindTime eventOuts are sent.

The URL syntax ".../scene.wrl#ViewpointName" specifies the user's initial view when entering "scene.wrl" to be the first SoVRMLViewpoint in file "scene.wrl" that appears as "DEF ViewpointName Viewpoint { ... }" - this overrides the first SoVRMLViewpoint in the file as the initial user view and receives a set_bind true message. If the SoVRMLViewpoint "ViewpointName" is not found, then assume that no SoVRMLViewpoint was specified and use the first SoVRMLViewpoint in the file. The URL syntax "#ViewpointName" specifies a view within the existing file. If this is loaded, then it receives a set_bind true message.

If an SoVRMLViewpoint is bound ( set_bind ) and is the child of an SoVRMLLOD, SoVRMLSwitch, or any node or prototype that disables its children, then the result is undefined. If an SoVRMLViewpoint is bound that results in collision with geometry, then the browser performs its self-defined navigation adjustments as if the user navigated to this point (see SoVRMLCollision).

File format/default:

Viewpoint {

fieldOfView	0.785398
jump	true
orientation	0 0 1 0
position	0 0 10
centerOfRotation	0 0 0
description	""
metadata	NULL

}

EVENTS

eventIn

SoSFBool	set_bind (Note: Not implemented)
SoSFFloat	set_fieldOfView
SoSFBool	set_jump (Note: Not implemented)
SoSFRotation	set_orientation
SoSFVec3f	set_position
SoSFVec3f	set_centerOfRotation (Note: Not implemented)
SoSFString	set_description
SoSFNode	set_metadata

eventOut

SoSFTime	bindTime (Note: Not implemented)
SoSFBool	isBound (Note: Not implemented)
SoSFFloat	fieldOfView_changed
SoSFBool	jump_changed (Note: Not implemented)
SoSFRotation	orientation_changed
SoSFVec3f	position_changed
SoSFVec3f	centerOfRotation_changed (Note: Not implemented)
SoSFString	description_changed
SoSFNode	metadata_changed

Deprecated since Open Inventor 9500
The VRML API is no longer supported. See section http://oivdoc95.vsg3d.com/content/compatibility-notes-4#Deprecation of the Reference Manual.

Nested Class Summary

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
SoSFTime	bindTime Deprecated. OutputEvent.
SoSFVec3f	centerOfRotation Deprecated. (Note: Not implemented) Specifies a center about which to rotate the users eyepoint when in EXAMINE mode.
SoSFString	description Deprecated. Specifies viewpoints that are recommended to be publicly accessible.
SoSFFloat	fieldOfView Deprecated. Specifies a preferred field of view from the viewpoint, in radians.
SoSFBool	isBound Deprecated. OutputEvent.
SoSFBool	jump Deprecated. (Note: Not implemented) Specifies whether the user's view "jumps" to the position and orientation.
SoSFRotation	orientation Deprecated. Specifies a rotation relative to the default orientation.
SoSFVec3f	position Deprecated. Specifies a position relative to the coordinate system's origin (0,0,0).
SoSFBool	set_bind Deprecated. Input event.

Fields inherited from class com.openinventor.inventor.vrmlnodes.SoVRMLNode

metadata

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoVRMLViewpoint() Deprecated. Constructor.

Method Summary

Methods inherited from class com.openinventor.inventor.nodes.SoNode

affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write

Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer

copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults

Methods inherited from class com.openinventor.inventor.misc.SoBase

dispose, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

position

public final SoSFVec3f position

Deprecated.

Specifies a position relative to the coordinate system's origin (0,0,0).

orientation

public final SoSFRotation orientation

Deprecated.

Specifies a rotation relative to the default orientation.

fieldOfView

public final SoSFFloat fieldOfView

Deprecated.

Specifies a preferred field of view from the viewpoint, in radians. A small field of view roughly corresponds to a telephoto lens; a large field of view roughly corresponds to a wide-angle lens. The field of view should be greater than zero and smaller than pi.

description

public final SoSFString description

Deprecated.

Specifies viewpoints that are recommended to be publicly accessible.

jump

public final SoSFBool jump

Deprecated.

(Note: Not implemented) Specifies whether the user's view "jumps" to the position and orientation.

centerOfRotation

public final SoSFVec3f centerOfRotation

Deprecated.

(Note: Not implemented) Specifies a center about which to rotate the users eyepoint when in EXAMINE mode.

Since:

Open Inventor 5.0 NOTE 2: This field is not compatible with VRML97. If you specify a non-default value for this field, when this node is written to a VRML file, the file will contain this incompatible field and standard VRML97 file readers will not be able to read it.

set_bind

public final SoSFBool set_bind

Deprecated.

Input event.

bindTime

public final SoSFTime bindTime

Deprecated.

OutputEvent.

isBound

public final SoSFBool isBound

Deprecated.

OutputEvent.

Constructor Detail

SoVRMLViewpoint

public SoVRMLViewpoint()

Deprecated.

Constructor.