Introduction

This chapter contains references to all the Starbase Display List routines, along with short descriptions of what they do. As its name implies, the purpose of this chapter is to be a summary — or overview — of Starbase Display List for those people who are familiar with display lists in general, or with the Starbase Display List in particular. As such, there is very little detail given here. For more in-depth descriptions of the Display List routines and what they do, see the succeeding chapters in this section of the manual, as well as theChapter 12 “Display List Reference” near the end of the manual.

Opening and Closing Devices

Table 2-1 Display List Routines for Opening and Closing

Call	Result
`close_segment`	Closes the currently open segment.
`gclose`	Closes the Starbase output device and its display list, or, closes the device-independent display list.
`gopen`	Opens a Starbase output device and its display list, or, opens the device-independent display list.
`open_segment`	Creates (if necessary) and opens a segment associated with the specified display list.

Display/Refresh

Table 2-2 Display List Routines for Displaying and Refreshing

Call	Result
`display_element`	Displays the current element of the open segment on the specified graphics display device.
`display_segment`	Displays the specified segment network on the specified graphics display device.
`display_segment_hsr`	Displays the specified segment network on the specified graphics display device with hidden surfaces removed.
`refresh_element`	Displays the current element of the open segment on the graphics display device associated with the display list.
`refresh_segment`	Displays the specified segment network on the graphics display device associated with the display list.
`refresh_segment_hsr`	Displays the specified segment network on the graphics display device associated with the display list with hidden surfaces removed.

Segment Network Manipulation

Table 2-3 Display List Routines for Segment Network Manipulation

Call	Result
`call_segment`	Places a `call_segment` element in the currently open segment.
`change_segment_references`	Changes all `call_segment`, `execute_segment`, `cond_call_segment`, and `cond_execute_segment` elements that reference a specified segment to reference another segment.
`cond_call_segment`	Inserts a conditional segment call element into the currently open segment.
`cond_execute_segment`	Inserts a conditional segment execution element into the currently open segment.
`cond_return`	Inserts a conditional return element into the currently open segment.
`delete_all_segments`	Deletes all segments as well as all segment references.
`delete_segment`	Deletes the specified segment if there are no references to the segment; otherwise, the specified segment is emptied.
`delete_segment_and_references`	Deletes the specified segment and all references to the segment.
`execute_segment`	Adds a segment execution element into the open segment.
`inq_called_segno`	Returns the number of the segment referenced by the current element.
`inq_calling_segment_count`	Returns the number of segments calling the specified segment.
`inq_calling_segment_list`	Returns a list of the names of segments in the display list that call the specified segment.
`inq_num_refs`	Returns the number of times the specified segment is referenced in the display list.
`inq_open_segment`	Returns a flag indicating if a segment is open in the specified display list, and if a segment is open, returns the name of that open segment.
`inq_open_segment_and_mode`	Returns a flag indicating if a segment is open in the specified display list, and if a segment is open, returns the name and state of the display mode of that open segment.
`inq_segment_count`	Returns the number of segments in the display list.
`inq_segment_list`	Returns a list of the names of the segments in the display list.
`inq_segment_exists`	Returns a flag indicating whether the specified segment exists.
`pop_state`	Restores Starbase to the state in which it was at the most recent call to `push_state`.
`push_state`	Causes a subset of the current state of Starbase to be saved for subsequent restoration.
`rename_segment`	Changes the identifier for a segment.
`rename_segment_and_references`	Changes the identifier for a segment and changes all `call_segment` elements referencing that segment to reference the same segment with the new name.

Segment Editing

Table 2-4 Display List Routines for Segment Editing

Call	Result
`copy_segment`	Copies the contents of the specified segment into the currently open segment.
`delete_eles`	Deletes elements from the currently open segment.
`dl_label`	Inserts a display list label into the currently open segment. Display list labels are used for element pointer positioning and are returned as part of the pick path from the picking operation.
`inq_ele_ptr`	Returns the position of the element pointer relative to the beginning of the segment.
`inq_ele_ptr_at_bound`	Returns an indication of where the element pointer is positioned with respect to the beginning and end of the segment.
`inq_ele_type`	Returns the type of the current element.
`replace_ele`	Places the display list in "replace mode". The next element added to a segment replaces the current element.
`set_ele_ptr`	Positions the element pointer relative to the beginning of the segment.
`set_ele_ptr_at_end`	Positions the element pointer at the end of the segment.
`set_ele_ptr_relative`	Positions the element pointer relative to the current element.
`set_ele_ptr_relative_to_label`	Positions the element pointer relative to a specified label.

Traversal Control

Table 2-5 Display List Routines for Traversal Control

