TkGS Specification - Drawing parameters: Colors

Introduction

Effective color management is one of the major goals of TkGS. The current implementation relies on the Xlib model (or its emulation layer). In order to achieve device independence, we need to provide a more generic means of specifying colors.

Using XLib, colors must be allocated and freed using various functions such as XAllocColor. TkGS follows the same model in the sense that colors must be allocated and freed. Colors are made available under the form of an opaque token named TkGS_Color. The way these tokens are obtained is device-independent, but they can internally hold device-dependent information.

The TkGS_Color model tries to keep all existing feature available in Tk. For example, colors can be specified as named colors such as "orange" (usually defined in the file rgb.txt) or as variable-sized RGB triplets such as "#FFA500". TkGS could also add other specification methods such as HLS or CMYK, allowing such names as "rgb(1,0,0)" or "cmyk(0,1,1,0)" (both representing red).

While TkGS_Colors are device-independent, their internal representation may change depending on which device they are used with. This model is close to the way Tcl_Objects are designed and used. For example, in Tcl, "10" can be seen as a string, an integer or a double value. Likewise, a TkGS_Color specified by its RGB values could hold any device-independent value internally, be it an XColor or a Windows COLORREF or Pen Object. As the same color may be used on distinct devices, its internal representation may change as well, however its external representation remains the same, thus guaranteeing device-independence. Internally, TkGS_Colors are implemented using TkGS_Objs. As seen from the outside, TkGS_Colors are opaque tokens.

Structures


TkGS_Color
Description
This is a cross-platform structure intended to replace the current X-specific XColor structure.
Structure
TkGS_Color is an opaque token that holds system-independent color information. Its internals could for example contain an XColor on X, or on Windows hold a Pen Object created from the specified color.
TkGS_Color's internals are defined by the TkGS_Color_ structure (notice the trailing underscore).

Functions


TkGS_GetRGBColor
Description
Allocate or retrive a TkGS_Color given its red, green and blue (RGB) values. These values are represented as unsigned 16-bit integers, although most systems only use 8-bit values.
Status
Specification complete. Current implementation always allocate a new color. We may later add color caching.
Declaration
TkGS_Color TkGS_GetRGBColor(
    unsigned short red;
    unsigned short green;
    unsigned short blue;
);
Arguments
red, green, blue: the values of the 3 primary colors.
Returned value
A newly allocated TkGS_Color, or an existing one if a matching color is found.
Side effects
A new object may be allocated.

TkGS_GetColorByName
Description
Allocate or retrieve a TkGS_Color given its textual description. This can be any form currently allowed by Tk: a registered color name, or an RGB triplet such as #RRGGBB. This can also be a functional specification such as rgb(1,0,0) or cmyk(0,1,1,0) (each number being a real between 0 and 1).
Status
Specification complete. Not yet implemented.
Declaration
TkGS_Color TkGS_GetColorByName(
    Tcl_Interp *interp;
    char       *name;
);
Arguments
interp: Tcl interpreter used for error reporting.
name: textual description of desired color.
Returned value
A newly allocated TkGS_Color (or an existing one if a matching color is found), or NULL if the provided name is invalid. In the latter case, the interp's result is set to an error message.
Side effects
A new object may be allocated.

TkGS_GetColorRGBValues
Description
Retrieve RGB values from a given TkGS_Color.
Status
Specification complete. Not yet implemented.
Declaration
void TkGS_GetColorRGBValues(
    TkGS_Color     color;
    unsigned short *redPtr;
    unsigned short *greenPtr;
    unsigned short *bluePtr;
);
Arguments
color: TkGS_Color from which to retrieve information.
redPtr, greenPtr, bluePtr: pointers used to retrieve RGB values.
Returned value
Through the specified pointers.
Side effects
Pointed values are modified.

TkGS_GetColorName
Description
Retrieve RGB values from a given TkGS_Color.
Status
Specification complete. Not yet implemented.
Declaration
const char* TkGS_GetColorName(
    TkGS_Color color;
);
Arguments
color: TkGS_Color from which to retrieve information.
Returned value
If color is a named color, its name, else an RGB triplet string. The value is only guraranteed to persist until the next call to TkGS_GetColorName.
Side effects
None.

TkGS_FreeColor
Description
Free a TkGS_Color previously allocated by any of the above functions.
Status
Complete.
Declaration
void TkGS_FreeColor(
    TkGS_Color color;
);
Arguments
color: TkGS_Color to free.
Returned value
None.
Side effects
The given object is freed.

TODO