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.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 follows.
  32  */
  33 #ifdef GP_PIXEL_RGB555
  34
  35 ...
  36
  37 #endif /* GP_PIXEL_RGB555 */
  38
  39 -------------------------------------------------------------------------------
  40
  41 Pixels are described by a pixel type, which is enumeration type. The enum is
  42 defined in the generated 'GP_Pixel.gen.h' header and must contain at least the
  43 members listed above.
  44
  45 The same names as are the enum values are also defined (to themselves) as
  46 macros so that it's possible to use them with 'ifdef'.
  47
  48 [source,c]
  49 -------------------------------------------------------------------------------
  50 #include <GP.h>
  51 /* or */
  52 #include <core/GP_Pixel.h>
  53
  54 typedef struct {
  55         char name[8];    /* Channel name */
  56         uint8_t offset;  /* Offset in bits */
  57         uint8_t size;    /* Bit-size */
  58 } GP_PixelTypeChannel;
  59
  60 typedef enum GP_PixelFlags {
  61         GP_PIXEL_HAS_ALPHA = 0x01,
  62         GP_PIXEL_IS_RGB = 0x02,
  63         GP_PIXEL_IS_PALETTE = 0x04,
  64         GP_PIXEL_IS_CMYK = 0x08,
  65         GP_PIXEL_IS_GRAYSCALE = 0x10,
  66 } GP_PixelFlags;
  67
  68 typedef struct {
  69         GP_PixelType type;        /* Number of the type */
  70         const char name[16];      /* Name */
  71         uint8_t size;             /* Size in bits */
  72         GP_BIT_ENDIAN bit_endian; /* Order of pixels in a byte */
  73         uint8_t numchannels;      /* Number of channels */
  74         GP_PixelFlags flags;
  75         /* String describing the bit-representaton (as in "RRRRRGGGGGGBBBBB")*/
  76         const char bitmap[GP_PIXEL_BITS + 1];
  77         /* Individual channels */
  78         const GP_PixelTypeChannel channels[GP_PIXELTYPE_MAX_CHANNELS];
  79 } GP_PixelTypeDescription;
  80
  81 extern const GP_PixelTypeDescription const GP_PixelTypes[];
  82
  83 const GP_PixelTypeDescription *GP_PixelTypeDesc(GP_PixelType type);
  84
  85 const char *GP_PixelTypeName(GP_PixelType type);
  86
  87 uint32_t GP_PixelSize(GP_PixelType type);
  88
  89 int GP_PixelHasFlags(GP_PixelType pixel_type, GP_PixelFlags flags);
  90 -------------------------------------------------------------------------------
  91
  92 Each pixel type has accompanying record in global array describing pixel types.
  93
  94 You should not use this array directly, use the 'GP_PixelTypeDesc()' function
  95 to query the pixel type description.
  96
  97 The 'GP_PixelTypeName()' function returns static string with pixel type name.
  98
  99 The 'GP_PixelSize()' returns pixel size in bits.
 100
 101 The 'GP_PixelHasFlags()' function returns true if particular pixel type
 102 contains the bitmask of pixel flags.
 103
 104 [source,c]
 105 -------------------------------------------------------------------------------
 106 #include <GP.h>
 107 /* or */
 108 #include <core/GP_Pixel.h>
 109
 110 void GP_PixelPrint(GP_Pixel pixel, GP_PixelType type);
 111
 112 void GP_PixelSNPrint(char *buf, size_t len, GP_Pixel pixel, GP_PixelType type);
 113 -------------------------------------------------------------------------------
 114
 115 Pretty print pixel value given the pixel type.
 116
 117 .Sample output from the functions
 118 -------------------------------------------------------------------------------
 119 RGB888 0xffffff R=255 G=255 B=255
 120 -------------------------------------------------------------------------------
 121
 122 [source,c]
 123 -------------------------------------------------------------------------------
 124 #include <GP.h>
 125 /* or */
 126 #include <core/GP_Pixel.h>
 127
 128 GP_PixelType GP_PixelRGBMatch(GP_Pixel rmask, GP_Pixel gmask,
 129                               GP_Pixel bmask, GP_Pixel amask,
 130                               uint8_t bits_per_pixel);
 131
 132 GP_PixelType GP_PixelRGBLookup(uint32_t rsize, uint32_t roff,
 133                                uint32_t gsize, uint32_t goff,
 134                                uint32_t bsize, uint32_t boff,
 135                                uint32_t asize, uint32_t aoff,
 136                                uint8_t bits_per_pixel);
 137 -------------------------------------------------------------------------------
 138
 139 Returns pixel type given either RGB masks or RGB sizes and offsets. If no
 140 matching pixel was found 'GP_PIXEL_UNKNOWN' is returned.