The default processing of the graPHIGS API is to collect primitives and attributes into groups called structures. This grouping allows data to be defined hierarchically and permits easy modification through structure editing operations. In addition, to draw the picture that is defined by the structure content, the graPHIGS API traverses the structures. This traversal makes the displayed picture correct, but requires that all the affected contents be redrawn.
There may be reasons that the structures are not a benefit to some applications; such as, the data is not hierarchical or the structure changes are extensive enough as to require complete replacement of all structure content. In addition, you may want to perform your own traversal in your application rather than invoking the graPHIGS API to perform the traversal. (By doing your own traversal, you can realize your own optimizations and "short-cuts" that the graPHIGS API does not provide, thus improving end-user responsiveness).
To allow an application to directly control the traversal and drawing process, the graPHIGS API provides subroutine calls that access the very basic rendering controls of the workstation. These controls suspend the normal (implicit) processing of the graPHIGS API rendering and allow your application to provide its own (explicit) processing. These controls provide your application explicit traversal control in the following ways:
Your application can display output primitives on a workstation without requiring the use of structures. Your application sends primitives and attributes directly to a workstation rather than storing them in a structure. Note that immediate refers to this bypass of structures: it does not mean that your workstation displays elements immediately in time (although your application can force that result, if desired). An application's use of immediate elements for traversal is often called Immediate Mode Your application can use immediate mode in place of the graPHIGS traversal processing of data in structures, or your application can combine immediate mode traversal with traversal of elements in structures (see below).
Your application can create pictures by directly rendering graphical data in structures. This is similar to immediate mode traversal (in that the application does the traversal operation rather than using the normal graPHIGS traversal processing) but differs in that the application does the traversal of elements stored in structures rather than providing the elements directly. (The application can create a picture by using both immediate mode processing and explicit traversal processing together).
Your application can control the resources used by the workstation during the interpretation of elements for display. These workstation resources are typically frame buffers and Z-buffers used by HLHSR processing. Your application can direct the rendering into the currently displayed frame buffer or to a background frame buffer, it can cause a background frame buffer to be displayed, and it can clear a frame buffer or Z-buffer. These controls allow your application to create pictures, display them, and update the displayed result directly, according to the application's requirements.
Together, these three facilities, Immediate Elements, Direct Traversal Processing, and Workstation Resource Control, are called Explicit Traversal Control, since they suspend the default graPHIGS traversal and allow the application to perform the traversal directly (i.e. explicitly). By using these facilities, a graPHIGS application can implement update techniques that are optimized for the application's requirements, and can use data organizations other than the hierarchical, centralized structure store. For example, an application could:
Existing graPHIGS applications operate without change and still obtain all the internal optimizations implicitly performed. When using the explicit traversal functions, the application defines its own traversal and can provide its own optimizations in place of those of the graPHIGS API If the workstation is in WAIT deferral state and NO_IMMEDIATE_VISUAL_EFFECT (NIVE) modification mode, changes are processed only at the application's request. Other combinations of deferral states and modification modes are ignored and the explicit processing forces the workstation into a "conceptual" mode of WAIT /NO_IMMEDIATE_VISUAL_EFFECT
All explicit traversals are initiated by the application by calling the Begin Traversal (GPBGTR) subroutine, which specifies the workstation to receive the elements produced by the application's traversal. The function parameters include a workstation identifier, a processing type, and processing-type-specific information. This function sets a new workstation state Workstation Selected (WSSL) and can only be called from state Workstation Open (WSOP), which implies GPBGTR can not be nested. The selected workstation receives subsequent explicit traversal commands. The workstation becomes dedicated to the traversal processing, and is conceptually put in WAIT deferral state and NO_IMMEDIATE_VISUAL_EFFECT modification mode, since the application explicitly directs the traversal and rendering processing. (This processing state is similar to the Update Workstation (GPUPWS) and Redraw All Structures (GPRAST) subroutines, where a traversal is performed on the contents of the structure store. However, GPBGTR identifies the workstation to interpret the elements: the application is performing the traversal).
Upon receiving the Begin Traversal (GPBGTR) subroutine, the workstation:
GPENTR completes an explicit traversal sequence and requires the structure state Structure Open (STOP) or Structure Close (STCL) and the workstation state Workstation Selected (WSSL). The structure state can not be the newly defined state Non-Retained Structure Open (NROP). Upon receiving this command, the workstation completes any processing of the scene. Notice that this function does not delete the scene or clear the Rendering Resources. The scene can be appended to if the application invokes another GPBGTR - GPENTR sequence. The effect of appending to an existing scene is Renderer dependent. In addition, the results of appending to a scene are indeterminate if the WSL is changed between GPENTR and the next GPBGTR
In order for an application to send structure elements directly to a workstation or explicitly traverse structures in the Centralized Structure Store, an application must first call the Begin Structure (GPBGST) subroutine. GPBGST changes the structure state to Non-Retained Structure Open (NROP) and directs all subsequent elements to the workstation. The End Structure (GPENST) subroutine completes the explicit traversal sequence started by GPBGST and returns the structure state to Structure Closed (STCL).
GPBGST precedes immediate structure elements that are to be interpreted by a workstation. It is part of the application's traversal processing, and is analogous to the graPHIGS API processing performed by a workstation when traversing a root structure, where the Traversal State List (TSL) is initialized. (Refer to The graPHIGS Programming Interface: Technical Reference for details on the Travers al State List.) The Begin Structure (GPBGST) subroutine does not reference any retained structures nor does it cause elements to be retained. Rather, it indicates that the application is sending elements for interpretation and display by the workstation.
Upon receiving a Begin Structure (GPBGST) subroutine call, the workstation:
A GPBGST - GPENST sequence is only permitted in workstation state Workstation Selected (WSSL) which implies that they must be bracketed by Begin Traversal (GPBGTR) and End Traversal (GPENTR) subroutine calls.
Following the GPBGTR and GPBGST subroutine calls, output primitives and attributes (e.g., Polyline 3 [GPPL3]) are passed to the traversing workstation for interpretation. Your application can use any API call that, in the default processing, would create a structure element. (These are the subroutine calls in the Output Primitives and Attributes chapters of The graPHIGS Programming Interface: Subroutine Reference manual.) In immediate mode, the same element is sent to the workstation for interpretation rather than being stored in a structure. This includes the Execute Structure element, which results in the traversal of the identified structure. Thus, an application can use immediate mode processing to also traverse structures and their contents. The End Traversal (GPENTR) and End Structure (GPENST) subroutines indicate completion of the corresponding GPBGTR and GPBGST subroutines.
The following immediate elements are valid only in state NROP (these are not valid elements to insert into a structure):
This structure element has a similar effect on the TSL as the Execute Structure (GPEXST) subroutine. Unlike the Execute Structure (GPEXST) subroutine, GPPSTS does not traverse the specified structure. GPPSTS allows an application to perform its own hierarchical traversal. Specifically, this element performs the following:
If a GPPSTS subroutine is encountered when the TSL stack is full, it is treated as a NULL element. However, the workstation maintains a logical stack depth and ignores all structure elements except a Pop TSL (GPPTS) subroutine until the stack depth becomes less than or equal to the maximum hierarchy depth. This has the effect of skipping the part of the hierarchy below the maximum hierarchy depth. A warning message is generated each time the logical stack depth is incremented beyond the maximum depth.
This structure element removes the top of the stack TSL and copies it to the current TSL. The effect is the same as returning from an Execute Structure (GPEXST) subroutine. If the TSL stack is empty when a Pop TSL (GPPTS) subroutine is encountered, GPPTS is treated as a NULL element and a warning is issued.
In the default graPHIGS API processing, traversal is the process of stepping through a structure network, and is performed on the structures associated to a view. The result of traversal is the set of elements (primitives and attributes) to be interpreted by the workstation.
Your application can replace the graPHIGS API default traversal processing with its own traversal. By doing this, your application determines the primitives and attributes to be processed by the workstation and directs the rendering of these elements by the workstation. This processing is called direct traversal
Your application has two methods to provide the elements to the workstation during direct traversal:
The application can use these methods either independently or together to perform the traversal. Thus, direct traversal can be performed using both elements in structures and immediate elements.
Two functions are defined to allow an application to traverse a subset of an entire structure. These two function are the Traversal Elements (GPTE) and Accumulate Traversal State (GPATS) subroutines. Both functions are only valid in structure state Non-Retained Structure Open (NROP).
The Traversal Elements (GPTE) subroutine function causes the traversal of a group of structure elements found in a structure in the associated structure store. Start and end criteria can be specified, allowing the application to render a subset of a structure (for example, traversing the elements between two labels in a structure).
GPATS causes traversal of a group of structure elements found in a structure in the associated structure store. The elements are interpreted only to update the Traversal State List (TSL). No drawing of any primitive elements is performed. Execute Structure elements are ignored, but do increment the element counter. Accumulating the traversal state can be used, for example, to set the TSL before rendering immediate mode primitives. The effect of Accumulate Traversal State is to modify the current TSL which is sometimes called "Pseudo Traversal"
Both functions accept a flexible specification for the location in the structure to start and end traversal. These locations may be specified as pick identifier, label, element number, element type, or end-of-structure. An error is generated if the start location does not exist. If the end condition does not exist, traversal stops when the end of the structure is reached.
The element counter in the current TSL is incremented for each element that is traversed by these two functions.
In addition, to the direct traversal subroutines, two other subroutine calls are available for direct processing.
This subroutine draws all the roots associated with a view. If the border and the shield of the view are active, then these are also drawn. The specified view is updated as follows:
This subroutine draws the specified image in a view. The image must be previously defined. Your application specifies the extent of the image and the location, in World Coordinates (WC), where the image is to be drawn.
The workstation is responsible for interpreting elements for display on the display surface. The process of converting the elements to displayable data is called rendering Each workstation has certain resources that are used during rendering, such as frame buffers, Z-buffers, and memory. The workstation's resources are grouped according to purpose:
Explicit control of the rendering target allows the application to control which target is updated by rendering and when pictures are displayed. There are several functions in this category. All require workstation state Workstation Open (WSOP). These functions include:
This function selects a Rendering Target on the specified workstation to receive the results of rendering primitives and their bound attributes. For a double-buffered device, this allows rendering to be performed without affecting the current display, or allows rendering to be performed directly to the display surface. This function is only applicable to workstations with two or more Rendering Targets (Implicit updates also change the currently Selected Rendering Target).
Note: When a workstation is opened, the Selected Rendering Target is the same as the Displayed Rendering Target.
This function selects a Rendering Target on the specified workstation to be displayed. This function is only applicable to workstations with two or more Rendering Targets and is ignored on workstations with non-displayable Rendering Targets such as a CGM or GDF workstations.
This function resets the entire contents of the specified Rendering Targets. For a frame buffer workstation, the pixels are set to the value zero. On devices with a page/frame concept, this function forces a page eject or new frame even if the page/frame is already empty. Clearing a rendering target is typically performed before a traversal to remove any previously rendered output.
Any Rendering Target can be chosen for modification and/or for display. The Rendering Target chosen for modification is called the Selected Rendering Target and the Rendering Target chosen for display is called the Displayed Rendering Target
For ease in specifying Rendering Targets, they are conceptually organized in a ring as shown in the figure, "Rendering Target Ring." To specify a Rendering Target, an application must specify an offset from either the Selected Rendering Target or the Displayed Rendering Target. The offset must be an integer number; positive, negative, or zero. For example, for a double-buffered workstation an application could select the displayed buffer plus one for the next update. Upon completion of the update, the displayed buffer is set to the one just drawn (0 relative to the currently Selected Rendering Target).
Additional resource control subroutines allow your application to control the areas that are defined by the extents of a view:
This subroutine copies a region from one rendering target to another rendering target. The region is defined by the viewport of the specified view.
This subroutine fills a region of a rendering target. The region is defined by the viewport of the specified view. By performing the fill, the previous picture is replaced, thus clearing the area. If the view shielding indicator is ON , then the shield color is used to clear the view; otherwise, the view is not cleared. Additionally, if HLHSR mode is OFF for the view, then the Z-buffer is not cleared; otherwise, the Z-buffer is cleared.
The Clear All Rendering Resources (GPCARR) subroutine resets all Rendering Resources for the specified workstation. The function requires workstation state Workstation Open (WSOP) which means that GPCARR is not allowed between the Begin Traversal (GPBGTR) subroutine and the End Traversal (GPENTR) subroutine. This reset occurs in a workstation-dependent manner, depending on the type of resources. For example, if a workstation has a Z-buffer, then GPCARR causes the Z-buffer to be cleared.
The Inquire Rendering Targets (GPQART) subroutine returns the number of Rendering Targets available on a workstation for explicit use by an application. If the number returned is zero, explicit traversal control is not supported on the workstation.
PHIGS defines the following two fields in the WSL to describe the state of the display surface:
If a change is made to the WSL or any of the structure networks posted to the workstation, the State of Visual Representation for the currently Selected Rendering Target is set appropriately depending on whether the change was simulated or deferred. The State of Visual Representation is a flag that is set when you post structures to a workstation. Instead of displaying the change to a structure when it is posted, you can make a group of changes and then update the display once. The State of Visual Representation keeps track of whether the display is correct (shows all the changes that have been posted.) (Refer to "Frame Buffer Manipulation" for an explanation of the State of Visual Representation values.) The State of Visual Representation for the other Rendering Targets is set to DEFERRED but their content is not modified.
A Redraw All Structures (GPRAST) subroutine results in a CORRECT State of Visual Representation for the currently displayed Rendering Target (after completion). That is, the GPRAST causes the workstation to be cleared and to redisplay all the posted structures. The Clear Rendering Target (GPCRT) subroutine resets the Display Surface Empty status of the specified Rendering Target to EMPTY The effect of Update Workstation with control flag set to PERFORM is conditional:
All explicit traversal control functions set the state of the Selected Rendering Target to SIMULATED.
Notice that the display of a different Rendering Target could cause the State of Visual Representation and Display Surface Empty status of the PHIGS workstation to change.
All of the explicit traversal functions can be used with any combination of deferral states and modification modes. If a change is made to the WSL while in workstation state Workstation Selected (WSSL) and that change requires a modification be made to the display surface, the modification is postponed until the workstation state changes from WSSL to Workstation Open (WSOP). When the workstation state changes to WSOP, then the display is updated if required by the current deferral state and modification mode.
Implicit traversals performed by a workstation are affected by the explicit traversal processing of the application. Implicit regenerations and simulations of updates are not performed while in state WSSL. Implicit correlations and input device echoes are not performed while in state NROP.
When an implicit update traversal is performed, the graPHIGS API changes the contents of the current displayed and selected Rendering Target. The value of the display status is set to CORRECT for the displayed Rendering Target, and is unchanged for any other Rendering Targets. After completion of an implicit update, the selected rendering target is the same as the display rendering target.
There are several important considerations when using the explicit traversal functions. These considerations must be addressed to ensure that your use of explicit traversal does not cause problems with other parts of the graPHIGS API
For the most efficient use of the workstation's resources, your application must issue the End Structure (GPENST) and End Traversal (GPENTR) subroutine calls at reasonable intervals. This allows other processes to use the workstation's resources.
Input device echoes cannot be drawn while in state Non-Retained Structure Open (NROP). Your application must issue GPENST at reasonable intervals to allow the echo processing to be performed.
There is a potential for a processing interlock if your application issues an Await Event (GPAWEV) subroutine for pick device events while also doing explicit traversal processing. The potential problems occur if the Await Event is issued after a Begin Structure (GPBGST) subroutine but before the corresponding End Structure (GPENST) subroutine. The interlock occurs because the workstation facilities required to do the (implicit) correlation for the pick device are dedicated to the application's use by GPBGST If a pick device is active in EVENT mode and is triggered by the user pressing a button, then the workstation queues the pick processing until GPENST occurs. However, GPENST does not occur while your application is waiting in the Await Event. Note also that input events from other input devices are also queued if a pick event is queued under these circumstances. (This is to preserve the order of input events to the application). Only when the time interval expires does your application receive control again. Since this wait is for the time specified on GPAWEV, the workstation's resources are unavailable for other processing.
It is the responsibility of your application to ensure that such an interlock does not occur. This can be prevented by a variety of methods:
This section contains a set of example pseudocode fragments which illustrate the use of Explicit Traversal Control.
This example shows the changing of the color of a polyline without forcing a redraw of the entire screen. Through use of the explicit traversal controls, the application can be written to modify the polyline's color attribute and then retraverse just the attribute and polyline primitive. The code fragment listed below illustrates this type of trivial update, with the following assumptions:
.
.
.
CALL GPOPST(structure_id)
CALL GPEP(element_number-1)
CALL GPDLE
CALL GPPLCI(HIGHLIGHT_COLOR)
CALL GPCLST
CALL GPBGTR(WORKSTATION_ID, DRAWING, NULL)
CALL GPBGST(ANY_INTEGER)
CALL GPTE(structure_id, START(element_number-1), END(element_number))
CALL GPENST
CALL GPENTR
.
.
.
The trivial update example can be generalized to use a pick path of any depth by taking advantage of the Accumulate Traversal State (GPATS) subroutine. The pseudo code below also illustrates the use of the Push Set TSL (GPPSTS) subroutine and the Pop TSL (GPPTS) subroutine although, in this particular example, neither are required. The pseudo code was written with the following assumptions:
.
.
.
CALL GPOPST(pick_path[depth]
CALL GPEP(pick_path[depth]
CALL GPDLE
CALL GPPLCI(HIGHLIGHT_COLOR)
CALL GPCLST
CALL GPBGTR(WORKSTATION_ID, DRAWING, NULL)
CALL GPBGST(ANY_INTEGER)
DO 100 i = 1, depth
CALL GPPSTS(ANY_INTEGER)
structure_id = pick_path[i]
element_number = pick_path[i]
CALL GPATS(structure_id, START(ELEMENT1), END(element_number-1))
100 CONTINUE
CALL GPTE(structure_id, START(element_number), END(element_number))
DO 200 i = 1, depth
CALL GPPTS
200 CONTINUE
CALL GPENST
CALL GPENTR
.
.
.
The example code fragment below illustrates the animation of a line rotating about the origin. The animation is made "smooth" through the use of double buffering. The assumptions are as follows:
Note: The Inquire Available Rendering Targets (GPQART) subroutine function is called to ensure the workstation has at least two Rendering Targets.
.
.
.
CALL GPQART(WORKSTATION_TYPE, error_indicator, number_of_rts)
if (number_of_rts.GE> 2) THEN
line[POINT1]
line[POINT1]
loop i = 1 to 360
CALL GPSRT(WORKSTATION_ID, DISPLAYED_RENDERING_TARGET+1)
CALL GPCRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
CALL GPBGTR(WORKSTATION_ID, DRAWING, NULL)
CALL GPBGST(ANY_INTEGER)
angle = angle + DELTA_ANGLE x i
line[POINT2]
line[POINT2]
CALL GPPL2(TWO, line)
CALL GPENST
CALL GPENTR
CALL GPDRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
.
.
.
The Redraw All Structures (GPRAST) subroutine function can be defined using the explicit traversal functions as shown in the following pseudo code:
CALL GPRAST( workstation_id, flag )
CALL GPSRT( workstation_id, DISPLAYED_RENDERING_TARGET+1 )
if ( not_empty(selected_rt) or (flag.EQ.ALWAYS )) THEN
CALL GPCRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
CALL GPBGTR
for each root
CALL GPBGST(ANY_INTEGER)
CALL GPTE(root, ELEMENT_1, END_OF_STRUCTURE)
CALL GPENST
CALL GPENTR
CALL GPDRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
Note: After a call to Redraw All Structures, both the Selected Rendering Target and Displayed Rendering Target are the same.
The differences between the pseudo code for the Update Workstation (GPUPWS) and Redraw All Structures (GPRAST) subroutines are as follows:
CALL GPUPWS( workstation_id, flag )
IF ( ( state_of_visual_rep(displayed_rt).EQ. DEFERRED or
state_of_visual_rep(displayed_rt).EQ.SIMULATED ) &
flag.EQ.PERFORM ) THEN
CALL GPSRT( workstation_id, DISPLAYED_RENDERING_TARGET+1 )
IF ( note_empty(selected_rt) ) THEN
CALL GPCRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
for each root
CALL GPBGST(ANY_INTEGER)
CALL GPTE(root, ELEMENT_1, END_OF_STRUCTURE)
CALL GPENST
CALL GPDRT(WORKSTATION_ID, SELECTED_RENDERING_TARGET+0)
Note:
If the control flag parameter is set to PERFORM , the State of Visual Representation for the currently displayed Rendering Target upon completion of this function is always CORRECT and the same Rendering Target is both selected and displayed.