REF XColorcells                                     A. Schoter, Jul 1991
                                        Revised: Adrian Howard, Jun 1993

        COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< MANIPULATION OF COLOR CELLS >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

In X colors are specified as a  pixel number which points to a  specific
color cell in  a colormap.  The functions detailed  here define  various
operations on colors and  color cells. See  REF * XColor for details  of
the structure used  to represent color  cells. See REF * XColormaps  for
details on the manipulation of colormaps.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Color Cells, Pixels, and Color Planes

  2   LIB XColorcells
      2.1   XColor flags constants
      2.2   Allocating, Modifying, and Freeing Color Cells
      2.3   Reading Colormap Entries
      2.4   Parsing the Color Specification

  3   Also of Interest



----------------------------------------
1  Color Cells, Pixels, and Color Planes
----------------------------------------

As mentioned  in the  overview, in  X colors  are specified  as a  pixel
number which points to a particular color cell in a colormap.  Different
windows can  have  their  own  colormaps, but  usually  they  share  the
colormap of the root window of the screen (see * DefaultColormap.)

It is very important to  realise that the pixel  number of a color  cell
has no relation to the actual color stored in that cell. The association
between pixel  numbers  and  RGB  (Red Green  Blue)  values  is  usually
arbitrary (see REF * XVisuals for more information.)

The number of bits per-pixel is the number of "planes" available. It  is
sometimes useful to associate groups of  pixels by having a sequence  of
bits set. For example, the first three bits of a pixel could be used  to
indicate the "color" while the forth is used to indicate the "group"  to
give the following:

        Pixel   Group   Color
        ----    -----   -----
        2:0000  0       0
        2:0001  0       1
        2:0010  0       2
        2:0011  0       3
        ...     ...     ...
        2:1000  1       0
        2:1001  1       1
        2:1010  1       2
        2:1011  1       3
        ...     ...     ...

If the second group of colors corresponded to "highlighted" versions  of
the first group, you  could "highlight" a  pixel merely by  manipulating
the forth  bit. You  often mask  bits in  this way  using integer  plane
masks. This kind of manipulation of  the colormap is only possible  when
the visual of the display being  used has sufficient planes, and  allows
the RGB values of color cells to be changed (see REF * XVisuals.)




------------------
2  LIB XColorcells
------------------

To load LIB * XColorcells do:

        uses xlib;
        uses XColorcells;

The procedures  and  constants  supplied  by  this  library  are  direct
equivalents of the Xlib  C functions and  constants. For information  on
the C functions see sections  5.1.2 'Allocating, Modifying, and  Freeing
Color Cells', 5.1.2 'Reading Entries  in a Colormap', and 10.4  'Parsing
the Color Specifications' in:

                      Xlib - C Language X Interface
                        MIT X Consortium Standard
                         X Version 11, Release 4

        Copyright (C) 1985, 1986, 1987, 1988, 1989 Massachusetts
        Institute of Technology,  Cambridge, Massachusetts,  and
        Digital Equipment Corporation, Maynard, Massachusetts.



2.1  XColor flags constants
---------------------------
The following constants are defined by LIB * XColorcells.


DoRed   -> (1 << 0)                                     [constant macro]
DoGreen -> (1 << 1)                                     [constant macro]
DoBlue  -> (1 << 2)                                     [constant macro]
        These flags are used in  the * XColor structures flags field  to
        indicate which of the red, green,  and blue fields is used.  See
        * XColor for details.



2.2  Allocating, Modifying, and Freeing Color Cells
---------------------------------------------------
Color  cells  can  either  be  allocated  as  read-only  entries  with a
specified color  that cannot  be changed,  or read/write  where the  RGB
values of the cell  can be changed. Any  read/write cells do not  have a
defined color until they are set with * XStoreColor or * XStoreColors.

NOTE: while it is possible to alter a read/write color cell allocated by
another application, this is considered to be "antisocial" X programming
behaviour.

Read-only color  cells can  be more  space efficient  because  different
clients requesting the same color will be allocated the same color cell.

X has a  color database  which allows colors  to be  specified by  name.
Using color  names makes  it  more likely  that different  clients  will
request the same colors,  and therefore make more  efficient use of  the
colormap. See HELP * XCOLOURS for information on possible color names.

See the  sections on  Standard  Colormaps in  REF * XColormaps  another
mechanism to increase efficent use of color cells and colormaps.


