Introduction

Display List supports two very powerful and interrelated concepts called filters and name sets. This chapter discusses in detail what these two concepts are and how they are used.

Filters

Think about the various kinds of filters you have seen. The images going through your mind may include an oil filter, camera filter, water filter, noise filter, fuel filter, air filter, cigarette filter, electronic filter, etc. The thread of commonality among all these filters is this: in whatever medium it works, the filter passes some entities, and stops others. That is, it "strains out" the components that are undesirable for a particular application.

Display List filters work exactly the same way. Using them, you can "strain out" specified sections of segments, while "passing through" other sections. The sections that are passed through or strained out are not required to be entire segments; you can filter out single elements if you desire.

But why would you want to "filter out" some parts of your image? Using our example of the house, a simple segment hierarchy describes the entire image. Any visibility filtering and/or pickability filtering could be effected by simply using traversal-control edits or changing segment-control bits.

But suppose that your application requires individual pickability/visibility control of a greater number of different attributes of the database. For example, the operator might want to view the hot water plumbing and floor plan of the second-floor bathrooms of a house. This flexibility could also be represented by a hierarchy, but the disadvantage is that the number of structural elements grows very rapidly as the number of different selectable database attributes grows.

Another approach would be to linearize the entire display list into a single segment, and the application could control visibility and pickability by searching the segment and editing element-control bits. But this would require a lot of extra code, and the resulting implementation would be quite slow.

Display List's names sets and filters offer the flexibility to control many different attributes without exponential growth of the number of segments and without placing the management burden on the application.

Supported Filters

Display List supports three different filters:

The invisibility filter. This filter eliminates all graphics primitives that have been defined as invisible and passes all primitives that have been defined as visible. Invisible objects are not plotted at all, nor are they pickable.
The unpickability filter. This filter eliminates all graphics primitives that have been defined as unpickable, and passes all primitives that have been defined as pickable. Unpickable objects cannot be indicated via graphical input or found during a spatial search.
The highlighting filter. This filter renders as highlighted all graphics primitives that have been defined as highlighted, and renders normally all primitives that have been defined as unhighlighted.

Notice the sense of the names; for example, it is not a "visibility filter," it is an "invisibility" filter. That is, all elements are visible, unless they are filtered. Similarly, the others are an unpickability filter^[21] (by default, everything is pickable, unless it is filtered), and a highlighting filter (everything is unhighlighted, unless it is filtered). This is important — it means, for example, that if an element is included in the invisibility filter's list of objects, it will not be displayed on the screen.

Name Sets

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 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.

There are three different types of name sets:

The include set. Each filter has its own include set, which is a name set that specifies what objects are to be included in the set of objects to be filtered.
The exclude set. Each filter also has its own exclude set, which is a name set that specifies what objects are to be excluded from the set of objects to be filtered. If a name is specified in both the include set and the exclude set of any particular filter, the exclude set overrides the include set: that name is not ultimately filtered.
The current set. The current set specifies which names are currently active for comparison with the include and exclude sets. During display list traversal, graphics primitives are associated with all the names that are in the current name set at that moment.

The include sets and exclude sets are global values that stay constant during the traversal process. Conversely, the current set can change during traversal. It is modified by Display List calls that are stored in the display list and processed during traversal. As graphics primitives are traversed, whether they are invisible, unpickable, and/or highlighted, is determined by the combination of the current name set with the appropriate include and exclude sets.

A Display List name set is a simple data structure consisting of an array of integers. For the purpose of filtering, these integers are interpreted bit by bit, where each bit represents a "name". Collectively, each of these "arrays of bits" is called a name set.

A name is "in a name set" if the bit representing that name is set, and a name is not "in the name set" if the bit representing that name is clear. In other words, a "1" bit specifies that the name is to be considered in filtering operations; a "0" bit specifies that the name is not to be considered in filtering operations.

An 32-bit integer can represent up to 32 names, two integers can provide 64 names, and so forth. If you were to visualize a 64-bit name set, it might look like this:

`00000011 01000000 00000000 00000111`	`10000000 00000000 00000100 00000111`
Second integer: for names 32-63	First integer: for names 0-31

As you can see, a name set is just a set of zeroes and ones. This particular name set shows two integers' worth of names.

The actual operation of filters is as follows. If any of the "1" bits in the current set have corresponding "1" bits in the include set, the object is filtered, unless the corresponding bit in the exclude set is also "1", in which case the object is not filtered. Being "filtered," in this context, means to be either invisible, unpickable^[22], or highlighted, whereas being "not filtered" means visible, pickable, or unhighlighted.

The Name Set and Filter Routines

There are two main categories of routines dealing with filters and name sets: those related to the include and exclude sets of the various filters, and those related to manipulating the current set. These are discussed below.

Filter Routines

The syntax for the routines for defining the various filters is listed below:

set_invisibility_filter(〈fildes〉, 〈i_count〉, 〈i_names〉,\hfil\break{} 〈x_count〉, 〈x_names〉);
- and
set_pick_filter(〈fildes〉, 〈i_count〉, 〈i_names〉,\hfil\break{} 〈x_count〉, 〈x_names〉);
- and
set_highlighting_filter(〈fildes〉, 〈i_count〉, 〈i_names〉,\hfil\break{} 〈x_count〉, 〈x_names〉);

where:

