CTM_$ALLOCATE_PV                  CTM Calls                   CTM_$ALLOCATE_PV


NAME
     ctm_$allocate_pv - allocates available pixel values and sets their use
     counts to one.

FORMAT
     ctm_$allocate_pv (count, option, plane, pixel_values, status)

DESCRIPTION
     The ctm_$alloc_pv routine searches for pixel values that have use counts
     of 0 and also satisfy the constraints specified by the option parameter.
     ctm_$alloc_pv sets the use counts for the allocated pixel values to 1,
     and returns with an array of them in pixel_values.

   Input Parameters
     count
          The number of pixel values (or pixel value pairs) requested.  This
          is a 2-byte integer.

     option
          A constraint placed on pixel values to be allocated, in
          ctm_$alloc_options_t format.  This is a 2-byte integer.  Although
          this argument is a small set type, the CTM can currently satisfy
          only one constraint at a time, so choose only one of the following
          values:

          ctm_$contiguous
               Contiguous pixel values.  ctm_$alloc_pv will allocate count
               contiguous pixel values, but will supply only the lowest allo-
               cated pixel value in pixel_values.

          ctm_$zero_only
               Pixel values with 0s in a specified plane or bit position.  If
               plane is greater than or equal to 0, then ctm_$alloc_pv will
               allocate count pixel values with 0s in the plane bit.  If plane
               is less than 0, then ctm_$alloc_pv will allocate count pixel
               values with 0s in some arbitrary plane and supply the position
               it chose in plane.  The ctm_$alloc_pv routine supplies the
               allocated pixel values in pixel_values.

          ctm_$one_only
               Pixel values with only 1s in a specified plane or bit position.
               This is similar to ctm_$zero_only except that the specified
               plane or bit position in the supplied pixel values will contain
               only 1s.

          ctm_$both
               Pairs of pixel values that differ only in a single plane; that
               is, pixel value pairs that differ in only one bit.  If plane is
               greater than or equal to 0, then ctm_$alloc_pv will allocate
               count pairs of pixel values in which the members of each pair
               differ only in the plane bit.  If plane is less than 0, then
               ctm_$alloc_pv will allocate count pairs of pixel values where
               the members of each pair differ only in some arbitrary bit
               position, and supply the position it chose in plane.  The
               ctm_$alloc_pv routine supplies only the lowest pixel value from
               each allocated pair in pixel_values.

          Specify 0 in FORTRAN or C, or [] in Pascal, when no particular pixel
          values are preferred.  This constraint is the easiest for
          ctm_$alloc_pv to satisfy.

   Input/Output Parameters
     plane
          Specifies a bit plane used together with option to constrain the
          pixel values that ctm_$alloc_pv will supply.  This parameter is a
          2-byte integer.

   Output Parameters
     pixel_values
          An array of allocated pixel values that satisfy the constraints
          specified in option and plane, in ctm_$pixel_value_vector_t format.
          If option is ctm_$contiguous, then ctm_$alloc_pv returns with only
          one allocated pixel value in pixel_values.  Otherwise, it returns
          with count allocated pixel values in pixel_values.

          ctm_$pixel_value_vector_t is an array of pixel values in
          gpr_$pixel_value_t format.

     status
          The completion status.

SEE ALSO
     ctm_$find_color, ctm_$release_pv.

NOTES
     The CTM (Color Table Manager) package operates on a data base of pixel
     values that is shared by all processes using GPR in direct or frame mode.
     The CTM calls allow different applications on the same node to share a
     color map without interfering with one another.

     Borrow mode applications have a separate, private copy of the color map,
     which is initialized to default values by gpr_$init or gpr_$initialize.

     The CTM package keeps track of how many processes can access a pixel
     value by maintaining a use count for each pixel value.  All pixel values
     except those preallocated by the Display Manager (see below) have an ini-
     tial use count of zero, which means that they are available for alloca-
     tion.

     As each process gains access to a pixel value, the pixel value's use
     count is incremented.  For example, if five processes are sharing a pixel
     value, its use count is five.  When a process releases a pixel value
     (using ctm_$release_pv) its use count is decremented.  When the use count
     reaches zero, the pixel can be reallocated.

     The CTM routines are advisory in nature and do not affect the validity of
     calls to gpr_$set_color_map.  Any pixel value may be set by any program,
     including the pixel values used by the Display Manager for window colors.
     The Display Manager preallocates values 0, 1, and 7 through 15.  However,
     the Display Manager will release pixel values 8 through 15 when you use
     the mono command (see the Domain System Call Reference.