XAllocColor(displayptr, colormap, colorptr) -> status        [procedure]
        XAllocColor allocates  a  single  read-only color  cell  in  the
        colormap referred to by the XID colormap of the display referred
        to by displayptr.

        colorptr should  be an  * XColor structure  which specifies  the
        color that is wanted.  The actual color  allocated will be  the
        closest one  to  the  one  specified in  colorptr  that  can  be
        supported by the hardware currently being used. The actual color
        allocated will be stored in colorptr after the procedure exits.

        status will  be 0  if the  attempt to  allocate the  color  cell
        failed, non-zero otherwise.


XAllocNamedColor(displayptr, colormap, string,               [procedure]
                screen_colorptr_ret, exact_colorptr_ret) -> status
        XAllocNamedColor allocates a single read-only color cell in  the
        colormap referred to by the XID colormap of the display referred
        to by displayptr.

        string should be  the name  of the  color to  be allocated.  See
        HELP * XCOLOURS for possible color names.

        Both  screen_colorptr_ret  and   exact_colorptr_ret  should   be
        * XColor structures. The  value of the  color cell allocated  is
        returned in  screen_colorptr_ret. The  exact definition  of  the
        color named  string (from  the color  database) is  returned  in
        exact_colorptr_ret.

        status will  be 0  if the  attempt to  allocate the  color  cell
        failed, non-zero otherwise.

        XAllocNamedColor  can   give  a   "BadColor"  X   error  if   an
        inappropriate argument is supplied.


XLookupColor(displayptr, colormap, string,                   [procedure]
                exact_colorptr_ret, screen_colorptr_ret) -> status
        Applications often  need to  know what  the exact  value of  the
        color named 'red'  in the color  database may be  on display  to
        provide  a  good  user  interface.  XLookupColor  performs  like
        * XAllocNamedColor but does not allocate a color cell. This  can
        be used to query named colors in the color database. For details
        of  the   arguments   see   * XAllocNamedColor.   Compare   with
        * XParseColor.


XAllocColorCells(displayptr, colormap, contig,               [procedure]
                plane_mask_ret, nplanes, pixels_ret, npixels) -> status
        XAllocColorCells is the recommended way of allocating color cell
        and color  plane  combinations for  * PseudoColor  visuals  It's
        arguments are:

            displayptr
                The display to be used.

            colormap
                The XID of the colormap to be used.

            contig
                A boolean  value which,  if true  indicates whether  any
                allocated planes should  be contiguous. For  * GrayScale
                and * PseudoColor visuals this implies the  inclusive-OR
                of all plane masks will produce a single contiguous  set
                of bits set to 1.  For * DirectColor visuals there  will
                be three  sets  of contiguous  bits,  one for  each  RGB
                sub-field.

            plane_mask_ret
                An external pointer class object which will point to  an
                array of nplanes plane-masks after the procedure exits.

            nplanes
                An integer which specifies the number of plane-masks  to
                be returned via plane_mask_ret.  nplanes should be  zero
                or greater.

            pixels_ret
                An external pointer class object which will point to  an
                array of npixels pixel values after the procedure exits.

            npixels
                An integer which  specifies the number  of pixels to  be
                returned via pixels_ret. npixels should be greater  than
                zero.

        No plane-mask returned in plane_mask_ret will have any bits  set
        in common with any other plane-mask, or any of the pixel  values
        returned in pixels_ret. This enables a total of

            npixels * (2 ** nplanes)

        color cells to be accessed by inclusive ORing pixel values  from
        pixels_ret with zero  or more  plane-masks from  plane_mask_ret.
        All  these   color  cells   are  allocated   by  the   call   to
        XAllocColorCells.

        The  actual  RGB  values  of   the  color  cells  allocated   by
        XAllocColorCells is undefined.

        For  * GrayScale   or  * PseudoColor   visuals  each   mask   in
        plane_mask_ret  has  exactly  one  bit  set.  For  * DirectColor
        visuals, each mask has three bits set.

        status will be  0 if  the attempt  to allocate  the color  cells
        failed, non-zero otherwise.

        XAllocColorCells can generate "BadColor" and "BadValue" X errors
        if given incorrect arguments.

        Compare with * XAllocColorPlanes.


