Introduction

In order to converse fluently about Display List, one must be familiar with the pertinent jargon. This chapter defines the necessary words and concepts in order to make the discussions in future chapters understandable.

Display List

A display list is a hierarchically organized body of graphics commands and data that can be created, modified, sent to a display device, stored, and retrieved. Providing display list capabilities frees the application from having to do so.

A display list may or may not be associated with a display device; both are supported by the Starbase Display List. If a display list is associated with a particular display device it is considered device-dependent. If it is not associated with a particular display device, but can be displayed on a device yet to be determined, it is considered device-independent.

The commands in a display list are executed via a process called display list traversal. If the display list is device-dependent, a traversal for the purpose of drawing the picture is called refreshing; if the display list is device-independent, it is called displaying.

A Starbase Display List is composed of one or more structural pieces called segments.

Segments

A display list is a collection of graphical commands and/or data, all wrapped up into neat little "packages" called segments. Each graphical command or block of data is called an element (discussed below). A segment can be called as a sub-part of some other segment, much like a "subroutine of structure." A segment can also have its own sub-parts — other segments — which it can call. A segment that calls another segment is referred to as a parent segment and, conversely, a segment that is called by another segment is referred to as a child segment. A hierarchically arranged group of segments is referred to as a segment network.

The contents of a segment can be defined, added to, modified, and deleted from. All of these operations require that the segment first be opened. Opening a particular segment tells the computer that the specified segment is the one that is to be the recipient of the following display-list manipulation commands. After you are through doing operations on the open segment, you close the segment.

When your application passes control to a segment, the commands therein — the elements — are executed sequentially; when all the elements in that segment have been executed, control is returned to the calling segment. This process of executing the elements in a segment is called segment traversal, and if the display list's image is being displayed during the traversal (you may or may not want it to be), such a traversal is called display traversal.

In situations where one segment calls another segment that calls another segment that calls another segment, and on and on, it may be useful to be able to tell Display List to traverse — or not to traverse — a specified portion of the display list. This ability, in its several flavors, is called traversal control. Traversal control deals with these areas:

Segment control: the ability to make individual segments invisible, unpickable, or highlighted during traversal.
Element control: the ability to make individual elements invisible or unpickable during traversal.
Conditional traversal: the ability to decide whether or not to traverse a segment (to return from a segment) based on testing of program parameters.
Namesets and filters: the ability to put the parts of a display list into "categories," and then to include them or not, in a filtering process. The three filtering options affect visibility, pickability, and highlighting.
Traversal control elements: the ability to control the behavior of the display list by making some portions visible or invisible, pickable or unpickable.
Traversal depth control: the ability to selectively avoid traversal of some sections altogether by limiting traversal depth.

All these subjects are covered in later chapters.

At any point in time, Starbase's attributes are in a particular state. Depending on your application, you may wish the state of these attributes to be identical after calling a segment to what it was before calling the segment. Display List can automatically save (a subset of) Starbase's attributes before a segment call and restore them after the call, or you can save and restore them yourself by including the appropriate calls.

There are many segment-level operations that Display List supports. Segments can be copied into other segments, renamed, their references changed in calling segments, and more.

The individual pieces of a segment — those commands and/or data that comprise it — are called elements.

Elements

All the Starbase commands, Display List commands, and application-specific data that are included in the definition of a display list segment are called elements. Examples include primitives like move2d, polyline3d, polygon3d, and ellipse, attribute settings like curve_resolution, interior_style, and line_color, segment-network calls like call_segment, and so forth. Each element has a particular type, and this type can be interrogated by the application program.

The Element Pointer

A display list keeps track of where it is in each segment by means of an element pointer. As its name implies, it is a pointer that indicates which element in a given segment is its current element; i.e., the element that will be acted upon next by any Display List function that deals with individual elements if that segment is open. Actions may include inserting, deleting, or replacing elements.

