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 <gfxprim.h>
  12 /* or */
  13 #include <core/GP_Pixel.gen.h>
  14
  15 typedef enum gp_pixel_type {
  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_pixel_type;
  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 <gfxprim.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_pixel_channel;
  60
  61 typedef enum gp_pixel_flags {
  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_pixel_flags;
  68
  69 typedef struct {
  70         gp_pixel_type 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_pixel_flags flags;
  76         /* String describing the bit-representaton (as in "RRRRRGGGGGGBBBBB")*/
  77         const char bitmap[GP_PIXEL_BITS + 1];
  78         /* Individual channels */
  79         const gp_pixel_channel channels[GP_PIXELTYPE_MAX_CHANNELS];
  80 } gp_pixel_type_desc;
  81
  82 extern const gp_pixel_type_desc const gp_pixel_types[];
  83
  84 const gp_pixel_type_desc *gp_pixel_desc(gp_pixel_type type);
  85
  86 const char *gp_pixel_typeName(gp_pixel_type type);
  87
  88 uint32_t gp_pixel_size(gp_pixel_type type);
  89
  90 unsigned int gp_pixel_channel_count(gp_pixel_type type);
  91
  92 uint8_t gp_pixel_channel_bits(gp_pixel_type type, uint8_t channel);
  93
  94 const char *gp_pixel_channel_name(gp_pixel_type type, uint8_t channel);
  95
  96 int gp_pixel_has_flags(gp_pixel_type pixel_type, gp_pixel_flags 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_pixel_desc()' function to
 102 query the pixel type description or one of the gp_pixel_*() functions below.
 103
 104 The 'gp_pixel_type_name()' function returns static string with pixel type name.
 105
 106 The 'gp_pixel_size()' returns pixel size in bits.
 107
 108 The 'gp_pixel_channel_count()' returns number of pixel channels.
 109
 110 The 'gp_pixel_channel_bits()' returns number of bits for respective channel.
 111
 112 The 'gp_pixel_channel_name()' returns channel name.
 113
 114 The 'gp_pixel_has_flags()' function returns true if particular pixel type
 115 contains the bitmask of pixel flags.
 116
 117 [source,c]
 118 -------------------------------------------------------------------------------
 119 #include <gfxprim.h>
 120 /* or */
 121 #include <core/GP_Pixel.h>
 122
 123 void gp_pixel_print(gp_pixel pixel, gp_pixel_type type);
 124
 125 void gp_pixel_snprint(char *buf, size_t len, gp_pixel pixel, gp_pixel_type 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 <gfxprim.h>
 138 /* or */
 139 #include <core/GP_Pixel.h>
 140
 141 gp_pixel_type gp_pixel_rgb_match(gp_pixel rmask, gp_pixel gmask,
 142                                  gp_pixel bmask, gp_pixel amask,
 143                                  uint8_t bits_per_pixel);
 144
 145 gp_pixel_type gp_pixel_rgb_lookup(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.