XAllocColorPlanes(displayptr, colormap, contig, pixels_ret,  [procedure]
                ncolors, nreds, ngreens, nblues, rmask_ret, gmask_ret,
                bmask_ret) -> status
        XAllocColorPlanes is  the recommended  way of  allocating  color
        cell combinations for * DirectColor visuals. It's arguments are:

            displayptr
                The display to be used.

            colormap
                The XID of the colormap to be used.

            contig
                If this is true then the bit-masks rmask_ret, gmask_ret,
                and bmask_ret will have contiguous  sets of bits set  to
                1.

            pixels_ret
                An external pointer class object which will point to  an
                array of ncolors pixel values after the procedure exits.

            ncolors
                An positive  integer  specifying  the  number  of  pixel
                numbers returned in pixels_ret.

            nreds, ngreens, nblues
                The (non-negative) number of red, green, and blue planes
                to be allocated.

            rmask_ret, gmask_ret, bmask_ret
                These should be external pointer class objects to ulongs
                as produced, for example, by:

                    initexptr_mem(SIZEOFTYPE(:int))

                After the procedure  exits these will  point to the  bit
                masks for the red, green, and blue planes. Their  values
                can be recovered using:

                    exacc :ulong mask_ret -> mask_val

                For * DirectColor visuals the bits set within each  mask
                will correspond with the corresponding RGB sub-field.

        No mask will have any bits set in common with any other mask, or
        any of the pixel values  returned in pixels_ret. This  enables a
        total of

            ncolors * (2 ** (nreds + ngreens + nblues))

        color cells to be accessed by inclusive ORing pixel values  from
        pixels_ret with zero or  more masks. All  these color cells  are
        allocated by  the call  to  XAllocColorPlanes. However,  in  the
        colormap there will only be "ncolors * (2 ** nreds)" independent
        red  entries,  "ncolors * (2 **   ngreens)"  independent   green
        entries, and "ncolors * (2 ** nblues)" independent blue entries.
        This is true for all visual types.

        When the colormap entry of a pixel value is changed (using,  for
        example, * XStoreColors,  * XStoreColor, or  * XStoreNamedColor)
        the  pixel  is  decomposed  according  to  the  masks  and   the
        corresponding independent entries are updated.

        status will be  0 if  the attempt  to allocate  the color  cells
        failed, non-zero otherwise.

        XAllocColorPlanes can produce "BadValue" and "BadColor" X errors
        if inappropriate arguments are given.


XStoreColors(displayptr, colormap, colorptr, ncolors)        [procedure]
        XStoreColors changes the RGB values  of the pixels specified  in
        the array of * XColor structures pointed to by colorptr. ncolors
        should be an integer indicating the number of XColor  structures
        colorptr points to. colormap  is the XID of  the colormap to  be
        updated on the display referred to by displayptr.

        The color  components to  be changed  are specified  by  setting
        * DoRed, * DoGreen,  and  * DoBlue in  the  flags field  of  the
        XColor structures pointed  to by  colorptr. If  the colormap  is
        installed any changes are visible immediately.

        An attempt is made to change all the color cells referred to  by
        colorptr, even if some of them cause errors.

        A "BadValue" X  error if one  of the specified  pixels is  not a
        valid index into the specified  colormap. A "BadAccess" X  error
        occurs if one of the  specified pixels refers to an  unallocated
        or read-only color cell. If more than one pixel is in error,  it
        is arbitrary  which  one gets  reported.  A "BadColor"  X  error
        occurs if an invalid color is specified.


XStoreColor(displayptr, colormap, colorptr)                  [procedure]
        XStoreColor changes the RGB values of the pixel specified by the
        * XColor structure  pointed  to  by  colorptr  in  the  colormap
        colormap of the  display referred to  by displayptr.  Equivalent
        of:

            XStoreColors(%1%);


XStoreNamedColor(displayptr, colormap, string, pixel, flags) [procedure]
        XStoreNamedColor changes  the RGB  values  of the  pixel  number
        pixel to that of the color named string (see HELP * XCOLOURS for
        possible color names.) colormap is the XID of the colormap to be
        used. displayptr specifies the display.

        flags is an integer bit-mask used  to specify which of the  red,
        green, and blue components of the color cell are to be  changed.
        It should be an inclusive-OR of some of * DoRed, * DoGreen,  and
        * DoBlue.

        XStoreNamedColor   can    generate   "BadAccess",    "BadColor",
        "BadName",  and  "BadValue"  X  errors  if  given  inappropriate
        arguments.


