Coin: SoVRMLViewpoint Class Reference

| Coin3D is Free Software, published under the BSD 3-clause license. | https://coin3d.github.io https://www.kongsberg.com/en/kogt/

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
SoVRMLViewpoint Class Reference
VRML97 Classes

The SoVRMLViewpoint class is a perspective camera class. More...

`#include <Inventor/VRMLnodes/SoVRMLViewpoint.h>`

Inheritance diagram for SoVRMLViewpoint:

## Public Member Functions
virtual SoType | getTypeId (void) const
| SoVRMLViewpoint (void)
virtual void | GLRender (SoGLRenderAction *action)
Public Member Functions inherited from SoNode
void | setOverride (const SbBool state)
SbBool | isOverride (void) const
void | setNodeType (const NodeType type)
NodeType | getNodeType (void) const
virtual SoNode * | copy (SbBool copyconnections=FALSE) const
virtual SbBool | affectsState (void) const
virtual void | doAction (SoAction *action)
virtual void | GLRenderBelowPath (SoGLRenderAction *action)
virtual void | GLRenderInPath (SoGLRenderAction *action)
virtual void | GLRenderOffPath (SoGLRenderAction *action)
virtual void | callback (SoCallbackAction *action)
virtual void | getBoundingBox (SoGetBoundingBoxAction *action)
virtual void | getMatrix (SoGetMatrixAction *action)
virtual void | handleEvent (SoHandleEventAction *action)
virtual void | pick (SoPickAction *action)
virtual void | rayPick (SoRayPickAction *action)
virtual void | search (SoSearchAction *action)
virtual void | write (SoWriteAction *action)
virtual void | audioRender (SoAudioRenderAction *action)
virtual void | getPrimitiveCount (SoGetPrimitiveCountAction *action)
virtual void | grabEventsSetup (void)
virtual void | grabEventsCleanup (void)
virtual void | startNotify (void)
virtual void | notify (SoNotList *l)
SbUniqueId | getNodeId (void) const
virtual SoChildList * | getChildren (void) const
virtual void | writeInstance (SoOutput *out)
virtual SoNode * | addToCopyDict (void) const
virtual void | copyContents (const SoFieldContainer *from, SbBool copyconnections)
virtual SoFieldContainer * | copyThroughConnection (void) const
Public Member Functions inherited from SoFieldContainer
void | setToDefaults (void)
SbBool | hasDefaultValues (void) const
SbBool | fieldsAreEqual (const SoFieldContainer *container) const
void | copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
SbBool | set (const char *const fielddata)
void | get (SbString &fielddata)
virtual int | getFields (SoFieldList &l) const
virtual int | getAllFields (SoFieldList &l) const
virtual SoField * | getField (const SbName &name) const
virtual SoField * | getEventIn (const SbName &name) const
virtual SoField * | getEventOut (const SbName &name) const
SbBool | getFieldName (const SoField *const field, SbName &name) const
SbBool | enableNotify (const SbBool flag)
SbBool | isNotifyEnabled (void) const
SbBool | set (const char *fielddata, SoInput *input)
void | get (SbString &fielddata, SoOutput *out)
virtual SbBool | validateNewFieldValue (SoField *field, void *newval)
virtual void | addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
SbBool | getIsBuiltIn (void) const
virtual void | getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
void | setUserData (void *userdata) const
void * | getUserData (void) const
Public Member Functions inherited from SoBase
void | ref (void) const
void | unref (void) const
void | unrefNoDelete (void) const
int32_t | getRefCount (void) const
void | touch (void)
SbBool | isOfType (SoType type) const
| Returns `TRUE` if the type of this object is either of the same type or inherited from type.
virtual SbName | getName (void) const
virtual void | setName (const SbName &newname)
void | addAuditor (void *const auditor, const SoNotRec::Type type)
void | removeAuditor (void *const auditor, const SoNotRec::Type type)
const SoAuditorList & | getAuditors (void) const
SbBool | shouldWrite (void)
void | assertAlive (void) const