When replacing an element with another element, the two are not required to be the same size; Display List "makes room" for a larger element if necessary. For example, a call to make_picture_current, with its single parameter, can be replaced by a call to bitmap_print, with its thirteen parameters. You need not be concerned with moving subsequent elements.

Every segment has its own element pointer, and therefore, its own current element. The phrase "the current element" means "the current element in the currently open segment;" this is the element that will be acted upon next by any display list function that deals with individual elements.

The element pointer always has a valid value, even when the open segment is an empty segment. This is because, technically, there is really no such thing as a truly empty segment. When a segment is created, a special null element is placed at the beginning of the segment. This is the element to which the element pointer initially points.

Again, each segment has its own element pointer; there is not just a single one that must be shared among all the segments. Because of this, you can close a segment, do some operations, re-open the same segment, and the segment's element pointer remains where it was when you closed the segment (unless you explicitly tell it to be somewhere else). This permits many useful operations, as we'll see in Chapter 7 “Display List Editing”

An element-specific operation that relates to the subject of this chapter is refreshing or displaying individual elements within a segment. Chapter 5 “Displaying and Refreshing” describes Display List's refreshing/displaying commands, and shows an example of element-by-element refreshing.

Element Labels

To help you retain an intuitive understanding of your display list, you can insert labels into it at strategic points. Thus, when you want to access a particular element, you won't have to remember exactly where it is in the segment; you can just tell Display List to "go to label such-and-such," and the element pointer will be correctly positioned, no matter what is before or after the element of interest.

Picking

Picking in a display list is similar to picking in a non-Display List environment: it is the process of indicating, via graphical input routines, a piece of a displayed image, and having the application understand which piece was indicated. In addition, you can use the picking functionality to do a spatial search, where graphical input is not involved at all.

Of course, when picking in a Display List environment, returned information regarding the picked object is described in a Display List context. For example, you can know not only which object was picked, but the entire pick path; i.e., that path down the hierarchical segment network that was traversed to display the particular instance of the object picked. The process of determining which, if any, components of a display list were picked is called pick traversal.

Filters and Name Sets

By default, every graphics primitive is visible during display traversal. However, you may want to temporarily make certain objects, or whole sets of objects, invisible during display traversal. Similarly, by default, every graphics primitive is pickable during pick traversal, and every primitive is unhighlighted. But in the same vein, you may want to temporarily make certain objects unpickable during pick traversal, or highlighted during display traversal.

Display List makes available three filters: they are called the invisibility filter, the unpickability filter, and the highlighting filter. But before a filter can really become useful, you must have some way of specifying which things are to be filtered out. Display List allows you to do such specification with what are called name sets. As the term implies, it is simply a set of names. Conceptually, a "name" is just a category or class to which a graphics object can belong. A name set is a collection of these categories. A graphics object may belong to no category, one category, or to as many categories as you desire.

Each filter has two name sets, called its include set and its exclude set, whose operations are intuitive:

Categories mentioned in the include set of the invisibility filter are invisible.
Categories mentioned in the exclude set of the invisibility filter are visible, regardless of whether or not they are also mentioned in the include set.
Categories mentioned in the include set of the unpickability filter are unpickable.
Categories mentioned in the exclude set of the unpickability filter are pickable, regardless of whether or not they are also mentioned in the include set.
Categories mentioned in the include set of the highlighting filter are highlighted.
Categories mentioned in the exclude set of the highlighting filter are unhighlighted, regardless of whether or not they are also mentioned in the include set.

There is also a name set known as the current name set. The current name set is an integer array in which the bit numbers correspond to the (numeric) category names. Inclusion of a name in a set is equivalent to having the bit whose number is the same as the name, set to "1".

Off We Go...

Now that you are familiar with these terms, the discussions ahead will have some framework in which to fit in your mind. If you forget the meaning of a term, feel free to refer back to this chapter for definitions of the terms arranged in logical groupings, or see the glossary for an alphabetical list.

Introduction

Technical documentation

» Table of Contents

» Glossary

» Index