CTM_$INC_USE_COUNT CTM Calls CTM_$INC_USE_COUNT
NAME
ctm_$inc_use_count - increments pixel value use counts.
FORMAT
ctm_$inc_use_count (count, option, plane, pixel_values, status)
DESCRIPTION
The ctm_$inc_use_count routine increments the use counts for the count
pixel values (or pixel value pairs) specified by option, plane, and
pixel_values.
If a program runs in a single process that calls the CTM only via
ctm_$find_color and relies on process termination to release allocated
pixel values, then ctm_$inc_use_count will not be very useful and may,
indeed, confuse the CTM. However, ctm_$inc_use_count is invaluable when
pixel values are shared between processes, or multiple program levels,
that use ctm_$alloc_pv and ctm_$release_pv to manipulate the color map.
A process can use ctm_$inc_use_count to retain an allocated pixel value
passed to it by another process. For example, if a process uses
ctm_$inc_use_count to increment the use count for a pixel value it
receives from another process, and the process that originally allocated
the pixel value subsequently terminates or calls ctm_$release_pv for the
passed pixel value, then the CTM is free to change the color associated
with the passed pixel value. The receiving process will be left with an
unallocated pixel value, which may change colors as the CTM responds to
requests from other processes. But, if the receiving process uses
ctm_$inc_use_count to increment the use count for the pixel value passed
to it, the allocated color will remain fixed even after the originating
process terminates because the pixel value's use count will still be
nonzero.
Input Parameters
count
Specifies the number of pixel values (or pixel value pairs) defined
by option, plane, and pixel_values. This parameter is a 2-byte
integer.
option
Together with plane, this defines how ctm_$inc_use_count will inter-
pret pixel_values, in ctm_$alloc_options format. This is a 2-byte
integer. Although this argument is a small set type, the CTM
currently accepts only one option at a time, so choose only one from
the following:
ctm_$contiguous
Increment the use count for count contiguous pixel values,
starting from the first pixel value passed in pixel_value.
When specifying ctm_$contiguous, pass only the lowest pixel
value whose use count is to be incremented in the pixel_values
argument.
ctm_$zero_only
Increment the use counts for the count pixel values supplied in
pixel_values. The plane value is redundant.
ctm_$one_only
Increment the use counts for the count pixel values supplied in
pixel_values. The plane value is redundant.
ctm_$both
Increment the use counts for count pairs of pixel values, where
the members of each pair differ only in the plane bit. When
specifying ctm_$both, pass only the lowest pixel value of each
pair of pixel values to be incremented in the pixel_values
argument.
plane
Specifies a bitmap plane used together with option to define the
pixel values supplied in pixel_values. This parameter is a 2-byte
integer. plane specifies a pixel value bit position or a plane in
the display bitmap. Unless option is ctm_$both, the value of plane
is ignored by ctm_$inc_use_count.
pixel_values
An array of pixel values whose use counts are to be incremented by
ctm_$inc_use_count, in ctm_$pixel_value_vector_t format. This
parameter is an array of 4-byte integers. If option is
ctm_$continuous, then pass only one pixel value in pixel_values.
Otherwise, pixel_values should contain count pixel values.
Output Parameters
status
The completion status, in status_t format.
NOTES
Every time a process forks (via fork of SysV, or fork or vfork of BSD),
the CTM increments the use counts for all pixel values allocated to it.
The CTM also decrements the use counts for all pixel values allocated to
a process during a subsequent UNIX exec call. Therefore, a child process
can retain any pixel values allocated to its parent by incrementing their
use counts before it execs. This incrementing/decrementing mechanism
insures that all pixel values allocated to a process remain allocated
independent of the persistence of any parent or child processes.