## Static Public Member Functions
static SoType | getClassTypeId (void)
static void | initClass (void)
Static Public Member Functions inherited from SoNode
static uint32_t | getCompatibilityTypes (const SoType &nodetype)
static SoType | getClassTypeId (void)
static SoNode * | getByName (const SbName &name)
static int | getByName (const SbName &name, SoNodeList &l)
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static void | initClasses (void)
static SbUniqueId | getNextNodeId (void)
static int | getActionMethodIndex (const SoType type)
static void | getBoundingBoxS (SoAction *action, SoNode *node)
static void | GLRenderS (SoAction *action, SoNode *node)
static void | callbackS (SoAction *action, SoNode *node)
static void | getMatrixS (SoAction *action, SoNode *node)
static void | handleEventS (SoAction *action, SoNode *node)
static void | pickS (SoAction *action, SoNode *node)
static void | rayPickS (SoAction *action, SoNode *node)
static void | searchS (SoAction *action, SoNode *node)
static void | writeS (SoAction *action, SoNode *node)
static void | audioRenderS (SoAction *action, SoNode *node)
static void | getPrimitiveCountS (SoAction *action, SoNode *node)
Static Public Member Functions inherited from SoFieldContainer
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static SoType | getClassTypeId (void)
| This static method returns the SoType object associated with objects of this class.
static void | cleanupClass (void)
static void | initCopyDict (void)
static void | addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
static SoFieldContainer * | checkCopy (const SoFieldContainer *orig)
static SoFieldContainer * | findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
static void | copyDone (void)
Static Public Member Functions inherited from SoBase
static void | initClass (void)
| Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
static SoType | getClassTypeId (void)
| This static method returns the SoType object associated with objects of this class.
static void | addName (SoBase *const base, const char *const name)
static void | removeName (SoBase *const base, const char *const name)
static void | incrementCurrentWriteCounter (void)
static void | decrementCurrentWriteCounter (void)
static SoBase * | getNamedBase (const SbName &name, SoType type)
static int | getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
static SbBool | read (SoInput *input, SoBase *&base, SoType expectedtype)
static void | setInstancePrefix (const SbString &c)
static void | setTraceRefs (SbBool trace)
static SbBool | getTraceRefs (void)
static SbBool | connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
static SbBool | readRoute (SoInput *input)

## Public Attributes
SoSFVec3f | position
SoSFRotation | orientation
SoSFFloat | fieldOfView
SoSFString | description
SoSFBool | jump
Public Attributes inherited from SoBase

## Protected Member Functions
virtual const SoFieldData * | getFieldData (void) const
virtual | ~SoVRMLViewpoint ()
Protected Member Functions inherited from SoNode
| SoNode (void)
virtual | ~SoNode ()
virtual SbBool | readInstance (SoInput *in, unsigned short flags)
Protected Member Functions inherited from SoFieldContainer
| SoFieldContainer (void)
virtual | ~SoFieldContainer ()
Protected Member Functions inherited from SoBase
| SoBase (void)
virtual | ~SoBase ()
virtual void | destroy (void)
SbBool | hasMultipleWriteRefs (void) const
SbBool | writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
void | writeFooter (SoOutput *out) const
virtual const char * | getFileFormatName (void) const
virtual SoNotRec | createNotRec (void)

## Static Protected Member Functions
static const SoFieldData ** | getFieldDataPtr (void)
Static Protected Member Functions inherited from SoNode
static const SoFieldData ** | getFieldDataPtr (void)
static void | setNextActionMethodIndex (int index)
static int | getNextActionMethodIndex (void)
static void | incNextActionMethodIndex (void)
static void | setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)
Static Protected Member Functions inherited from SoBase
static uint32_t | getCurrentWriteCounter (void)
static void | staticDataLock (void)
static void | staticDataUnlock (void)

## Protected Attributes
SoSFBool | set_bind
SoSFTime | bindTime
SoSFBool | isBound
Protected Attributes inherited from SoNode
SbUniqueId | uniqueId
Protected Attributes inherited from SoFieldContainer
SbBool | isBuiltIn

