set_highlighting_filter(3G)

NAME

set_highlighting_filter − set the current highlighting filter

SYNOPSIS

C Syntax:

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

FORTRAN77 Syntax:

subroutine set_highlighting_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_highlighting_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 highlighting filter.

i_names Array of integer bit strings representing names to be put into the inclusion set of the highlighting 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 highlighting filter.

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

Discussion

Set_highlighting_filter changes the highlighting 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 highlight 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).

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 be highlighted whenever the primitive in question is not being ignored by one or more of ele_control, seg_control and set_invisibility_filter, and the current name set includes any of the names in the highlighting filter’s inclusion set but doesn’t include any of the names in the highlighting filter’s exclusion set.

WARNING

Mixing highlighting calls from seg_control, set_highlighting_filter, and highlight_on is not recommended. If they are mixed, they behave independently. Primitives are then highlighted if any of the three indicates they should be. For example, if segment 1 contains the following elements:

highlight_on(fildes, FALSE)
polygon2d(fildes,...)

and the segment has been marked HIGHLIGHT with seg_control, the polygon will be highlighted, because the highlight_on call cannot turn off seg_control highlighting.

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. If the filter’s maximum size does not change, this is not necessary.

For an example of how to use filters, see set_invisibility_filter(3G).

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 highlighting filter are empty. This implies that, by default, no primitive is highlighted.

Museum

Related Articles