CTM_$MARK_READ_ONLY CTM Calls CTM_$MARK_READ_ONLY
NAME
ctm_$mark_read_only - shares pixel values with other processes.
FORMAT
ctm_mark_read_only (count, option, plane, pixel_values, status)
DESCRIPTION
The ctm_$mark_read_only routine makes pixel values allocated to the cal-
ling process via ctm_$alloc_pv available to other processes. Unless a
process calls ctm_$mark_read_only, the CTM reserves the pixel values
allocated via ctm_$alloc_pv for the use of that process only. The CTM
will never return such a reserved pixel value to another process that
calls ctm_$find_color, on the assumption that pixel values allocated via
ctm_$alloc_pv will not, in general, have a stable color value and are not
safe for other processes to use.
However, if a process will not change the colors of pixel values it has
allocated, it can call ctm_$mark_read_only to make the pixel values it
has allocated available to other processes. When a pixel value is passed
to ctm_$mark_read_only, other processes can use the pixel value by cal-
ling ctm_$find_color to access its associated color, but they cannot
change its color value. The ctm_$mark_read_only routine can, therefore,
enhance the utility of a limited color map by preventing the CTM from
assigning the same color to too many different pixel values.
The CTM will not prevent a process from changing the color of a pixel
value allocated to it, even after the process has called
ctm_$mark_read_only, so ctm_$mark_read_only should be used with caution.
If the process later assigns a new color value to a pixel value supplied
to other processes via ctm_$find_color, the other processes will get the
new color whenever they access that pixel value. Sometimes this is a
useful mechanism by which one process can transparently control the
colors displayed by other processes.
Input Parameters
count
Specifies the number of pixel values (or pixel value pairs) to be
shared with other processes via ctm_$find_color. This parameter is
a 2-byte integer.
option
Together with plane, this defines how ctm_$mark_read_only will
interpret pixel_values. This parameter is in ctm_$alloc_options_t
format, which 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
Make count contiguous pixel values, starting from the first pixel
value passed in pixel_value, available to other processes. When
specifying ctm_$contiguous, pass only the lowest pixel value to
be shared with other processes in the pixel_values argument.
ctm_$zero_only
Make the count pixel values supplied in pixel_values available to
other processes. The plane value is redundant.
ctm_$one_only
Make the count pixel values supplied in pixel_values with 1s in
the plane bit available to other processes. The plane value is
redundant.
ctm_$both
Make count pairs of pixel values, where the members of each pair
differ only in the plane bit, available to other processes. When
specifying ctm_$both, pass only the lowest pixel value of each
pair of pixel values to be shared in the pixel_values argument.
plane
Specifies a bit 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 to be shared with other processes on a
"read only" basis, in ctm_$pixel_value_vector_t format. This param-
eter 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.