CTM_$ALLOC_PV                     Domain/OS                      CTM_$ALLOC_PV


NAME
     ctm_$alloc_pv - allocate unused pixel values

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

     void ctm_$alloc_pv(
          short &count,
          ctm_$alloc_options_t &option,
          short &plane,
          ctm_$pixel_value_vector_t *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_$alloc_pv(
          in count: integer;
          in option: ctm_$alloc_options_t;
          var plane: integer;
          out pixel_values: 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_$alloc_pv(count, option, plane, pixel_values, status)

DESCRIPTION
     Ctm_$alloc_pv 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.

     count
          The number of pixel values (or pixel value pairs) requested.

     option
          A constraint placed on pixel values to be allocated.  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.  Ctm_$alloc_pv 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.
               Ctm_$alloc_pv 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.

     plane
          Specifies a bit plane used together with option to constrain the
          pixel values that ctm_$alloc_pv will supply.

     pixel_values
          An array of allocated pixel values that satisfy the constraints
          specified in option and plane.  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.

     status
          The completion status.

SEE ALSO
     ctm_$find_color, ctm_$release_pv.