# a32Colour

Definition: | a32Colour identifier -- or -- integer i = a32Colour(object x)
Description: | This serves to define the a32Colour type. You can also call it like an ordinary function to determine if an object is an a32Colour.
Comments: | The raw data of the bitmap is 24 bits per pixel, stored as #bb,#gg,#rr, as required by the operating system primitives (such as gdi32.dll/BitBlt). These are held by arwen32dib as a sequence of 3 integers, each in the range 0 to 255: `colour[1]` is Blue. `colour[2]` is Green. `colour[3]` is Red. Note that colours are often defined elsewhere (other graphics libraries) in the order RGB, but throughout arwen32dib they are BGR. Variables declared with the user defined type a32Colour can be used to store the above. When invoked as a function, returns 1 if x is an a32Colour otherwise returns 0. One routine in particular, getDibPixel(), can return 0 if the provided co-ordinates are outside the bitmap, and like a32Dib0 you can use the type a32Colour0 to store the results from getDibPixel, as long as you test for a zero before attempting to subscript it. Without said test it is better to store it in an a32Colour variable, as there is little difference to terminating with a typecheck, or with an attempt to subscript an atom, except that the typecheck makes it just that little bit more obvious what went wrong. The value for each of the 3 colours is technically an integer in the range of 0 (no intensity) to 255 (full intensity). However, manipulations may often produce values outside this range, or fractional values, and further since any final `poke()` performs an implicit `and_bits(x,#FF)`, the individual colours are in fact only verified to be atoms. To create a colour, simply create a {blue, green, red} sequence, or, if you are used to working with RGB-colours rather than BGR-colurs, you may prefer to use the dibColor(integer red, integer green, integer blue) function. The contents of arwen\axtra.ew\ColourTuples are also in the same BGR format as a32Colour, for the same reasons as arwen32dib, and can be retrieved using GetNamedColour(string name). Any performance overhead from type checking of parameters is likely to be neglible, compared to a per-pixel typecheck, for which this type is not recommended: after inital debugging use a plain sequence or object instead. For instance it makes perfect sense to validate the color parameter of `colorizeDib()` (as defined in a32dcolr.ew), but not really the private internal variables orig_color and new_color of that routine (once we know it works).
Example: |
    a32Colour color

    color = dibColor(255,   0,   0) -- full red, no green, no blue     => bright red
    color = dibColor(255, 255,   0) -- full red, full green, no blue   => bright yellow
    color = dibColor(  0,   0,   0) -- no red, no green, no blue       => black
    color = dibColor(255, 255, 255) -- full red, full green, full blue => bright white
    color = dibColor(  0, 127, 255) -- no red, half green, full blue   => some kind of cyan
See Also: | a32Dib dibColor