Call	Result
`dl_control`	Sets batched picking size and other parameters (memory use, etc.).
`ele_control`	Sets or clears element control flags for the current element of the currently open segment.
`inq_ele_control`	Returns information about the element control flags of the current element of the currently open segment.
`inq_seg_control`	Returns information about the segment control flags of the segment.
`inq_traversal_depth`	Returns the maximum traversal depth for a display list.
`seg_control`	Sets or clears segment control flags of a segment.
`set_disp_traversal_control`	Inserts a display traversal control element into the open segment.
`set_pick_traversal_control`	Inserts a pick traversal control element into the open segment.
`set_traversal_depth`	Defines the maximum traversal depth for a display list.
`traversal_lock`	Controls display locking during display list traversal.

Debugging

Table 2-6 Display List Routines for Debugging

Call	Result
`print_element`	Prints the function name and the parameters of the current element of the currently open segment of the specified graphics device to standard output.

Name Sets and Filters

Table 2-7 Display List Routines for Name Sets and Filters

Call	Result
`add_names_to_set`	Identifies the beginning of a named segment section by adding the section's name to the current name set.
`inq_highlighting_filter`	Returns information about the current highlighting filter.
`inq_highlighting_filter_sizes`	Returns the size of the arrays needed by `inq_highlighting_filter`.
`inq_invisibility_filter`	Returns the segment section names stored in the invisibility filter's include filter and exclude filter.
`inq_invisibility_filter_sizes`	Returns the size of the invisibility filter's include and exclude filters.
`inq_nameset`	Returns the segment section names stored in the current name set.
`inq_nameset_size`	Returns the size of the current name set.
`inq_pick_filter`	Returns the segment section names stored in the pick filter's include and exclude filters.
`inq_pick_filter_sizes`	Returns the size of the pick filter's include and exclude filters.
`remove_all_names_from_set`	Clears all names from the current name set.
`remove_names_from_set`	Identifies the end of a named segment section by removing the section's name from the current name set.
`set_highlighting_filter`	Sets the current highlighting filter.
`set_invisibility_filter`	Place segment section names in the include and exclude filters of the invisibility filter to control primitive processing.
`set_pick_filter`	Place segment section names in the include and exclude filters of the pick filter to control pick processing.
`set_pick_sense`	Make the pick filter either a "pickability" filter or an "unpickability" filter.

Pruning, Culling and Extents

Table 2-8 Display List Routines for Pruning, Culling and Extents

Call	Result
`adapt_clip_to_extent`	Controls the disabling and enabling of clip planes based on extent testing.
`cond_call_segment`	Inserts a conditional segment call element into the currently open segment.
`cond_execute_segment`	Inserts a conditional segment execution element into the currently open segment.
`cond_return`	Inserts a conditional return element into the currently open segment.
`inq_cond_index`	Returns the current value of a condition index.
`inq_extent_info`	Returns supplementary information about an extent test.
`set_cull_size`	Defines a threshold cull size for setting the value of the cull condition.
`set_extent`	Computes the prune and cull condition index values. Determines the set of clip planes that can be disabled under optimization.
`set_extent_displacements`	Returns supplementary data for use by `set_extent`.

Picking

Table 2-9 Display List Routines for Picking

Call	Result
`dl_control`	Sets batched picking size.
`inq_pick_filter`	Returns the segment section names stored in the pick filter's include and exclude filters.
`inq_pick_filter_sizes`	Returns the size of the pick filter's include and exclude filters.
`inq_pick_path`	Returns the path to the picked element.
`inq_pick_path_depth`	Returns the depth of the path to the picked element.
`pick_from_segment`	Initiates a pick from a segment.
`set_pick_filter`	Place segment section names in the include and exclude filters of the pick filter to control pick processing.
`set_pick_mode`	Sets the picking mode to be used by `pick_from_segment`.
`set_pick_sense`	Make the pick filter either a "pickability" filter or an "unpickability" filter.
`set_pick_traversal_control`	Inserts a pick traversal control element into the open segment.

Application Data Manipulation

Table 2-10 Display List Routines for Application Data Manipulation

Call	Result
`application_data`	Inserts application data into the currently open segment.
`inq_application_data_size`	Returns the size of the application data in the current element.
`inq_application_data`	Returns the application data stored in the current element.

Archiving

Table 2-11 Display List Routines for Archiving

Call	Result
`inq_ele`	Returns the contents of the current element. Can be used to build an archive file.
`inq_ele_size`	Returns the size of the current element.
`inq_content`	Returns information about the parameters of the current element of the currently open segment.
`inq_content_sizes`	Returns the size of arrays needed by `inq_content`.
`interpret_ele`	Processes elements returned by `inq_ele` to the currently open display list or to the display.