Initialization and Control of Visualization Threads

The state embodied by a visualization thread (also refered as a rendering thread) is represented as an instance of an opaque structure, tvBase. Many of the functions of the API require a pointer (or handle) to this structure. A distinct instance of this structure is created for each rendering thread desired by the client code, via tvBaseCreate().

Creation of a tvBase structure allocates memory and performs certain initializations, but does not spawn the associated thread. Thread creation and termination are handled separately via calls to tvBaseStart() , tvBaseStop() respectively. Additionally, as certain graphics initializations are not safe/possible to perform until the associated window is visible, the client code should call tvBaseInitializeGraphics() once early on, typically as part of the processing to field an Xt Widget "realized" callback.

Clients may associate callbacks with a rendering thread, permitting them to capture messages eminating from the rendering thread [tvSetMessageHandler()] , and update events [tvSetUpdateHandler()]. Additionally, clients must register callbacks to handle adding and deleting timers on behalf of the render thread: tvSetAddTimerHandler(), tvSetDelTimerHandler(). Presumably the client forwards these requests to native application facilities, such as Xt timers in a Motif-based application.

Geographical datasets may be dynamically added and removed from a thread's rendering lists via a pair of functions: tvAddDataset(), tvRemoveDataset().

General purpose accessors/setters provide a mechanism to set state variables inside the render thread; see the Rendering Options and the discussion on the data type tvVariable for details. All of these functions follow the same form. "Set" functions specify the handle to the render thread, the name of the state variable to set, and the value. "Get" functions likewise specify the thread handle, the state variable name, and return the value. There is a pair of functions for each of the basic data types: tvGetBoolean()/ tvSetBoolean(), tvGetFloat()/ tvSetFloat(), tvGetFloatv()/ tvSetFloatv(), tvGetInteger()/ tvSetInteger(), tvGetIntegerv()/ tvSetIntegerv(), tvGetDouble()/ tvSetDouble(), tvGetDoublev()/ tvSetDoublev().

A pair of functions support pick operations in a render thread's window: tvBaseRegisterPickCB(), tvBaseFlyToPickPoint().

Several functions force the render thread to immediately take actions it normally does as needed. tvBaseRedoVisibleList() should be called anytime the geosets associated with the thread change, through additions or removal. tvBasePostRedraw() is called to force immediate redrawing of the scene.

Finally, the resources used by a rendering thread may be reclaimed by calling tvBaseDestroy(). This function should be called only after tvBaseStop() has been invoked to kill the thread execution; any further reference to the thread handle will shurely be disasterous.

(ISSUE: what roles do the functions tvForallWindows() and tvForallDatasets() play?)

API