LibGGIGCP Functions
===================



Initialize and uninitialize LibGGIGCP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpInit gcpExit gcpAttach gcpDetach


Synopsis
--------

::

   #include <ggi/gcp.h>

   int gcpInit(void);

   int gcpExit(void);

   int gcpAttach(ggi_visual_t vis);

   int gcpDetach(ggi_visual_t vis);


Description
-----------

These are the standard LibGGI extension management functions for the
LibGGIGCP extension. They allow initialization and deinitialization
of the extension as a whole and of individual visuals.

`gcpInit` will initialize an instance of the LibGGIGCP extension and
prepare it to attach to visuals.

`gcpAttach`, if successful, will allow LibGGIGCP functions to
operate on the named visual.

`gcpDetach`, if successful, will clean up all resources involved in
providing the named visual with the LibGGIGCP API.

`gcpExit` will free all resources associated with an instance of
LibGGIGCP.


Return value
------------

`gcpInit` returns `0` for OK, otherwise an :man:`ggi-error(3)` code.


`gcpExit` returns:

`0`
    after successfully cleaning up,

`>0`
    the number of 'open' `gcpInit` calls, if there has been more than
    one call to `gcpInit`. As `gcpInit` and `gcpExit` must be
    used in properly nested pairs, e.g. the first `gcpExit` after two
    `gcpInit`'s will return `1`.

`<0`
    :man:`ggi-error(3)`, especially if more `gcpExit` calls have been done than
    `gcpInit` calls.

`gcpAttach` returns:

`>=0`
    the number LibGGIGCP has been attached to this visual, whereas
    0 means the first time.

`<0`
    indicates an :man:`ggi-error(3)`.


`gcpDetach` returns:

`0`
    after successfully cleaning up,

`>0`
    the number of 'open' `gcpAttach` calls, if there has been more than
    one call to `gcpAttach`. As `gcpAttach` and `gcpDetach` must be
    used in properly nested pairs, e.g. the first `gcpDetach` after two
    `gcpInit`'s will return `1`.

`<0`
    :man:`ggi-error(3)`, especially if more `gcpDetach` calls have been done than
    `gcpAttach` calls.


Examples
--------

::

  ggi_visual_t vis;

  ggiInit();
  gcpInit();
  vis = ggiOpen(NULL);
  gcpAttach(vis);

  /* ... */

  gcpDetach(vis);
  gcpExit();
  ggiExit();



