set_pick_filter(3G)

NAME

set_pick_filter, set_pick_sense − set the current pick filter

SYNOPSIS

C Syntax:

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

void set_pick_sense(fildes, sense)
int fildes, sense;

FORTRAN77 Syntax:

subroutine set_pick_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)

subroutine set_pick_sense(fildes, sense)
integer*4 fildes, sense

Pascal Syntax:

procedure set_pick_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);

procedure set_pick_sense(fildes, sense: 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 pick filter.

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

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

sense Zero if elements trapped by the pick filter are to be considered unpickable, or non-zero if only elements trapped by the pick filter are to be considered pickable.

Discussion

Set_pick_filter changes the pick filter of the specified graphics device so that the filter’s inclusion set matches the set specified by i_count and i_names, and the filter’s exclusion set matches 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 unpickable.

Set_pick_sense changes the sense of the pick filter of the specified graphics device. The sense of the filter determines whether it acts as an "unpickability" filter or a "pickability" filter. If sense is zero, any element caught in the filter is considered unpickable and every element that passes through is considered pickable. Hence the filter is an "unpickability" filter. If sense is non-zero, any element caught in the filter is considered pickable and any element that passes through is considered unpickable. In this case, the filter is a "pickability" filter.

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.

If the sense of the pick filter is zero, visible primitives will not be placed in the graphics pipeline during pick traversals (and hence will be unpickable) whenever the current name set includes any of the names in the filter’s inclusion set but doesn’t include any of the names in the filter’s exclusion set. If the sense of the pick filter is non-zero, visible primitives will only be pickable when the current name set includes any of the names in the filter’s inclusion set but doesn’t include any of the names in the filter’s exclusion set. Invisible primitives (see set_invisibility_filter) are never pickable.

Any primitive that is unpickable (or invisible) will never be detected as a result of a pick_from_segment call, even if it is within the pick aperture.

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 pick filter are empty, and its pick sense is zero. Hence, by default every primitive is pickable.

Museum

Related Articles