SoVRMLViewpoint Class Reference
[VRML97 nodes]

Specifies position from which the user might view the scene. More...

#include <Inventor/VRMLnodes/SoVRMLViewpoint.h>

Inheritance diagram for SoVRMLViewpoint:

List of all members.

Public Member Functions
virtual SoType	getTypeId () const
	SoVRMLViewpoint ()
Static Public Member Functions
static SoType	getClassTypeId ()
Public Attributes
SoSFVec3f	position
SoSFRotation	orientation
SoSFFloat	fieldOfView
SoSFString	description
SoSFBool	jump
SoSFVec3f	centerOfRotation
SoSFBool	set_bind
SoSFTime	bindTime
SoSFBool	isBound

---

Detailed Description

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.

NOTE: 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:


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.

---

Constructor & Destructor Documentation

SoVRMLViewpoint::SoVRMLViewpoint

(

)

Constructor.

---

Member Function Documentation

static SoType SoVRMLViewpoint::getClassTypeId

(

)

[static]

Returns the type identifier for this class.

Reimplemented from SoVRMLNode.

Reimplemented in SoVRMLGeoViewpoint.

virtual SoType SoVRMLViewpoint::getTypeId

(

)

const [virtual]

Returns the type identifier for this specific instance.

Reimplemented from SoVRMLNode.

Reimplemented in SoVRMLGeoViewpoint.

---

Member Data Documentation

SoSFTime SoVRMLViewpoint::bindTime

OutputEvent.

SoSFVec3f SoVRMLViewpoint::centerOfRotation

(Note: Not implemented) Specifies a center about which to rotate the users eyepoint when in EXAMINE mode. NOTE: field available 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.

SoSFString SoVRMLViewpoint::description

Specifies viewpoints that are recommended to be publicly accessible.

SoSFFloat SoVRMLViewpoint::fieldOfView

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.

SoSFBool SoVRMLViewpoint::isBound

OutputEvent.

SoSFBool SoVRMLViewpoint::jump

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

SoSFRotation SoVRMLViewpoint::orientation

Specifies a rotation relative to the default orientation.

SoSFVec3f SoVRMLViewpoint::position

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

SoSFBool SoVRMLViewpoint::set_bind

Input event.

---

The documentation for this class was generated from the following file:
• Inventor/VRMLnodes/SoVRMLViewpoint.h