Convert from gcp_*color(s) to gcp_pixel(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpMapRGBAColor gcpPackRGBAColors gcpMapYUVColor gcpPackYUVColors gcpMapCMYKColor gcpPackCMYKColors gcpMapHSVColor gcpPackHSVColors gcpMapYCCColor gcpPackYCCColors


Synopsis
--------

::

  #include <ggi/gcp.h>

  gcp_pixel gcpMapRGBAColor(ggi_visual_t vis,
                gcp_RGBAcolor *col);
  int gcpPackRGBAColors(ggi_visual_t vis,
                void *buf,gcp_RGBAcolor *cols,int len);

  gcp_pixel gcpMapYUVColor(ggi_visual_t vis,
                gcp_YUVcolor *col);
  int gcpPackYUVColors(ggi_visual_t vis,
                void *buf,gcp_YUVcolor *cols,int len);

  gcp_pixel gcpMapCMYKColor(ggi_visual_t vis,
                gcp_CMYKcolor *col);
  int gcpPackCMYKColors(ggi_visual_t vis,
                void *buf,gcp_CMYKcolor *cols,int len);

  gcp_pixel gcpMapHSVColor(ggi_visual_t vis,
                gcp_HSVcolor *col);
  int gcpPackHSVColors(ggi_visual_t vis,
                void *buf,gcp_HSVcolor *cols,int len);

  gcp_pixel gcpMapYCCColor(ggi_visual_t vis,
                gcp_YCCcolor *col);
  int gcpPackYCCColors(ggi_visual_t vis,
                void *buf,gcp_YCCcolor *cols,int len);


Description
-----------

`gcpMap*Color` gets the pixelvalue for the given color.


`gcpPack*Colors` converts the colors in :p:`cols` to pixelvalues in
:p:`buf`.  The output from this function is suitable for input to the
`ggiPut{HLine,VLine,Box}` functions.


Try to cache the results of color lookups in your application for
efficiency purposes.



Return value
------------

`gcpMap*Color` returns a :man:`gcp_pixel(3)`.

`gcp*PackColors` returns `0` for OK, otherwise an :man:`ggi-error(3)` code.


See Also
--------

:man:`gcp_pixel(3)`,
:man:`gcpUnmapRGBAPixel(3)`, :man:`gcpUnpackRGBAPixels(3)`,
:man:`gcpUnmapYUVPixel(3)`, :man:`gcpUnpackYUVPixels(3)`,
:man:`gcpUnmapCMYKPixel(3)`, :man:`gcpUnpackCMYKPixels(3)`,
:man:`gcpUnmapHSVPixel(3)`, :man:`gcpUnpackHSVPixels(3)`,
:man:`gcpUnmapYCCPixel(3)`, :man:`gcpUnpackYCCPixels(3)`
:man:`ggiPutBox(3)`, :man:`ggiPutHLine(3)`, :man:`ggiPutVLine(3)`


Convert from gcp_pixel(s) to gcp_*colors(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpUnmapRGBAPixel gcpUnpackRGBAPixels gcpUnmapYUVPixel gcpUnpackYUVPixels gcpUnmapCMYKPixel gcpUnpackCMYKPixels gcpUnmapHSVPixel gcpUnpackHSVPixels gcpUnmapYCCPixel gcpUnpackYCCPixels


Synopsis
--------

::

  #include <ggi/gcp.h>

  int gcpUnmapRGBAPixel(ggi_visual_t vis,
                gcp_pixel pixel,gcp_RGBAcolor *col);
  int gcpUnpackRGBAPixels(ggi_visual_t vis,
                void *buf,gcp_RGBAcolor *cols,int len);

  int gcpUnmapYUVPixel(ggi_visual_t vis,
                gcp_pixel pixel, gcp_YUVcolor *col);
  int gcpUnpackYUVPixels(ggi_visual_t vis,
                void *buf,gcp_YUVcolor *cols,int len);

  int gcpUnmapCMYKPixel(ggi_visual_t vis,
                gcp_pixel pixel, gcp_CMYKcolor *col);
  int gcpUnpackCMYKPixels(ggi_visual_t vis,
                void *buf,gcp_CMYKcolor *cols,int len);

  int gcpUnmapHSVPixel(ggi_visual_t vis,
                gcp_pixel pixel, gcp_HSVcolor *col);
  int gcpUnpackHSVPixels(ggi_visual_t vis,
                void *buf,gcp_HSVcolor *cols,int len);

  int gcpUnmapYCCPixel(ggi_visual_t vis,
                gcp_pixel pixel, gcp_YCCcolor *col);
  int gcpUnpackYCCPixels(ggi_visual_t vis,
                void *buf,gcp_YCCcolor *cols,int len);


Description
-----------

`gcpUnmap*Pixel` gets the color associated with the given pixelvalue.


`gcpUnpack*Pixels` converts the pixelvalues in :p:`buf` to individual
elements of :p:`cols`.  This function may be used to convert buffers
output by the `ggiGet{HLine,VLine,Box}` functions from the pixelvalue
representation to their actual colors as defined by :man:`gcp_color(3)`.


Try to cache the results of color lookups in your application for
efficiency purposes.


Return value
------------

`gcpUnmap*Pixel` and `gcpUnpack*Pixels` return `0`
for OK, otherwise an :man:`ggi-error(3)` code.


See Also
--------

:man:`gcp_color(3)`, :man:`gcp_pixel(3)`,

:man:`gcpMapRGBAColor(3)`, :man:`gcpPackRGBAColors(3)`,
:man:`gcpMapYUVColor(3)`, :man:`gcpPackYUVColors(3)`,
:man:`gcpMapCMYKColor(3)`, :man:`gcpPackCMYKColors(3)`,
:man:`gcpMapHSVColor(3)`, :man:`gcpPackHSVColors(3)`,
:man:`gcpMapYCCColor(3)`, :man:`gcpPackYCCColors(3)`
:man:`ggiGetBox(3)`, :man:`ggiGetHLine(3)`, :man:`ggiGetVLine(3)`


Manipulate the palette of a visual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpSetRGBAPalette gcpGetRGBAPalette gcpSetYUVPalette gcpGetYUVPalette gcpSetCMYKPalette gcpGetCMYKPalette gcpSetHSVPalette gcpGetHSVPalette gcpSetYCCPalette gcpGetYCCPalette


Synopsis
--------

::

  #include <ggi/gcp.h>

  int gcpGetRGBAPalette(ggi_visual_t vis,
                int s,int len,gcp_RGBAcolor *cmap);
  int gcpSetRGBAPalette(ggi_visual_t vis,
                int s,int len,gcp_RGBAcolor *cmap);

  int gcpGetYUVPalette(ggi_visual_t vis,
                int s,int len,gcp_YUVcolor *cmap);
  int gcpSetYUVPalette(ggi_visual_t vis,
                int s,int len,gcp_YUVcolor *cmap);

  int gcpGetCMYKPalette(ggi_visual_t vis,
                int s,int len,gcp_CMYKcolor *cmap);
  int gcpSetCMYKPalette(ggi_visual_t vis,
                int s,int len,gcp_CMYKcolor *cmap);

  int gcpGetHSVPalette(ggi_visual_t vis,
                int s,int len,gcp_HSVcolor *cmap);
  int gcpSetHSVPalette(ggi_visual_t vis,
                int s,int len,gcp_HSVcolor *cmap);

  int gcpGetYCCPalette(ggi_visual_t vis,
                int s,int len,gcp_YCCcolor *cmap);
  int gcpSetYCCPalette(ggi_visual_t vis,
                int s,int len,gcp_YCCcolor *cmap);


Description
-----------

LibGGIGCP visuals in `GT_PALETTE` mode map all pixelvalues to the
corresponding :man:`gcp_color(3)` entry in the visual's palette.


`gcpSet*Palette` sets a range of palette values of length :p:`len`,
starting at index number :p:`s`.  The index can be
`GCP_PALETTE_DONTCARE` to indicate that the palette can be
installed anywhere in the CLUT.  This allows optimized use in
windowing environments (to minimize color flashing between windows)
and should be used if possible.


`gcpGet*Palette` copies the specified colors (starting from :p:`s`, for
:p:`len` colors) from the visual's palette to the array pointed by
:p:`cmap`.


Return value
------------

`gcpSet*Palette` returns the number of the first entry changed.
`<0` indicate :man:`ggi-error(3)`.


`gcpGet*Palette` returns `0` for OK, otherwise an :man:`ggi-error(3)`
code. When called with len=0 this function will not automatically
succeed, but the return code will indicate whether there is a
readable CLUT.


See Also
--------

:man:`gcpSetColorfulPalette(3)`



Set a palette with a full range of all colors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpSetColorfulPalette


Synopsis
--------

::

  #include <ggi/gcp.h>

  int gcpSetColorfulPalette(ggi_visual_t vis);


Description
-----------

LibGGIGCP guarantees that there will be a default palette when a
palettized mode is set.  What this default is, however, is dependent
on the visual.  For example, the X target deliberately avoids setting
all colors to avoid color-flashing when moving between windows.


Applications that want to ensure that they have a full scale of all
colors can call `gcpSetColorfulPalette` after mode set.  This function
uses a smarter color allocation scheme, causing good colors but still
minimal flashing in windowed targets.


Return value
------------

`gcpSetColorfulPalette` returns the number of the first entry changed.
`<0` indicate :man:`ggi-error(3)`.


See Also
--------

:man:`gcpSetRGBAPalette(3)`, :man:`gcpSetYUVPalette(3)`,
:man:`gcpSetCMYKPalette(3)`, :man:`gcpSetHSVPalette(3)`,
:man:`gcpSetYCCPalette(3)`



Manipulate the gamma maps and the gamma correction of a visual
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpGetRGBAGamma gcpSetRGBAGamma gcpGetRGBAGammaMap gcpSetRGBAGammaMap gcpGetYUVGamma gcpSetYUVGamma gcpGetYUVGammaMap gcpSetYUVGammaMap gcpGetCMYKGamma gcpSetCMYKGamma gcpGetCMYKGammaMap gcpSetCMYKGammaMap gcpGetHSVGamma gcpSetHSVGamma gcpGetHSVGammaMap gcpSetHSVGammaMap gcpGetYCCGamma gcpSetYCCGamma gcpGetYCCGammaMap gcpSetYCCGammaMap


Synopsis
--------

::

  #include <ggi/gcp.h>

  int gcpGetRGBAGamma(ggi_visual_t vis,
                ggi_float *r,ggi_float *g,ggi_float *b);
  int gcpSetRGBAGamma(ggi_visual_t vis,
                ggi_float r,ggi_float g,ggi_float b);

  int gcpGetRGBAGammaMap(ggi_visual_t vis,
                int s,int len,gcp_RGBAcolor *gammamap);
  int gcpSetRGBAGammaMap(ggi_visual_t vis,
                int s,int len,gcp_RGBAcolor *gammamap);

  int gcpGetYUVGamma(ggi_visual_t vis,
                ggi_float *y,ggi_float *u,ggi_float *v);
  int gcpSetYUVGamma(ggi_visual_t vis,
                ggi_float y,ggi_float u,ggi_float v);

  int gcpGetYUVGammaMap(ggi_visual_t vis,
                int s,int len,gcp_YUVcolor *gammamap);
  int gcpSetYUVGammaMap(ggi_visual_t vis,
                int s,int len,gcp_YUVcolor *gammamap);

  int gcpGetCMYKGamma(ggi_visual_t vis,
                ggi_float *c,ggi_float *m,ggi_float *y,ggi_float *k);
  int gcpSetCMYKGamma(ggi_visual_t vis,
                ggi_float c,ggi_float m,ggi_float y,ggi_float k);

  int gcpGetCMYKGammaMap(ggi_visual_t vis,
                int s,int len,gcp_CMYKcolor *gammamap);
  int gcpSetCMYKGammaMap(ggi_visual_t vis,
                int s,int len,gcp_CMYKcolor *gammamap);

  int gcpGetHSVGamma(ggi_visual_t vis,
                ggi_float *h,ggi_float *s,ggi_float *v);
  int gcpSetHSVGamma(ggi_visual_t vis,
                ggi_float h,ggi_float s,ggi_float v);

  int gcpGetHSVGammaMap(ggi_visual_t vis,
                int s,int len,gcp_HSVcolor *gammamap);
  int gcpSetHSVGammaMap(ggi_visual_t vis,
                int s,int len,gcp_HSVcolor *gammamap);

  int gcpGetYCCGamma(ggi_visual_t vis,
                ggi_float *y,ggi_float *c1,ggi_float *c2);
  int gcpSetYCCGamma(ggi_visual_t vis,
                ggi_float y,ggi_float c1,ggi_float c2);

  int gcpGetYCCGammaMap(ggi_visual_t vis,
                int s,int len,gcp_YCCcolor *gammamap);
  int gcpSetYCCGammaMap(ggi_visual_t vis,
                int s,int len,gcp_YCCcolor *gammamap);


Description
-----------

Some modes on some hardware can use a per-channel palette to lookup
the values before sending to the monitor.  Generally this is used for
gamma correction by filling the lookup table with a curve, hence the
name "gamma map", but it could be used for other things e.g. special
effects in games.  Truecolor modes with gamma maps are sometimes
referred to as "directcolor".


`gcpSet*GammaMap` and `gcpGet*GammaMap` set or get the gamma map, for
:p:`len` colors starting at :p:`s`.  In the event that there are more
map entries for some channels than others, values for the upper
indices of the map in the shallow channels are ignored on write, and
undefined on read.


Return value
------------

All functions returns 0 for success, otherwise an :man:`ggi-error(3)` code.



Color blending
~~~~~~~~~~~~~~

.. manpage:: 3 gcpBlendColor


Synopsis
--------

::

  #include <ggi/gcp.h>

  gcp_pixel gcpBlendColor(ggi_visual_t vis,
                          const gcp_pixel *pix1, const gcp_pixel *pix2, 
                          uint16_t alpha);


Description
-----------

`gcpBlendColor` blends :p:`pix2` over :p:`pix1` with the translucency :p:`alpha`,
with :p:`pix1` as the background, :p:`pix2` the forground. :p:`alpha` is a 16bit
translucency channel.


Return value
------------

`gcpBlendColor` returns the resulting :man:`gcp_pixel(3)` value.


Manipulate Luminance
~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpGetLuminance


Synopsis
--------

::

  #include <ggi/gcp.h>

  ggi_float gcpGetLuminance(ggi_visual_t vis, const gcp_pixel pix);


Description
-----------

`gcpGetLuminance` calculates the luminance of the :p:`pix` pixel.


Return value
------------

`gcpGetLuminance` returns the luminance of the pixel.


Manipulate Lighting
~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcpSetIntensity gcpGetIntensity


Synopsis
--------

::

  #include <ggi/gcp.h>

  gcp_pixel gcpSetIntensity(ggi_visual_t vis,
                const gcp_pixel *pix1, const gcp_pixel *light_color);
  gcp_pixel gcpGetIntensity(ggi_visual_t vis,
                const gcp_pixel *pix1, const gcp_pixel *pix2);


Description
-----------

`gcpSetIntensity` sets the intensity for a :man:`gcp_pixel(3)`.


`gcpGetIntensity` extracts the intensity of a :man:`gcp_pixel(3)`.


Return value
------------

`gcpSetIntensity` returns a `gcp_pixel` with the new light itensity.


`gcpGetIntensity` returns a `gcp_pixel`, that corresponds the :p:`light_color`
argument of `gcpSetIntensity`. The :p:`pix1` is the same 'basecolor'
passed to `gcpSetIntensity` and :p:`pix2` corresponds the return value of
`gcpSetIntensity`.