View Specification and Navigation

The functions described here are the means by which arbitrary views into a scene can be established, and provide support for animated navigation.

There are three views that may be associated with a rendering thread. First, there is always the notion of a current view, which is the view being rendered at any instant in time. There is the notion of an initial view, which is retained as part of the rendering state. One use for the initial view is to give the user a means to return to a well-defined view, in an interactive application where the user may potentially get disoriented or lost in the scene. Lastly, there is a frozen view which may be set by the client-code (ISSUE: not clear what the use of this is...).

Viewing parameters may be set by either of one of two means. Many of the functions accept or return a tvViewpoint data structure, which encapsulates various details about a view. Alternatively, a view is established by a reference point and roll/pitch/yaw angles about a current view.
(ISSUE: what are these angles relative to? Pitch seems straigforward; are roll and yaw about some geographical coord. system? Lat/Long?).
(ISSUE: not clear how one creates new View structs? For example, where does a user specified "initial" view come from -- manually constructed?)

The viewing system should be initialized with a call to tvBaseInitView(). This sets up reasonable defaults: either the (SW?) corner of a scene, or directly over the center of the geographical extent in the case of a 2D-contrained view, or to an initial view set previously by the client-code with tvSetInitialView(). (Issue: Huh? again, how does one get the View struct, and is this an exception to a rule that ThreeDCoreInitView() must be the first viewing function called? Is this a rule?)

tvSetView() and tvSetView3d() provide a means to set the current view, in an absolute sense. tvAdjustView() permits setting the view in a viewer-based fashion, as offsets left, forward and up relative to the current view. A convenience function tvBaseCentralView() sets the current view to the center of the available geographic extent, looking straight down (what altitude?).

The current view of a thread may be retrieved from calling tvBaseGetView(), or tvBaseView() (redundant -- prefer one over the other?).

The Viewing API also supports animated fly-throughs of a scene. Animation is set in motion by calling tvStartMovement(). The speed of the fly through is affected with calls to tvStartAccelerate() and tvStartDeccelerate(). All motion is halted with tvStopMovement(). Motion is generally along a vector in the "forward" facing direction of the view. However, it may be skewed up/down or left/right with calls to tvBaseSetAttitudeDelta() and tvBaseSetSlideDelta(), respectively.

Finally, tvBaseSetFrozenView() establishes the frozen view associated with a thread. tvBasePointAltitude() is a convenience function for calculating the altitude of a given point with respect to the underlying terrain.

API