## Additional Inherited Members
Public Types inherited from SoNode
enum | NodeType { INVENTOR = 0x0000 , VRML1 = 0x0001 , VRML2 = 0x0002 , INVENTOR_1 = 0x0004 , INVENTOR_2_0 = 0x0008 , INVENTOR_2_1 = 0x0010 , INVENTOR_2_5 = 0x0020 , INVENTOR_2_6 = 0x0040 , COIN_1_0 = 0x0080 , COIN_2_0 = 0x0100 , EXTENSION = 0x0200 , COIN_2_2 = 0x0400 , COIN_2_3 = 0x0800 , COIN_2_4 = 0x1000 , INVENTOR_5_0 = 0x2000 , COIN_2_5 = 0x4000 , COIN_3_0 = 0x8000 , INVENTOR_6_0 = 0x10000 , COIN_4_0 = 0x20000 }
Protected Types inherited from SoBase
enum | BaseFlags { IS_ENGINE = 0x01 , IS_GROUP = 0x02 }
Static Protected Attributes inherited from SoNode
static SbUniqueId | nextUniqueId = 1
static int | nextActionMethodIndex = 0

## Detailed Description

The SoVRMLViewpoint class is a perspective camera class.

The detailed class documentation is taken verbatim from the VRML97 standard (ISO/IEC 14772-1:1997). It is copyright The Web3D Consortium, and is used by permission of the Consortium:

    Viewpoint {
      eventIn      SFBool     set_bind
      exposedField SFFloat    fieldOfView    0.785398  # (0,inf)
      exposedField SFBool     jump           TRUE
      exposedField SFRotation orientation    0 0 1 0   # [-1,1],(-inf,inf)
      exposedField SFVec3f    position       0 0 10    # (-inf,inf)
      field        SFString   description    ""
      eventOut     SFTime     bindTime
      eventOut     SFBool     isBound
    }

The Viewpoint node defines a specific location in the local coordinate system from which the user may view the scene. Viewpoint nodes are bindable children nodes (see 4.6.10, Bindable children nodes: http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.6.10) and thus there exists a Viewpoint node stack in the browser in which the top-most Viewpoint node on the stack is the currently active Viewpoint node. If a TRUE value is sent to the set_bind eventIn of a Viewpoint node, it is moved to the top of the Viewpoint node stack and activated. When a Viewpoint node is at the top of the stack, the user's view is conceptually re-parented as a child of the Viewpoint node. All subsequent changes to the Viewpoint node's coordinate system change the user's view (e.g., changes to any ancestor transformation nodes or to the Viewpoint node's position or orientation fields). Sending a set_bind FALSE event removes the Viewpoint node from the stack and produces isBound FALSE and bindTime events. If the popped Viewpoint node is at the top of the viewpoint stack, the user's view is re-parented to the next entry in the stack. More details on binding stacks can be found in 4.6.10, Bindable children nodes (http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.6.10). When a Viewpoint node is moved to the top of the stack, the existing top of stack Viewpoint node sends an isBound FALSE event and is pushed down the stack.

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

The bindTime eventOut sends the time at which the Viewpoint node is bound or unbound. This can happen:

- during loading;
- when a set_bind event is sent to the Viewpoint node;
- when the browser binds to the Viewpoint node through its user interface described below.

The position and orientation fields of the Viewpoint 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. In the default position and orientation, the viewer is on the Z-axis looking down the -Z-axis toward the origin with +X to the right and +Y straight up. Viewpoint nodes are affected by the transformation hierarchy.

Navigation types (see SoVRMLNavigationInfo) that require a definition of a down vector (e.g., terrain following) shall use the negative Y-axis of the coordinate system of the currently bound Viewpoint node. Likewise, navigation types that require a definition of an up vector shall use the positive Y-axis of the coordinate system of the currently bound Viewpoint node. The orientation field of the Viewpoint node 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" to the position and orientation of a bound Viewpoint node or remains unchanged. This jump is instantaneous and discontinuous in that no collisions are performed and no ProximitySensor nodes are checked in between the starting and ending jump points. If the user's position before the jump is inside a ProximitySensor the exitTime of that sensor shall send the same timestamp as the bind eventIn. Similarly, if the user's position after the jump is inside a ProximitySensor the enterTime of that sensor shall send the same timestamp as the bind eventIn. Regardless of the value of jump at bind time, the relative viewing transformation between the user's view and the current Viewpoint node shall be stored with the current Viewpoint node for later use when un-jumping (i.e., popping the Viewpoint node binding stack from a Viewpoint node with jump TRUE). The following summarizes the bind stack rules (see 4.6.10, Bindable children nodes: http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.6.10) with additional rules regarding Viewpoint nodes (displayed in boldface type):

