Pixel Description
-----------------

This pages describes library core functions for handling pixel types.

Pixel Type
~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_pixel.gen.h>

typedef enum gp_pixel_type {
	GP_PIXEL_UNKNOWN,
	GP_PIXEL_xRGB8888,
	GP_PIXEL_RGBA8888,
	GP_PIXEL_RGB888,
	GP_PIXEL_BGR888,
	GP_PIXE_CMYK8888,
	/* optional RGB pixel types (can be disabled in config) */
	GP_PIXEL_RGB565,
	GP_PIXEL_RGB555,
	GP_PIXEL_RGB332,
	...
	GP_PIXEL_G1,
	GP_PIXEL_G2,
	GP_PIXEL_G4,
	GP_PIXEL_G8,
	/* optional grayscale pixel types (can be disabled in config) */
	GP_PIXEL_GA88,
	GP_PIXEL_G16,
	...
	GP_PIXEL_MAX,
} gp_pixel_type;

/*
 * The same values are also defined as macros so it's possible to
 * use them with ifdef as:
 * #ifdef GP_PIXEL_RGB555
 * ...
 * #endif /* GP_PIXEL_RGB555 */
 */
#define GP_PIXEL_UNKNOWN GP_PIXEL_UNKNOWN
#define GP_PIXEL_xRGB8888 GP_PIXEL_xRGB8888
...

-------------------------------------------------------------------------------

Pixels are described by a pixel type, which is an enumeration type.

The enum is defined in the 'gp_pixel.gen.h' header link:gen.html[generated]
from a configuration file.

The header and must contain at least the members listed above.

[source,c]
-------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_pixel.h>

typedef struct {
	char name[8];    /* Channel name */
	uint8_t offset;  /* Offset in bits */
	uint8_t size;    /* Bit-size */
} gp_pixel_channel;

typedef enum gp_pixel_flags {
	GP_PIXEL_HAS_ALPHA = 0x01,
	GP_PIXEL_IS_RGB = 0x02,
	GP_PIXEL_IS_PALETTE = 0x04,
	GP_PIXEL_IS_CMYK = 0x08,
	GP_PIXEL_IS_GRAYSCALE = 0x10,
} gp_pixel_flags;

typedef struct {
	gp_pixel_type type;        /* Number of the type */
	const char name[16];      /* Name */
	uint8_t size;	          /* Size in bits */
	uint8_t numchannels;      /* Number of channels */
	gp_pixel_flags flags;
	/* String describing the bit-representaton (as in "RRRRRGGGGGGBBBBB")*/
	const char bitmap[GP_PIXEL_BITS + 1];
	/* Individual channels */
	const gp_pixel_channel channels[GP_PIXELTYPE_MAX_CHANNELS];
} gp_pixel_type_desc;

extern const gp_pixel_type_desc const gp_pixel_types[];

const gp_pixel_type_desc *gp_pixel_desc(gp_pixel_type type);

const char *gp_pixel_typeName(gp_pixel_type type);

uint32_t gp_pixel_size(gp_pixel_type type);

unsigned int gp_pixel_channel_count(gp_pixel_type type);

uint8_t gp_pixel_channel_bits(gp_pixel_type type, uint8_t channel);

const char *gp_pixel_channel_name(gp_pixel_type type, uint8_t channel);

int gp_pixel_has_flags(gp_pixel_type pixel_type, gp_pixel_flags flags);
-------------------------------------------------------------------------------

Each pixel type has accompanying record in global array describing pixel types.

You should not use this array directly, use the 'gp_pixel_desc()' function to
query the pixel type description or one of the gp_pixel_*() functions below.

The 'gp_pixel_type_name()' function returns static string with pixel type name.

The 'gp_pixel_size()' returns pixel size in bits.

The 'gp_pixel_channel_count()' returns number of pixel channels.

The 'gp_pixel_channel_bits()' returns number of bits for respective channel.

The 'gp_pixel_channel_name()' returns channel name.

The 'gp_pixel_has_flags()' function returns true if particular pixel type
contains the bitmask of pixel flags.

[source,c]
-------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_pixel.h>

void gp_pixel_print(gp_pixel pixel, gp_pixel_type type);

void gp_pixel_snprint(char *buf, size_t len, gp_pixel pixel, gp_pixel_type type);
-------------------------------------------------------------------------------

Pretty print pixel value given the pixel type.

.Sample output from the functions
-------------------------------------------------------------------------------
RGB888 0xffffff R=255 G=255 B=255
-------------------------------------------------------------------------------

[source,c]
-------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_pixel.h>

gp_pixel_type gp_pixel_rgb_match(gp_pixel rmask, gp_pixel gmask,
                                 gp_pixel bmask, gp_pixel amask,
			         uint8_t bits_per_pixel);

gp_pixel_type gp_pixel_rgb_lookup(uint32_t rsize, uint32_t roff,
                                  uint32_t gsize, uint32_t goff,
			          uint32_t bsize, uint32_t boff,
			          uint32_t asize, uint32_t aoff,
			          uint8_t bits_per_pixel);
-------------------------------------------------------------------------------

Returns pixel type given either RGB masks or RGB sizes and offsets. If no
matching pixel was found 'GP_PIXEL_UNKNOWN' is returned.
