add_names_to_set(3G)

NAME

add_names_to_set − add names to the current name set

SYNOPSIS

C Syntax:

void add_names_to_set(fildes, count, names)
int fildes, count, names[];

FORTRAN77 Syntax:

subroutine add_names_to_set(fildes, count, names)
integer*4 fildes, count, names(count)

Pascal Syntax:

procedure add_names_to_set(fildes, count:integer;
var names[lo..hi:integer] of integer);

DESCRIPTION

Input Parameters

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

count Number of integers in the names array that represents bit strings of names.

names Array of integer bit strings representing names to be added to the current name set.

Discussion

Add_names_to_set adds the given names to the current name set of the display list on the specified graphics device. Names may be removed from the current name set by remove_names_from_set(3G) and remove_all_names_from_set(3G). The use of name sets allows the programmer to divide a segment hierarchy into logical sections, the visibility, highlighting and pickability of which may be controlled by invisibility, highlighting and pick filters (see set_invisibility_filter(3G), set_highlighting_filter(3G), and set_pick_filter(3G)).

Each bit in each integer 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 only limited by available memory.

When add_names_to_set or an add_names_to_set element is executed, the specified names are added (mathematical set union) to the current name set. This changes the current name set which in conjunction with the current filters controls how display list traversal processes subsequent elements. See the manual pages for each filter for descriptions of the filter’s effects.

EXAMPLE

A C programmer writing an application wishes to create a segment with primitives that have various names associated with them. Assuming in each instance that fd contains a gopen’ed file descriptor, segno contains a segment name, and the names array holds the names that the programmer will be adding and removing from the current name set, the following calls would accomplish this:

/* Open the desired segment */
open_segment(fd, segno);
/* Add the desired names to the name set */
names[0] = 21; /* bits 5, 3, and 1 in the first integer */
names[1] = 7; /* bits 3, 2, and 1 in the second integer */
add_names_to_set(fd, 2, names); /* 2 integers of names */
/* Draw the primitive that the names will be associated with */
polygon2d(fd, ...);
/* Remove some of the names from the name set */
names[0] = 17; /* bits 5 and 1 in the first integer */
remove_names_from_set(fd, 1, names); /* 1 integer of names */
/* Add a few more names */
names[0] = 32; /* bit 6 in the first integer */
names[1] = 0; /* no bits in the second integer */
names[2] = 31; /* bits 5, 4, 3, 2, and 1 in the 3rd integer */
add_names_to_set(fd, 3, names); /* 3 integers of names */
/* Draw the primitives with which the names will be associated */
line_color_index(fd, 2);
rectangle(fd, ...);
text2d(fd, ...);
/* Remove all the names from the set */
remove_all_names_from_set(fd);
/* Draw a primitive with which no names are associated */
polyline2d(fd, ...);
/* Done with the segment */
close_segment(fd);

For further examples, see the /usr/lib/sbdl/demos directory.

ERRORS

1 Graphics device is not initialized for this operation.

6 Invalid parameter value − count less than 0.

DEFAULTS

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

Museum

Related Articles