doc/pixels.txt

   1 Pixel Description
   2 -----------------
   3
   4 This pages describes library core functions for handling pixel types.
   5
   6 Pixel Type
   7 ~~~~~~~~~~
   8
   9 [source,c]
  10 -------------------------------------------------------------------------------
  11 #include <GP.h>
  12 /* or */
  13 #include <core/GP_Pixel.gen.h>
  14
  15 typedef enum GP_PixelType {
  16         GP_PIXEL_UNKNOWN,
  17         GP_PIXEL_xRGB8888,
  18         GP_PIXEL_RGBA8888,
  19         GP_PIXEL_RGB888,
  20         GP_PIXEL_BGR888,
  21         GP_PIXEL_G1,
  22         GP_PIXEL_G2,
  23         GP_PIXEL_G4,
  24         GP_PIXEL_G8,
  25         ...
  26         GP_PIXEL_MAX,
  27 } GP_PixelType;
  28
  29 /*
  30  * The same values are also defined as macros so it's possible to
  31  * use them with ifdef as:
  32  * #ifdef GP_PIXEL_RGB555
  33  * ...
  34  * #endif /* GP_PIXEL_RGB555 */
  35  */
  36 #define GP_PIXEL_UNKNOWN GP_PIXEL_UNKNOWN
  37 #define GP_PIXEL_xRGB8888 GP_PIXEL_xRGB8888
  38 ...
  39
  40 -------------------------------------------------------------------------------
  41
  42 Pixels are described by a pixel type, which is an enumeration type.
  43
  44 The enum is defined in the 'GP_Pixel.gen.h' header link:gen.html[generated]
  45 from a configuration file.
  46
  47 The header and must contain at least the members listed above.
  48
  49 [source,c]
  50 -------------------------------------------------------------------------------
  51 #include <GP.h>
  52 /* or */
  53 #include <core/GP_Pixel.h>
  54
  55 typedef struct {
  56         char name[8];    /* Channel name */
  57         uint8_t offset;  /* Offset in bits */
  58         uint8_t size;    /* Bit-size */
  59 } GP_PixelTypeChannel;
  60
  61 typedef enum GP_PixelFlags {
  62         GP_PIXEL_HAS_ALPHA = 0x01,
  63         GP_PIXEL_IS_RGB = 0x02,
  64         GP_PIXEL_IS_PALETTE = 0x04,
  65         GP_PIXEL_IS_CMYK = 0x08,
  66         GP_PIXEL_IS_GRAYSCALE = 0x10,
  67 } GP_PixelFlags;
  68
  69 typedef struct {
  70         GP_PixelType type;        /* Number of the type */
  71         const char name[16];      /* Name */
  72         uint8_t size;             /* Size in bits */
  73         GP_BIT_ENDIAN bit_endian; /* Order of pixels in a byte */
  74         uint8_t numchannels;      /* Number of channels */
  75         GP_PixelFlags flags;
  76         /* String describing the bit-representaton (as in "RRRRRGGGGGGBBBBB")*/
  77         const char bitmap[GP_PIXEL_BITS + 1];
  78         /* Individual channels */
  79         const GP_PixelTypeChannel channels[GP_PIXELTYPE_MAX_CHANNELS];
  80 } GP_PixelTypeDescription;
  81
  82 extern const GP_PixelTypeDescription const GP_PixelTypes[];
  83
  84 const GP_PixelTypeDescription *GP_PixelTypeDesc(GP_PixelType type);
  85
  86 const char *GP_PixelTypeName(GP_PixelType type);
  87
  88 uint32_t GP_PixelSize(GP_PixelType type);
  89
  90 unsigned int GP_PixelChannelCount(GP_PixelType type);
  91
  92 uint8_t GP_PixelChannelBits(GP_PixelType type, uint8_t channel);
  93
  94 const char *GP_PixelChannelName(GP_PixelType type, uint8_t channel);
  95
  96 int GP_PixelHasFlags(GP_PixelType pixel_type, GP_PixelFlags flags);
  97 -------------------------------------------------------------------------------
  98
  99 Each pixel type has accompanying record in global array describing pixel types.
 100
 101 You should not use this array directly, use the 'GP_PixelTypeDesc()' function
 102 to query the pixel type description.
 103
 104 The 'GP_PixelTypeName()' function returns static string with pixel type name.
 105
 106 The 'GP_PixelSize()' returns pixel size in bits.
 107
 108 The 'GP_PixelChannelCount()' returns number of pixel channels.
 109
 110 The 'GP_PixelChannelBits()' returns number of bits for respective channel.
 111
 112 The 'GP_PixelChannelName()' returns channel name.
 113
 114 The 'GP_PixelHasFlags()' function returns true if particular pixel type
 115 contains the bitmask of pixel flags.
 116
 117 [source,c]
 118 -------------------------------------------------------------------------------
 119 #include <GP.h>
 120 /* or */
 121 #include <core/GP_Pixel.h>
 122
 123 void GP_PixelPrint(GP_Pixel pixel, GP_PixelType type);
 124
 125 void GP_PixelSNPrint(char *buf, size_t len, GP_Pixel pixel, GP_PixelType type);
 126 -------------------------------------------------------------------------------
 127
 128 Pretty print pixel value given the pixel type.
 129
 130 .Sample output from the functions
 131 -------------------------------------------------------------------------------
 132 RGB888 0xffffff R=255 G=255 B=255
 133 -------------------------------------------------------------------------------
 134
 135 [source,c]
 136 -------------------------------------------------------------------------------
 137 #include <GP.h>
 138 /* or */
 139 #include <core/GP_Pixel.h>
 140
 141 GP_PixelType GP_PixelRGBMatch(GP_Pixel rmask, GP_Pixel gmask,
 142                               GP_Pixel bmask, GP_Pixel amask,
 143                               uint8_t bits_per_pixel);
 144
 145 GP_PixelType GP_PixelRGBLookup(uint32_t rsize, uint32_t roff,
 146                                uint32_t gsize, uint32_t goff,
 147                                uint32_t bsize, uint32_t boff,
 148                                uint32_t asize, uint32_t aoff,
 149                                uint8_t bits_per_pixel);
 150 -------------------------------------------------------------------------------
 151
 152 Returns pixel type given either RGB masks or RGB sizes and offsets. If no
 153 matching pixel was found 'GP_PIXEL_UNKNOWN' is returned.