〈i_count〉 is an integer value specifying the number of elements in the array 〈i_names〉; i.e., the number of integers' worth of names to be added to the include set — not the number of names.
〈i_names〉 is an array of integers whose bits represent names to be included in the filtering operation.
〈x_count〉 is an integer value specifying the number of elements in the array 〈x_names〉; i.e., the number of integers' worth of names to be added to the exclude set.
〈x_names〉 is an array of integers whose bits represent names to be excluded from the filtering operation.

Each filter mentioned above also has two inquiry routines: one for returning the 〈count〉 parameters (e.g., inq_invisibility_filter_sizes), and one for returning the 〈names〉 parameters (e.g., inq_invisibility_filter).

These filter-setting commands cannot be stored as elements in a display list — the values of the filters remain constant throughout traversal.

"Current Set" Routines

There are three routines that directly manipulate the current set:

add_names_to_set(〈fildes〉, 〈count〉, 〈names〉);
- and
remove_names_from_set(〈fildes〉, 〈count〉, 〈names〉);
- and
remove_all_names_from_set(〈fildes〉);

where:

〈count〉 specifies how many integers comprise the 〈names〉 array.
〈names〉 is an array of integers that contains the names to be added to (in the case of add_names_to_set) or removed from (in the case of remove_names_from_set) the current set.

The routine add_names_to_set combines, with the logical or operation, the current set with the name set specified in 〈names〉 to define the new current set.

The routine remove_names_from_set does a "set difference" operation, subtracting the nameset specified in 〈names〉 from the current set, to define the new current set. That is, for every "1" bit in 〈names〉, the corresponding bit in the current set is cleared.

Predictably, remove_all_names_from_set clears all bits in the current set. This routine can also be used to guarantee that the current set is empty at the start of traversal (this may be necessary for some applications, since the current name set is never automatically cleared).

As with the filter routines, there are inquiry routines related to the current set. Their names are inq_nameset_size and inq_nameset.

Unlike the filter-setting routines, the above routines (except the inquiries) are stored as elements in the display list.

Say What?

The above verbiage gets a little abstract, so perhaps an example is in order. For simplicity's sake, let's use a name set with only four bits. Suppose that you call set_invisibility_filter to define the invisibility filter's include set to the following value, and assume for the moment that the exclude set is empty:

Name Set	Bit 3	Bit 2	Bit 1	Bit 0
Invisibility include set	0	0	0	1

And suppose that, during subsequent traversal, an add_names_to_set element is executed so that:

Name Set	Bit 3	Bit 2	Bit 1	Bit 0
Current set	0	0	0	1

With these two values for the invisibility include set and the current set, graphics primitives subsequently traversed would not be displayed. The reasoning goes like this:

Bit 0 in the include set has a value of 1. This indicates that name 0, corresponding to bit 0, has been placed in the include set.
Bit 0 in the current name set also has a value of 1. This indicates that name 0 has also been placed in the current name set.
Since there is a name in the current name set that corresponds to the name in the include set, the graphics primitives being traversed are included in the set of filtered — invisible — objects and are thus not displayed. In other words, the result of combining the include set and the current set with the logical "and" operator is non-zero (0001 {∧} 0001 = 0001).

Now, by executing a remove_names_from_set or remove_all_names_from_set element, you set the value of the current set to all zeroes:

Name Set	Bit 3	Bit 2	Bit 1	Bit 0
Invisibility include set	0	0	0	1
Current set	0	0	0	0

Subsequent graphics primitives are not invisible in this case, because the current name set does not include a name that corresponds to a name in the invisibility include set (0001 {∧} 0000 = 0000).

Now further suppose that you change the current set back to its former state, and define the invisibility filter's exclusion set (also via set_invisibility_filter) to the same value:

Name Set	Bit 3	Bit 2	Bit 1	Bit 0
Invisibility include set	0	0	0	1
Invisibility exclude set	0	0	0	1
Current set	0	0	0	1

Subsequent graphics primitives would not be invisible, because the current name set has a name that corresponds to a name in the invisibility exclude set, and this overrides the match with the invisibility include set. The exclude set always overrides the include set.

The rule is: if one or more of the names in the current name set are in the invisibility include set, and none of the names in the current name set are in the invisibility exclude set, the graphics primitives being traversed will be included in the set of filtered objects.

All of the above can be stated mathematically. Let:

N: be a specified set of names.
I: be the inclusion set for any particular filter.
E: be the exclusion set for the same filter.
C: be the current set.

Using the above definitions, note the descriptions in the following tables. In the left column is the mathematical statement, and in the right column is the English equivalent:

The operation done by add_names_to_set is:
C←C {∪} N
The current set becomes the set union of the previous value of the current set and the specified name set.
The operation done by remove_names_from_set is:
C←C-N
The current set becomes the set difference of the previous value of the current set and the specified name set.
Filtering is performed if and only if:
(C ∩ I≠ ∅ ) ∧ (C ∩ E= ∅ )
There are names in the current set that are also in the include set, and there are no names in the current set that are also in the exclude set.

^[21]To be compatible with the PHIGS definition, Display List allows you to change the sense of the pick filter from an unpickability filter to a pickability filter. See the Reference section under the command set_pick_sense for details. Note: only the pick filter can have its sense reversed.

^[22]Again, for PHIGS users, the sense of the pick filter can be reversed by calling set_pick_sense.

Introduction

Technical documentation

» Table of Contents

» Glossary