typedef struct Colour Color;
typedef struct Colour Colour;
struct Colour {
byte alpha; /* 0=opaque, 255=transparent */
byte red; /* intensity of red light, 0=none, 255=bright */
byte green; /* intensity of green light, 0=none, 255=bright */
byte blue; /* intensity of blue light, 0=none, 255=bright */
};
Colour rgb(int red, int green, int blue); /* create Colour */ Colour argb(int alpha, int r, int g, int b); /* with alpha */ Colour new_color(int r, int g, int b); /* create Colour */ Colour new_colour(int r, int g, int b); /* create Colour */ int rgbs_equal(Colour a, Colour b); /* compare Colours */ int colors_equal(Colour a, Colour b); /* compare Colours */ int colours_equal(Colour a, Colour b); /* compare Colours */
#define CLEAR argb(0xFF,0xFF,0xFF,0xFF) #define BLACK rgb(0x00,0x00,0x00) #define WHITE rgb(0xFF,0xFF,0xFF) #define BLUE rgb(0x00,0x00,0xFF) #define YELLOW rgb(0xFF,0xFF,0x00) #define GREEN rgb(0x00,0xFF,0x00) #define MAGENTA rgb(0xFF,0x00,0xFF) #define RED rgb(0xFF,0x00,0x00) #define CYAN rgb(0x00,0xFF,0xFF) #define GREY rgb(0x80,0x80,0x80) #define GRAY rgb(0x80,0x80,0x80) #define LIGHT_GREY rgb(0xC0,0xC0,0xC0) #define LIGHT_GRAY rgb(0xC0,0xC0,0xC0) #define DARK_GREY rgb(0x40,0x40,0x40) #define DARK_GRAY rgb(0x40,0x40,0x40) #define DARK_BLUE rgb(0x00,0x00,0x80) #define DARK_GREEN rgb(0x00,0x80,0x00) #define DARK_RED rgb(0x80,0x00,0x00) #define LIGHT_BLUE rgb(0x80,0xC0,0xFF) #define LIGHT_GREEN rgb(0x80,0xFF,0x80) #define LIGHT_RED rgb(0xFF,0xC0,0xFF) #define PINK rgb(0xFF,0xAF,0xAF) #define BROWN rgb(0x60,0x30,0x00) #define ORANGE rgb(0xFF,0x80,0x00) #define PURPLE rgb(0xC0,0x00,0xFF) #define LIME rgb(0x80,0xFF,0x00)
A Colour value is a structure used to represent a colour, using four integer components: three to represent the intensity of red, green and blue light, and one to represent the transparency of the colour against a background, otherwise known as the alpha channel value. The names Colour and Color are interchangeable.
The rgb function constructs a fully-opaque Colour value, given the required intensity of red, green and blue light. The values of red, green and blue can range from zero (no intensity) to 255 (maximum intensity). The rgb function is implemented as a macro.
Pre-defined colours are available, such as BLACK, WHITE, GREY, BLUE, RED, GREEN, etc. These are defined using the C pre-processor as calls to the rgb function, and as such, cannot be used outside of function blocks (for instance, you cannot use the pre-defined colours in an initialising structure). The bit-patterns these colours become when inside a bitmap are not generally defined; bitmaps are platform-dependent data structures, and should be treated as output devices only. (Note that both American and British English spellings are supported, both for colour-names and functions which employ the word 'colour' or 'color'. Thus GREY and GRAY are quite legal, and interchangeable.)
The alpha byte of a Colour value is used to represent a transparency value. If this byte is equal to 255, that Colour is fully transparent. If the alpha value is zero, the Colour is fully opaque. In theory, an alpha value between zero and 255 can be used to perform 'colour blending', however currently only fully transparent and fully opaque rgb values are supported. The special constant CLEAR can be used to represent fully transparent Colour values in images, and so forth.
The argb function constructs a Colour value which has an explicit alpha value between 0 and 255 inclusive.
The new_color and new_colour functions are macros which call rgb to create fully-opaque colours.
Colours can be be compared using rgbs_equal. The macro functions colors_equal and colours_equal are synonyms for this comparison function.
Important note: Colours, when passed as function parameters, are generally passed by value on the stack. This means that modifying a colour within a function will not change its value outside that function. Colours can thus be treated as numeric objects, like integers. (Were they to be passed by pointer, this would not be the case.) This differs somewhat from the way Java implicitly passes all objects by pointer, except for numbers.