doc/pixels.txt

   1 Pixel Description
   2 -----------------
   3
   4 This pages describes library core functions for handling pixels.
   5
   6 Pixel Type
   7 ~~~~~~~~~~
   8
   9 Pixels are described by a pixel type, which is enumeration type. The enum is
  10 defined at the generated 'GP_Pixel.gen.h' header and must contain at least
  11 following members:
  12
  13 [source,c]
  14 -------------------------------------------------------------------------------
  15 #include <GP.h>
  16 /* or */
  17 #include <core/GP_Pixel.h>
  18
  19 typedef enum GP_PixelType {
  20         GP_PIXEL_UNKNOWN,
  21         GP_PIXEL_xRGB8888,
  22         GP_PIXEL_RGBA8888,
  23         GP_PIXEL_RGB888,
  24         GP_PIXEL_BGR888,
  25         GP_PIXEL_G1,
  26         GP_PIXEL_G2,
  27         GP_PIXEL_G4,
  28         GP_PIXEL_G8,
  29         GP_PIXEL_MAX,
  30 } GP_PixelType;
  31
  32 -------------------------------------------------------------------------------
  33
  34 Each pixel type has accompanying record in global array of pixel types
  35 declared as follows:
  36
  37 [source,c]
  38 -------------------------------------------------------------------------------
  39 #include <GP.h>
  40 /* or */
  41 #include <core/GP_Pixel.h>
  42
  43 typedef struct {
  44         char name[8];    /* Channel name */
  45         uint8_t offset;  /* Offset in bits */
  46         uint8_t size;    /* Bit-size */
  47 } GP_PixelTypeChannel;
  48
  49 typedef struct {
  50         GP_PixelType type;        /* Number of the type */
  51         const char name[16];      /* Name */
  52         uint8_t size;             /* Size in bits */
  53         GP_BIT_ENDIAN bit_endian; /* Order of pixels in a byte */
  54         uint8_t numchannels;      /* Number of channels */
  55         /* String describing the bit-representaton (as in "RRRRRGGGGGGBBBBB")*/
  56         const char bitmap[GP_PIXEL_BITS + 1];
  57         /* Individual channels */
  58         const GP_PixelTypeChannel channels[GP_PIXELTYPE_MAX_CHANNELS];
  59 } GP_PixelTypeDescription;
  60
  61 extern const GP_PixelTypeDescription const GP_PixelTypes[];
  62
  63 const char *GP_PixelTypeName(GP_PixelType type);
  64
  65 uint32_t GP_PixelSize(GP_PixelType type);
  66 -------------------------------------------------------------------------------
  67
  68 There are also pixel matching functions that returns pixel type given RGB
  69 channel masks or sizes and offsets:
  70
  71 [source,c]
  72 -------------------------------------------------------------------------------
  73 #include <GP.h>
  74 /* or */
  75 #include <core/GP_Pixel.h>
  76
  77 GP_PixelType GP_PixelRGBMatch(GP_Pixel rmask, GP_Pixel gmask,
  78                               GP_Pixel bmask, GP_Pixel amask,
  79                               uint8_t bits_per_pixel);
  80
  81 GP_PixelType GP_PixelRGBLookup(uint32_t rsize, uint32_t roff,
  82                                uint32_t gsize, uint32_t goff,
  83                                uint32_t bsize, uint32_t boff,
  84                                uint32_t asize, uint32_t aoff,
  85                                uint8_t bits_per_pixel);
  86 -------------------------------------------------------------------------------
  87