- During read, the first encountered Viewpoint node is bound by pushing it to the top of the Viewpoint node stack. If a Viewpoint node name is specified in the URL that is being read, this named Viewpoint node is considered to be the first encountered Viewpoint node. Nodes contained within SoVRMLInline nodes, within the strings passed to the Browser.createVrmlFromString() method, or within files passed to the Browser.createVrmlFromURL() method (see 4.12.10, Browser script interface: http://www.web3d.org/documents/specifications/14772/V2.0/part1/concepts.html#4.12.10) are not candidates for the first encountered Viewpoint node. The first node within a prototype instance is a valid candidate for the first encountered Viewpoint node. The first encountered Viewpoint node sends an isBound TRUE event.
- When a set_bind TRUE event is received by a Viewpoint node,
  - If it is not on the top of the stack: The relative transformation from the current top of stack Viewpoint node to the user's view is stored with the current top of stack Viewpoint node. The current top of stack node sends an isBound FALSE event. The new node is moved to the top of the stack and becomes the currently bound Viewpoint node. The new Viewpoint node (top of stack) sends an isBound TRUE event. If jump is TRUE for the new Viewpoint node, the user's view is instantaneously "jumped" to match the values in the position and orientation fields of the new Viewpoint node.
  - If the node is already at the top of the stack, this event has no affect.
- When a set_bind FALSE event is received by a Viewpoint node in the stack, it is removed from the stack. If it was on the top of the stack,
  - it sends an isBound FALSE event,
  - the next node in the stack becomes the currently bound Viewpoint node (i.e., pop) and issues an isBound TRUE event,
  - if its jump field value is TRUE, the user's view is instantaneously "jumped" to the position and orientation of the next Viewpoint node in the stack with the stored relative transformation of this next Viewpoint node applied.
- If a set_bind FALSE event is received by a node not in the stack, the event is ignored and isBound events are not sent.
- When a node replaces another node at the top of the stack, the isBound TRUE and FALSE events from the two nodes are sent simultaneously (i.e., with identical timestamps).
- If a bound node is deleted, it behaves as if it received a set_bind FALSE event.

The jump field may change after a Viewpoint node is bound. The rules described above still apply. If jump was TRUE when the Viewpoint node is bound, but changed to FALSE before the set_bind FALSE is sent, the Viewpoint node does not un-jump during unbind. If jump was FALSE when the Viewpoint node is bound, but changed to TRUE before the set_bind FALSE is sent, the Viewpoint node does perform the un-jump during unbind.

Note that there are two other mechanisms that result in the binding of a new Viewpoint:

- An Anchor node's url field specifies a "#ViewpointName".
- A script invokes the loadURL() method and the URL argument specifies a "#ViewpointName".

Both of these mechanisms override the jump field value of the specified Viewpoint node ("#ViewpointName") and assume that jump is TRUE when binding to the new Viewpoint. The behaviour of the viewer transition to the newly bound Viewpoint depends on the currently bound NavigationInfo node's type field value (see SoVRMLNavigationInfo).

The fieldOfView field specifies a preferred minimum viewing angle 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 shall be greater than zero and smaller than . The value of fieldOfView represents the minimum viewing angle in any direction axis perpendicular to the view. For example, a browser with a rectangular viewing projection shall have the following relationship:

        display width    tan(FOVhorizontal/2)
        -------------- = -----------------
        display height   tan(FOVvertical/2)

where the smaller of display width or display height determines which angle equals the fieldOfView (the larger angle is computed using the relationship described above). The larger angle shall not exceed and may force the smaller angle to be less than fieldOfView in order to sustain the aspect ratio.

The description field specifies a textual description of the Viewpoint node. This may be used by browser-specific user interfaces. If a Viewpoint's description field is empty it is recommended that the browser not present this Viewpoint in its browser-specific user interface.

The URL syntax ".../scene.wrl#ViewpointName" specifies the user's initial view when loading "scene.wrl" to be the first Viewpoint node in the VRML file that appears as DEF ViewpointName Viewpoint {...}. This overrides the first Viewpoint node in the VRML file as the initial user view, and a set_bind TRUE message is sent to the Viewpoint node named "ViewpointName". If the Viewpoint node named "ViewpointName" is not found, the browser shall use the first Viewpoint node in the VRML file (i.e. the normal default behaviour). The URL syntax "#ViewpointName" (i.e. no file name) specifies a viewpoint within the existing VRML file. If this URL is loaded (e.g. Anchor node's url field or loadURL() method is invoked by a Script node), the Viewpoint node named "ViewpointName" is bound (a set_bind TRUE event is sent to this Viewpoint node).