XFreeColors(displayptr, colormap, pixelsptr, npixels, planes)[procedure]
        XFreeColors frees the color cells pointed to by pixelsptr  which
        should point  to npixels  ulong numbers  representing the  pixel
        numbers to be freed. Such a structure could be created with:

            vars pixelsptr = initexptr_mem(SIZEOFTYPE(:ulong) * npixels)

        and accessed with

            pixel_N -> exacc :ulong[] pixelsptr[N];

        colormap is the XID of the colormap to be used while  displayptr
        specifies the display.

        planes should be an integer bit-mask specifying any planes  that
        should be freed. planes should not  have any bits set in  common
        with the pixels pointed to by pixelsptr.

        The  actual   color  cells   to  be   freed  are   produced   by
        inclusive-ORing together subsets  of planes  with the  specified
        pixel numbers.

        All specified pixels  are freed, even  if one (or  more) of  the
        pixels produces an error.

        Freeing a single  pixel allocated  with * XAllocColorPlanes  may
        not actually allow  it to  be reused  until all  of its  related
        pixels are also freed.

        A read-only colormap entry is not  freed for reuse until it  has
        freed by every  client which  allocated it. If  a single  client
        allocates a  read-only colormap  entry multiple  times, then  it
        must be freed multiple times before it can be reused.

        XFreeColors can generate "BadAccess", "BadColor", and "BadValue"
        X errors if inappropriate arguments are supplied.




2.3  Reading Colormap Entries
-----------------------------
The following  procedures  allow  the  RGB value  of  color  cells  in a
colormap to be queried.


XQueryColors(displayptr, colormap, colorptr, ncolors)        [procedure]
        XQueryColors returns the RGB values of all the pixels  specified
        by the  array of  * XColor structures  pointed to  by  colorptr.
        ncolors should be the number of XColor structures in this array.

        The RGB  values  of  the  specified pixels  are  stored  in  the
        appropriate fields of the  XColor structures when the  procedure
        exits.  The  values  returned  for  an  unallocated  entry   are
        undefined. The  * DoRed, * DoGreen  and  * DoBlue bits  of  each
        XColors flags field are also set.

        colormap is the XID of the colormap to be used, while displayptr
        specifies the display.

        XQueryColors can generate "BadColor" and "BadValue" X errors  if
        inappropriate arguments are given.


XQueryColor(displayptr, colormap, colorptr)                  [procedure]
        XQueryColor returns the RGB value of the pixel specified by  the
        * XColor structure pointed to by colorptr. Equivalent to:

            XQueryColors(%1%)



2.4  Parsing the Color Specification
------------------------------------
XParseColor(displayptr, colormap, string, colorptr_ret)      [procedure]
                -> status
        This procedure is provided to make a standard user interface  to
        color simple. It  takes a  string specification of  a color  and
        returns the corresponding  red, green,  and blue  values in  the
        * XColor structure pointed to  by colorptr_ret. colormap is  the
        XID of the colormap  to be used  while displayptr specifies  the
        display.

        The  color  can  be  specified  either  as  a  color  name  (see
        HELP * XCOLOURS), or as an initial hash sign character following
        by a numeric specification, in one of the following formats:

                String          Num. of bits
                ------          ------------
                #RGB            4
                #RRGGBB         8
                #RRRGGGBBB      12
                #RRRRGGGGBBBB   16

        where R, G, and B represent single hexadecimal digits (upper  or
        lower case). When fewer  than 16 bits  each are specified,  they
        represent the most significant bits  of the value. For  example,
        #3A7 is the same as #3000A0007000.

        This routine will fail if the  initial character is a hash  sign
        and the string otherwise fails to fit any of the above  formats,
        or if the  initial character is  not a hash  sign and the  named
        color does not exist in the server's database.

        status will  be 0  if the  attempt to  parse the  color  failed,
        non-zero otherwise.

        XParseColor can generate a "BadColor" X error if given incorrect
        arguments.

        Compare with * XLookupColor




-------------------
3  Also of Interest
-------------------

The following functions may also be of interest:

 #  * WhitePixel, and * BlackPixel
 #  * DefaultColormap
 #  * PlanesOfScreen
 #  * CellsOfScreen
 #  * MinCmapsOfScreen, and * MaxCmapsOfScreen

See REF * XlibMacros for details.




--- C.x/x/pop/ref/XColorcells
--- Copyright University of Sussex 1993. All rights reserved.
