inq_nameset(3G)

NAME

inq_nameset_size, inq_nameset − return information about the current active name set

SYNOPSIS

C Syntax:

void inq_nameset_size(fildes, size)
int fildes, *size;

void inq_nameset(fildes, names)
int fildes, names[];

FORTRAN77 Syntax:

subroutine inq_nameset_size(fildes, size)
integer*4 fildes, size

subroutine inq_nameset(fildes, names)
integer*4 fildes, names(*)

Pascal Syntax:

procedure inq_nameset_size(fildes:integer; var size:integer);

procedure inq_nameset(fildes:integer;
var names: array[lo..hi] of integer);

DESCRIPTION

Input Parameters

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

Output Parameters

size Number of integers needed to represent the names in the current active name set.

names Buffer within which the integers whose bits represent the names in the current active name set are returned.

Discussion

Inq_nameset_size and inq_nameset return information about the current active name set of the specified graphics device.

The active name set of a device is that subset of the (conceptually infinite) set of names that can affect a traversal. The active name set size of the device is the number of integers needed to express the active name set. Only names that are currently being used in filters can affect a traversal, so the active name set size is defined as the maximum of the sizes of the inclusion and exclusion sets of the device’s invisibility and pick filters. For example, if all the inclusion and exclusion sets of the device’s filters were of size zero (i.e. empty), the active name set size would also be zero. If one of the inclusion or exclusion sets were of size two (i.e. it used two integers’ worth of names) then the active name set size would be two integers as well.

The current name set of a device is all names that have been added to the current name set (via add_names_to_set(3G)) that haven’t been removed from the set (via remove_names_from_set(3G) or remove_all_names_from_set(3G)). The current active name set of a device consists of the current name set truncated or padded to the active name set size. In order to provide optimum traversal performance, the Starbase Display List maintains only this latter set (the current active name set) during traversal. Only those names that directly affect traversals are stored.

Inq_nameset_size sets size to the number of integers that make up the device’s current active name set. The names parameter passed to inq_nameset must be able to hold at least size integers.

Inq_nameset returns in names the list of integers whose bits represent the device’s current active name set.

ERRORS

1 Graphics device is not initialized for this operation.

DEFAULTS

When a graphics device is gopen’ed, the current active name set for the display list of that device is empty.

WARNING

When a filter change causes the active name set size to change, the current active name set changes size and is left in an undefined state. Remove_all_names_from_set(3G) should be used to restore the current active name set to a well-defined state after any filter change.

Museum

Related Articles