set_invisibility_filter(3G)

NAME

set_invisibility_filter − set the current invisibility filter

SYNOPSIS

C Syntax:

void set_invisibility_filter(fildes,
i_count, i_names, x_count, x_names)
int fildes, i_count, i_names[], x_count, x_names[];

FORTRAN77 Syntax:

subroutine set_invisibility_filter(fildes,
i_count, i_names, x_count, x_names)
integer*4 fildes, i_count, i_names(i_count),
x_count, x_names(x_count)

Pascal Syntax:

procedure set_invisibility_filter(fildes:integer;
i_count:integer; var i_names[lo1..hi1:integer] of integer;
x_count:integer; var x_names[lo2..hi2:integer] of integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

i_count Number of integers in the i_names array that represent bit strings of names to be put into the inclusion set of the invisibility filter.

i_names Array of integer bit strings representing names to be put into the inclusion set of the invisibility filter.

x_count Number of integers in the x_names array that represent bit strings of names to be put into the exclusion set of the invisibility filter.

x_names Array of integer bit strings representing names to be put into the exclusion set of the invisibility filter.

Discussion

Set_invisibility_filter changes the invisibility filter of the specified graphics device. The filter’s inclusion set becomes the set specified by i_count and i_names, and the filter’s exclusion set becomes the set specified by x_count and x_names. This filter is used to make parts of a segment network (as indicated by add_names_to_set(3G), remove_names_from_set(3G), and remove_all_names_from_set(3G) elements) effectively invisible and unpickable.

Each bit in each integer of the inclusion or exclusion set represents a unique name. Assuming integers are 32 bits, this means that 32 names may be represented with one integer, 64 names with two integers, 96 names with three, etc. The maximum number of names allowed is limited only by available memory.

Graphical primitives will not be drawn whenever the current name set includes any of the names in the invisibility filter’s inclusion set but doesn’t include any of the names in the invisibility filter’s exclusion set.

All other Starbase non-primitive elements (such as line_color_index and call_segment) are not subject to filtering and will therefore always be traversed normally.

Whenever a filter’s maximum size (i.e. the maximum of the sizes of the filter’s inclusion and exclusion sets, in integers) changes, the current name set may be left in an undefined state (see inq_nameset(3G)). In this case, the filter change should be followed by a call to remove_all_names_from_set(3G) to restore the current name set to a well-defined state. This is not necessary if the filter’s maximum size does not change.

EXAMPLE

A C programmer writing an application has created a segment containing a polygon with names 1 and 2, a rectangle with name 1, a polyline with name 2, and an ellipse with name 4. If the invisibility filter is set to include name 1, and exclude name 2, then the next time that segment is refreshed:

• the polygon is both included and excluded. Exclusion always takes precedence over inclusion, so the polygon is excluded from the filter, and is visible.

• the rectangle is included. This makes it invisible.

• the polyline is excluded. This makes it visible.

• the ellipse is neither included nor excluded. The filter doesn’t affect it, leaving it visible.

If i_names and x_names are both integer arrays that can hold at least one integer, and fd is a gopen’ed file descriptor, then the following C calls would set the invisibility filter to include name 1 and exclude name 2, as in the example above:

/* In this example the lowest order bit is name 1,
* and the next lowest order bit is name 2
*/
i_names[0] = 1; /* low-order bit */
x_names[0] = 2; /* next lowest order bit */
/* Now set up the filter with 1 integer’s worth of
* names in both the inclusion set and exclusion
* set
*/
set_invisibility_filter(fd, 1, i_names, 1, x_names);

WARNING

Graphical state-changing primitives (for example, graphical primitives that move the current pen position such as move2d, polyline2d and draw2d) will not affect the state if they are invisible. Programmers that depend on this state (particularly the current pen position) should make sure the state is well-defined after this type of traversal. One way to maintain the current pen position is to place a move2d(3G) or move3d(3G) to a well-defined position immediately before any group of primitives that depend on the current position.

ERRORS

1 Graphics device is not initialized for this operation.

6 Invalid parameter value − i_count or x_count less than 0.

DEFAULTS

When a graphics device is gopen´ed the inclusion and exclusion sets of its invisibility filter are empty. This implies that, by default, no primitive is invisible (all are visible).

Museum

Related Articles