The results are undefined if a Viewpoint node is bound and is the child of an LOD, Switch, or any node or prototype that disables its children. If a Viewpoint node is bound that results in collision with geometry, the browser shall perform its self-defined navigation adjustments as if the user navigated to this point (see SoVRMLCollision).

## Constructor & Destructor Documentation

## ◆ SoVRMLViewpoint()

SoVRMLViewpoint::SoVRMLViewpoint | ( | void |  | ) |

Constructor.

## ◆ ~SoVRMLViewpoint()

SoVRMLViewpoint::~SoVRMLViewpoint | ( |  | ) |
| protectedvirtual

Destructor.

## Member Function Documentation

## ◆ getClassTypeId()

SoType SoVRMLViewpoint::getClassTypeId | ( | void |  | ) |
| static

This static method returns the SoType object associated with objects of this class.

## ◆ getTypeId()

SoType SoVRMLViewpoint::getTypeId | ( | void |  | ) | const
| virtual

Returns the type identification of an object derived from a class inheriting SoBase. This is used for runtime type checking and "downward" casting.

Implements SoBase.

## ◆ getFieldDataPtr()

const SoFieldData ** SoVRMLViewpoint::getFieldDataPtr | ( | void |  | ) |
| staticprotected

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
Returns the SoFieldData class which holds information about fields in this node.

## ◆ getFieldData()

const SoFieldData * SoVRMLViewpoint::getFieldData | ( | void |  | ) | const
| protectedvirtual

Returns a pointer to the class-wide field data storage object for this instance. If no fields are present, returns `NULL`.

Reimplemented from SoFieldContainer.

## ◆ initClass()

void SoVRMLViewpoint::initClass | ( | void |  | ) |
| static

## ◆ GLRender()

void SoVRMLViewpoint::GLRender | ( | SoGLRenderAction * | action | ) |
| virtual

Action method for the SoGLRenderAction.

This is called during rendering traversals. Nodes influencing the rendering state in any way or want to throw geometry primitives at OpenGL override this method.

Reimplemented from SoNode.

## Member Data Documentation

## ◆ position

SoSFVec3f SoVRMLViewpoint::position

The viewpoint position. Default value is (0, 0, 0).

## ◆ orientation

SoSFRotation SoVRMLViewpoint::orientation

The camera orientation. By default the camera is aligned along the negative z-axis.

## ◆ fieldOfView

SoSFFloat SoVRMLViewpoint::fieldOfView

Field of view. Default value is PI/4.

## ◆ description

SoSFString SoVRMLViewpoint::description

A textual viewpoint description. Is empty by default.

## ◆ jump

SoSFBool SoVRMLViewpoint::jump

Jump TRUE/FALSE.

## ◆ set_bind

SoSFBool SoVRMLViewpoint::set_bind
| protected

An eventIn that is used to bind the viewpoint.

## ◆ bindTime

SoSFTime SoVRMLViewpoint::bindTime
| protected

An eventOut that is sent when the viewpoint is bound.

## ◆ isBound

SoSFBool SoVRMLViewpoint::isBound
| protected

An eventOut that is sent when the viewpoint is bound/unbound.

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

- SoVRMLViewpoint.h
- Viewpoint.cpp