Museum

CTM_$INC_USE_COUNT                Domain/OS                 CTM_$INC_USE_COUNT


NAME
     ctm_$inc_use_count - increment pixel value use counts

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

     void ctm_$inc_use_count(
          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_$inc_use_count(
          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_$inc_use_count(count, option, plane, pixel_values, status)

DESCRIPTION
     Ctm_$inc_use_count increments the use counts for the count pixel values
     (or pixel value pairs) specified by option, plane, and pixel_values.

     If a program runs in a single process that calls the CTM only via
     ctm_$find_color and relies on process termination to release allocated
     pixel values, then ctm_$inc_use_count will not be very useful and may,
     indeed, confuse the CTM.  However, ctm_$inc_use_count is invaluable when
     pixel values are shared between processes, or multiple program levels,
     that use ctm_$alloc_pv and ctm_$release_pv to manipulate the color map.

     A process can use ctm_$inc_use_count to retain an allocated pixel value
     passed to it by another process.  For example, if a process uses
     ctm_$inc_use_count to increment the use count for a pixel value it
     receives from another process, and the process that originally allocated
     the pixel value subsequently terminates or calls ctm_$release_pv for the
     passed pixel value, then the CTM is free to change the color associated
     with the passed pixel value.  The receiving process will be left with an
     unallocated pixel value, which may change colors as the CTM responds to
     requests from other processes.  But, if the receiving process uses
     ctm_$inc_use_count to increment the use count for the pixel value passed
     to it, the allocated color will remain fixed even after the originating
     process terminates because the pixel value's use count will still be
     nonzero.

     count
          Specifies the number of pixel values (or pixel value pairs) defined
          by option, plane, and pixel_values.

     option
          Together with plane, this defines how ctm_$inc_use_count will inter-
          pret 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
               Increment 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 incremented in the pixel_values
               argument.

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

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

          ctm_$both
               Increment 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 incremented in the pixel_values
               argument.

     plane
          Specifies a bitmap 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 incremented by
          ctm_$inc_use_count.  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.

NOTES
     Every time a process forks (via fork(2) of SysV, or fork(2) or vfork(2)
     of BSD), the CTM increments the use counts for all pixel values allocated
     to it.  The CTM also decrements the use counts for all pixel values allo-
     cated to a process during a subsequent SysV or BSD exec(2) call (execl,
     execle, execlp, exect, execv, execve, or execvp).  Therefore, a child
     process can retain any pixel values allocated to its parent by increment-
     ing their use counts before it execs.  This incrementing/decrementing
     mechanism insures that all pixel values allocated to a process remain
     allocated independent of the persistence of any parent or child
     processes.