LibGGIGCP types and structures
==============================


LibGGIGCP color description
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 gcp_pixel gcp_RGBAcolor gcp_YUVcolor gcp_CMYKcolor gcp_HSVcolor gcp_YCCcolor


Synopsis
--------

::

  #include <ggi/gcp.h>

  typedef ggi_pixel gcp_pixel;

  typedef ggi_color gcp_RGBAcolor;
  typedef struct { ggi_float y,u,v; } gcp_YUVcolor;
  typedef struct { uint16_t c,m,y,k; } gcp_CMYKcolor;
  typedef struct { ggi_float h,s,v; } gcp_HSVcolor;
  typedef struct { uint16_t y,c1,c2; } gcp_YCCcolor;


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

Colors are described generally through display-independent
`gcp_RGBAcolor`, `gcp_YUVcolor`, `gcp_CMYKcolor`, `gcp_HSVcolor`
and `gcp_YCCcolor` structures for the RGBA, YUV, CMYK, HSV and
YCC color spaces.

`gcp_pixel`\ s are display-dependent pixel values. They are used by
all GCP operations for efficiency.  Use `gcpMap*Color(3)` to
convert gcp_*colors to gcp_pixels.


Structure members
-----------------

`gcp_RGBAcolor` represents the rgba colorspace and is
the same as :man:`ggi_color(3)`.

`gcp_YUVcolor` represents the YUV colorspace. It consists
of `y`, `u` and `v`. They correspond to the
luminance and chrominance components.

`gcp_CMYKcolor` represents the CMYK colorspace. It consists
of `c`, `m`, `y` and `k`. They correspond to the
cyan, magenta, yellow and black channels.

`gcp_HSVcolor` represents the HSV colorspace. It consists
of `h`, `s` and `v`. They correspond to the
hue, saturation and velocity.


`gcp_YCCcolor`, better known as Kodak PhotoCD. It consists
of `y`, `c1` and `c2`.

`gcp_pixel`\ s format depends on the actual display and mode. For those
who want to operate directly on pixel values, this format is described
in the :man:`ggi_pixelformat(3)` structure.


Pixel Arrays
------------

Although individual pixels are kept into 32 bits `gcp_pixel`, arrays
of pixels, as used in `ggi[Get|Put]*` functions, `gcpPack*Colors` and
`gcpUnpack*Pixels`, are stored in the display specific format, thus
packed according to the actual pixel size.  This size is given by the
`GT_SIZE` macro for `graphtype` or the `size` field of the
`ggi_pixelformat` structure.


The buffers provided to these functions must be big enough to store or
read enough pixels. Although it is safe to use 32 bits per pixel, the
optimum size (in bits) can be calculated by multiplying the number of
pixel by their size. Don't forget to round up to a multiple of 8 to
get the number of bytes.


If you want to access such buffers directly, do *not* use pointer
arithmetics with `gcp_pixel`\ s.


See Also
--------

:man:`gcpMapRGBAColor(3)`, :man:`gcpMapYUVColor(3)`,
:man:`gcpMapHSVColor(3)`, :man:`gcpMapCMYKColor(3)`,
:man:`gcpMapYCCColor(3)`,
:man:`ggi_pixelformat(3)`