15.3.681  src/lib/x-kit/xclient/pkg/color/rgb.api

## rgb.api
#
# RGB color values as opaque triples
#
#     (red: Float, green: Float, blue: Float)
#
# This is our preferred color representation;
# all other color representations implement
# to_rgb() and from_rgb() conversion functions.

# Compiled by:
#     src/lib/x-kit/xclient/xclient-internals.sublib

# This api is implemented in:
#
#     src/lib/x-kit/xclient/pkg/color/rgb.pkg

api Rgb {

    # RGB colors 
    #
    # We represent an RGB color value by a
    # record of 64-bit floats holding
    # red, green, blue in that order.
    # (The compiler will optimize this to
    # a very efficient packed representation.)
    # 
    Rgb = { red:        Float,
            green:      Float,
            blue:       Float
          };

    # Predefine a few common colors for convenience:
    #
    black:   Rgb;
    white:   Rgb;
    red:     Rgb;
    green:   Rgb;
    blue:    Rgb;
    cyan:    Rgb;
    magenta: Rgb;
    yellow:  Rgb;

    # We primarily think of color components as
    # ranging from 0.0 -> 1.0 inclusive:
    #
    rgb_from_floats:  (Float, Float, Float)  ->  Rgb;
    rgb_to_floats:    Rgb  ->  (Float, Float, Float);

    # The X protocol level likes to think
    # of color components as ranging from
    # 0 -> 65355 inclusive, so we support
    # that for implementation of X protocol
    # packet encoding and decoding.  This format
    # is not otherwise particularly recommended:
    #
    rgb_from_unts:    (Unt, Unt, Unt)  ->  Rgb;
    rgb_to_unts:      Rgb  ->  (Unt, Unt, Unt);

    same_rgb:    (Rgb, Rgb) -> Bool;
        #
        # Note that this 'same' function does
        # 64-bit float comparisons, and consequently
        # is very sensitive to rounding errors: Things
        # you expect to compare equal may fail to do so.
        #
        # If that is an issue in your application, you
        # may wish to convert to Rgb8 form (thus discarding
        # all but the most significant 8 bits of each color
        # component) and then use rgb8::same().


    rgb_normalize:  Rgb -> Rgb;         # Ensure all color components are in 0.0 -> 1.0 inclusive.

    rgb_from_name:  String -> Rgb;              # Raises exception lib_base::NOT_FOUND if given string is not in table.
        #
        # Return a color from x11_color_name::x11_colors table.
};


## COPYRIGHT (c) 1994 by AT&T Bell Laboratories
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2012,
## released under Gnu Public Licence version 3.