Museum

CTM_$MARK_READ_ONLY               Domain/OS                CTM_$MARK_READ_ONLY


NAME
     ctm_$mark_read_only - share pixel values with other processes

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/gpr.h>
     #include <apollo/ctm.h>

     void ctm_$mark_read_only(
          short &count,
          ctm_$alloc_options_t &option,
          short &plane,
          void *pixel_values,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/gpr.ins.pas';
     %include '/sys/ins/ctm.ins.pas';

     procedure ctm_$mark_read_only(
          in count: integer;
          in option: ctm_$alloc_options_t;
          in plane: integer;
          in pixel value: univ ctm_$pixel_value_vector_t;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/ctm.ins.ftn'

           integer*2 count, option, plane
           integer*4 status, pixel_values(256)

           call ctm_$mark_read_only(count, option, plane, pixel_values, status)

DESCRIPTION
     Ctm_$mark_read_only makes pixel values allocated to the calling 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.  Ctm_$mark_read_only 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.

     count
          Specifies the number of pixel values (or pixel value pairs) to be
          shared with other processes via ctm_$find_color.

     option
          Together with plane, this defines how ctm_$mark_read_only will
          interpret pixel_values.  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.  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.  If option is ctm_$continuous, then pass only one
          pixel value in pixel_values.  Otherwise, pixel_values should contain
          count pixel values.

     status
          The completion status.