Calling Segments From Other Segments

"call_segment"

The call_segment routine causes a "call segment" element to be inserted into the currently open segment. When the segment is traversed and the "call segment" element is encountered, the following events take place:

The syntax is:

where:

When refreshing or displaying a segment that contains a "call segment" element, the call_segment routine does nothing to save or restore the Starbase state after control returns from the called segment; that is, if the specified segment contains any Starbase calls that change the attribute settings, etc., those settings will still be in effect after control is returned to the segment containing the call_segment call.

For example, consider the following piece of pseudo-code:

   .
   .
   .
open_segment(fildes, 1, ...);
line_color_index(fildes, 12);
polyline2d(fildes, Line1, ...);
call_segment(fildes, 2);
polyline2d(fildes, Line3, ...);
close_segment(fildes);
   .
   .
   .
open_segment(fildes, 2, ...);
line_color_index(fildes, 15);
polyline2d(fildes, Line2, ...);
close_segment(fildes);
   .
   .
   .
refresh_segment(fildes, 1);
   .
   .
   .

Both segments 1 and 2 set the line color index (to different values). The question is: What color is Line3? Answer: Line3 is drawn with line color index 15. The reason is that call_segment neither saves the Starbase state before the call_segment, nor restores the Starbase state after the call_segment. Since the call_segment routine is used, when segment 2 exits and control is returned to segment 1, Display List does not restore the Starbase state to what it was before segment 2 was called. Therefore, Line3 is drawn in the line color most recently specified, regardless of the segment in which it was specified.

If you want the Starbase state to be saved and restored, use the routine execute_segment (discussed next).

"execute_segment"

The execute_segment routine causes an "execute segment" element to be inserted into the currently open segment. When the segment is traversed and the "execute segment" element is encountered, the following events take place:

The syntax is:

where:

When refreshing or displaying a segment that contains an "execute segment" element, a subset of the the Starbase state is saved before passing control to execute_segment, and it is restored after control returns. That is, if the specified segment contains any Starbase calls that change attribute settings, those settings will remain in effect only until control is returned to the segment containing the call to execute_segment. This "subset of the Starbase state" consists of Starbase attributes only — not the matrix stack or the current position. If you wish to save and restore the matrix stack, use the pop_matrix and push_matrix routines. It is not possible to save and restore the current position.

Since execute_segment is identical to call_segment except for the implicit restoration of the state of Starbase after a segment is called, the above pseudo-code example can be modified accordingly:

   .
   .
   .
open_segment(fildes, 1, ...);
line_color_index(fildes, 12);
polyline2d(fildes, Line1, ...);                 
execute_segment(fildes, 2);                     
(different
routine)polyline2d(fildes, Line3, ...);
close_segment(fildes);
   .
   .
   .
open_segment(fildes, 2, ...);
line_color_index(fildes, 15);
polyline2d(fildes, Line2, ...);
close_segment(fildes);
   .
   .
   .
refresh_segment(fildes, 1);
   .
   .
   .

In this case, Line3 is drawn in line color index 12. The reason is apparent in the following description of the actions of execute_segment:

"push_state" and "pop_state"

The routines push_state and pop_state respectively save and restore the state of the Starbase attributes. The discussion above shows why you might want such functionality, and the above discussion talks about how execute_segment implicitly does a push_state and pop_state. The syntax of these routines is simple:

The words "push" and "pop" imply that the Starbase states are stored on a stack, and, indeed, this is the case. Because of this, push_state/pop_state pairs can be nested to any depth, limited only by available memory.

Harking back to the pseudo-code example above and modifying it accordingly, we can see that explicitly saving and restoring the Starbase state yourself (using push_state and pop_state), and then executing call_segment, has the same effect as using execute_segment:

   .
   .
   .
open_segment(fildes, 1, ...);
line_color_index(fildes, 12);
polyline2d(fildes, Line1, ...);
push_state(fildes);                (save
Starbase state)
call_segment(fildes, 2);
pop_state(fildes);                 (restore
Starbase state)
polyline2d(fildes, Line3, ...);
close_segment(fildes);
   .
   .
   .
open_segment(fildes, 2, ...);
line_color_index(fildes, 15);
polyline2d(fildes, Line2, ...);
close_segment(fildes);
   .
   .
   .
refresh_segment(fildes, 1);
   .
   .
   .

As before, Line3 is drawn in line color index 12. The reasoning is functionally identical to that in the case of execute_segment, but the way we went about it was different: