# cdEncodeColor

Definition: | include pGUI.e integer colour = cdEncodeColor(atom red, green, blue) -- or -- atom colour = cdEncodeColorAlpha(atom red, green, blue, alpha) -- or -- atom colour = cdEncodeAlpha(atom colour, integer alpha) -- or -- atom colour = rgb(atom red, green, blue, alpha=0) -- or -- atom colour = hsv_to_rgb(atom h, s, v, a=0) -- and -- integer {red,green,blue} = cdDecodeColor(atom colour) -- or -- integer {red,green,blue,alpha} = cdDecodeColorAlpha(atom colour) -- or -- integer alpha = cdDecodeAlpha(atom colour) -- or -- integer {red,green,blue,alpha} = to_rgb(atom colour)
Description: | Various utility routines to convert between colour components and their combined equivalent encodings. red, green, blue, alpha: Notionally integers 0..255 but fractions permitted (see comment). colour: an encoding in the format 0xAARRGGBB. h,s,v,a: fractions between 0 and 1 (hue, saturation, value, and alpha).
pwa/p2js: | Supported. Note that under pwa/p2js both cdDecodeColor() and cdDecodeColorAlpha() are simple aliases of to_rgb(), and therefore the first returns a quadlet rather than a triplet, unlike desktop/Phix. Obviously that could easily be rectified, but if/when genuinely needed and not before.
Comments: | Used in the CD library to define colors. Can be used without an active canvas. Technically, and of little practical concern, except perhaps when testing, the precise nature of any fraction ==>> 0..255 conversion is officially undefined, especially for values below 0 or above 255.49, and may differ between different operating systems, libc/msvcrt builds, and even CPU brands. For consistent results, should that be vitally important, explicitly round/truncate any such fractions yourself, and for fairly obvious reasons hsv_to_rgb() is unlikely to be perfectly consistent between 32 and 64 bit (pretty much no matter what you do). The cdEncodeColor() and cdEncodeColorAlpha() routines invoke the C functions of the same name, whereas the rgb() function performs the same task in pure Phix code. The latter is recommended (simply have/omit the fourth parameter as needed), and is more likely to behave consistently across different platforms. A very similar rgb() routine exists in both arwen and win32lib, note however those libraries encode colours as red+green*#100+blue*#10000, whereas pGUI uses red*#10000+green*#100+blue, a fact you should only ever need to know when debugging or for some reason are directly comparing the results or using hard-coded literals such as #FF0000 (==CD_RED in pGUI) vs #0000FF (==BrightRed in arwen), which you may encounter when porting existing code. The cdDecodeColor(), cdDecodeColorAlpha(), and to_rgb() routines reverse the process, again with the latter being pure Phix and usually recommended: Just code `integer {r,g,b} = to_rgb()`, or maybe `integer {r,g,b,{}} = to_rgb()` if you don’t need the alpha value, however if you find yourself having to explicitly chop off the returned a, then using cdDecodeColour() may in fact be the better choice. Unlike the encode functions, no inconsistencies have ever been spotted between any of the decode routines. cdEncodeAlpha returns the given color coded with the alpha information. ATTENTION: At the moment only the Cairo, GDI+, XRender and IMAGERGB drivers support alpha components in color coding. The internal representation of the component is inverted, because the default value must be 0 and opaque for backward compatibility, so you should use the cdDecodeAlpha function or the cdAlpha macro to retrieve the alpha component. 0 is transparent, 255 is opaque. cdDecodeAlpha returns the alpha component of a color in the CD library. Can be used without an active canvas. 0 is transparent, 255 is opaque. The following constants are defined for convenience.
Eg | CD (#000000 format) | IUP ("#000000" format) | Value/Aliases
--- | --- | --- | ---
| CD_BLACK | IUP_BLACK | #000000 (0)
| CD_BLUE | IUP_BLUE | #0000FF (255)
| CD_CYAN | IUP_CYAN | #00FFFF (65535)
| CD_DARK_BLUE | IUP_DARK_BLUE | #000080 (128) CD_NAVY, IUP_NAVY
| CD_DARK_CYAN | IUP_DARK_CYAN | #008080 (32896) CD_TEAL, IUP_TEAL
| CD_DARK_GREY | IUP_DARK_GREY | #808080 (8421504) CD_DARK_GRAY, IUP_DARK_GRAY
| CD_DARK_GREEN | IUP_DARK_GREEN | #008000 (32768)
| CD_DARK_MAGENTA | IUP_DARK_MAGENTA | #800080 (8388736)
| CD_DARK_RED | IUP_DARK_RED | #800000 (8388608)
| CD_DARK_YELLOW | IUP_DARK_YELLOW | #EBEB00 (15461120)
| CD_GREY | IUP_GREY | #C0C0C0 (12632256) CD_GRAY, IUP_GRAY, CD_SILVER, IUP_SILVER
| CD_GREEN | IUP_GREEN | #3CB44B (3978315)
| CD_INDIGO | IUP_INDIGO | #4B0082 (4915330)
| CD_LIGHT_GREY | IUP_LIGHT_GREY | #E4E4E4 (15000804) CD_LIGHT_GRAY, IUP_LIGHT_GRAY
| CD_LIGHT_GREEN | IUP_LIGHT_GREEN | #00FF00 (65280)
| CD_LIGHT_BLUE | IUP_LIGHT_BLUE | #4363D8 (4416472)
| CD_LIGHT_PARCHMENT | IUP_LIGHT_PARCHMENT | #FAF8EF (16447727)
| CD_MAGENTA | IUP_MAGENTA | #F032E6 (15741670)
| CD_ORANGE | IUP_ORANGE | #FF8C00 (16747520)
| CD_AMBER | IUP_AMBER | #FFBF00 (16760576)
| CD_OLIVE | IUP_OLIVE | #808000 (8421376)
| CD_PARCHMENT | IUP_PARCHMENT | #FFFFE0 (16777184)
| CD_PURPLE | IUP_PURPLE | #911EB4 (9510580)
| CD_RED | IUP_RED | #FF0000 (16711680)
| CD_VIOLET | IUP_VIOLET | #EE82EE (15631086)
| CD_WHITE | IUP_WHITE | #FFFFFF (16777215)
| CD_YELLOW | IUP_YELLOW | #FFFF00 (16776960)