ctm_release_pv()

CTM_$RELEASE_PV                   Domain/OS                    CTM_$RELEASE_PV


NAME
     ctm_$release_pv - decrement pixel value use counts

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

     void ctm_$release_pv(
          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_$release_pv(
          in count: integer;
          in option: ctm_$alloc_options_t;
          in plane: integer;
          in 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_$release_pv(count, option, plane, pixel_values, status)

DESCRIPTION
     Ctm_$release_pv decrements use counts for pixel values allocated to the
     calling process.  A process should call ctm_$release_pv to free up pixel
     values it no longer needs so the CTM can allocate them to other
     processes.  Any unreleased pixel values allocated to a process will have
     their use counts decremented by the CTM when that process terminates.

     count
          Specifies the number of pixel values (or pixel value pairs) to be
          released.

     option
          Together with plane, this defines how ctm_$release_pv 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
               Decrement 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 decremented in the pixel_values
               argument.

          ctm_$zero_only
               Decrement the use counts for the count pixel values supplied in
               pixel_values.  The plane value is redundant.

          ctm_$one_only
               Decrement the use counts for the count pixel values supplied in
               pixel_values.  The plane value is redundant.

          ctm_$both
               Decrement 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 decremented 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 whose use counts are to be decremented by
          ctm_$release_pv.  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.  Ctm_$release_pv will fail when passed a
          pixel value with a use count of 0, and it will return with
          ctm_$not_allocated in status when passed a pixel value whose use
          count hasn't been incremented by the calling process at or above the
          current program level.
Museum
