graphics.c

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//     
//    __                                ______
//   / /_______________  ____  ___     / ____/
//  / __/ ___/ ___/ __ \/ __ \/ _ \   /___ )  
// / /_(__  ) /__/ /_/ / /_/ /  __/  ____/ /  
// \__/____/\___/\____/ .___/\___/  /_____/   
//                   /_/                      
//     
/// \file graphics.c
/// Definitions of graphics parameter functions.
/// \example graphics01.c
/// \example graphics02.c
/// \example graphics03.c
/// \example graphics04.c
/// \example graphics05.c
/// \example graphics06.c
/// \example graphics07.c
/// \example graphics08.c
/// \example graphics09.c
/// \example graphics10.c
////////////////////////////////////////////////////////////////////////////////


#include "../include/tscope5/graphics.h"
#include "../include/tscope5/graphics_internal.h"
#include "../include/tscope5/system_internal.h"
#include "../include/tscope5/textio_internal.h"

#include <allegro5/allegro_color.h>


////////////////////////////////////////////////////////////////////////////////
/// @name Coordinate functions
/// There are two coordinate systems and two coordinate scales 
/// available in Tscope5. 
///
/// - There is a Display coordinate system, 
///   with the origin (0,0) in the upper left corner of the display, 
///   with increasing coordinate values to the right of and below the origin. 
/// - There is also a Cartesian system, 
///   with the origin (0,0) in the center of the display, 
///   increasing coordinate values to the right and above the origin
///   and decreasing (negative) values to the left and below the origin.
/// - Default is the Cartesian system.
///
/// - There is an absolute coordinate scale where coordinates are 
///   interpreted as pixel values.
/// - There is a relative coordinate scale where coordinates are 
///   interpreted relative to the display size.
/// - The default is the absolute system.
///
/// Some helper functions that (can help you) convert between 
/// the coordinate scales/systems are available, 
/// but most of the time you will only need to choose the coordinate
/// system/scale and Tscop5 will automatically do the transormations 
/// that are necessary.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Set the coordinate system.
///
/// \param coordinate_system Coordinate system to be used. 
/// Can be TS5_CARTESIAN_COORDINATES and TS5_DISPLAY_COORDINATES. 
/// Default is TS5_CARTESIAN_COORDINATES.
///
/// \return The previous coordinate system.
///
/// The TS5_DISPLAY_COORDINATES system 
/// has the origin (0,0) in the upper left corner of the display
/// and increasing coordinate values to the left of and below the origin.
///
/// The TS5_CARTESIAN_COORDINATES system 
/// has the origin (0,0) in the center of the display,
/// increasing coordinate values to the left of and above the origin
/// and decreasing (negative) values to the right of and below the origin.
/// This is the default coordinate system.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_coordinate_system(const int coordinate_system)
{
    ts5_check_graphics("ts5_set_coordinate_system");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_coordinate_system(%d)\n", 
                coordinate_system);

    int retval = _ts5_status.graphics.coordinate_system;

    if (coordinate_system != TS5_CARTESIAN_COORDINATES 
            && coordinate_system != TS5_DISPLAY_COORDINATES) {
        
        ts5_fatal("%s: %s (is %d)\n", "ts5_set_coordinate_system",
                    "coordinate_system should be 0 or 1",
                    coordinate_system);
    }

    _ts5_status.graphics.coordinate_system = coordinate_system;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n",
                "ts5_set_coordinate_system", 
                "set coordinate_system for next display to",
                _ts5_status.graphics.coordinate_system, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the coordinate system.
///
/// \return The coordinate system.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_coordinate_system()
{
    ts5_check_graphics("ts5_get_coordinate_system");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_coordinate_system()\n");

    return _ts5_status.graphics.coordinate_system;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the coordinate scale.
///
/// \param coordinate_scale Coordinate scale to be used. 
/// Can be TS5_RELATIVE_COORDINATES and TS5_ABSOLUTE_COORDINATES. 
/// Default is TS5_ABSOLUTE_COORDINATES.
///
/// \return The previous coordinate scale.
///
/// In the TS5_ABSOLUTE_COORDINATES scale coordinates 
/// are absolute pixel values. This is the default coordinate scale.
///
/// In the TS5_RELATIVE_COORDINATES scale coordinates vary 
/// between -1.0 and 1.0 in the TS5_CARTESIAN_COORDINATES system
/// and between 0.0 abd 1.0 in the TS5_DISPLAY_COORDINATES system.
///
/// Using the TS5_RELATIVE_COORDINATES scale has an influence on position 
/// but also on sizes:
/// - Display sizes are computed relative to the display adapter.
/// - Bitmap sizes are computed relative to the active display.
/// - Circle diameters are computed relative to the x axis.
/// - Font size and drawing thickness are always set in pixels.
/// - When querying the size of the display (adapter), drawing target or 
///   a bitmap the size in pixels is returned.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_coordinate_scale(const int coordinate_scale)
{
    ts5_check_graphics("ts5_set_coordinate_scale");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_coordinate_scale(%d)\n", coordinate_scale);

    int retval = _ts5_status.graphics.coordinate_scale;

    if (coordinate_scale != TS5_RELATIVE_COORDINATES 
            && coordinate_scale != TS5_ABSOLUTE_COORDINATES) {
        ts5_fatal("%s: %s (is %d)\n", "ts5_set_coordinate_scale",
                    "coordinate_scale should be 0 or 1", coordinate_scale);
    }

    _ts5_status.graphics.coordinate_scale = coordinate_scale;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n", "ts5_set_coordinate_scale",
                "set coordinate_scale for next display to",
                _ts5_status.graphics.coordinate_scale, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the coordinate scale.
///
/// \return The coordinate scale.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_coordinate_scale()
{
    ts5_check_graphics("ts5_get_coordinate_scale");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_coordinate_scale()\n");

    return _ts5_status.graphics.coordinate_scale;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a relative horizontal coordinate into an 
/// absolute horizontal coordinate.
///
/// This function can be called using the macro ax(x)
///
/// \param x Horizontal coordinate value as a proportion.
///
/// \return Horizontal coordinate value in pixels.
///
/// Its behavior depends on the coordinate system used.
/// - With the Cartesian system x=0 refers to the center of the display,
///   x=1 refers the to right-hand side border and 
///   x=-1 refers to the left-hand side border.
/// - With the display system x=0 refers to the right-hand side border and
///   x=1 refers to the left-hand side border.
///
/// It is possible to call this function as a parameter to a drawing function
/// (e.g.: when using the Cartesian coordinate system, 
/// ts5_putpixel (ts5_relative_to_absolute_coordinate_x(.5), 0);
/// writes a pixel 80 pixels to the right of the center 
/// in the case of a 320x240 sized display,
/// or 160 pixels to the right in the case of a 640x480 sized display).
////////////////////////////////////////////////////////////////////////////////
double ts5_relative_to_absolute_coordinate_x(const double x)
{
    ts5_check_graphics("ts5_relative_to_absolute_coordinate_x");
    ts5_log(TS5_LOGLEVEL_6, "ts5_relative_to_absolute_coordinate_x(%f)\n", x);

    double retval;

    if (_ts5_status.graphics.coordinate_system 
            == TS5_CARTESIAN_COORDINATES) {
        retval =  (x * (_ts5_status.graphics.target_width) / 2.0);
    }
    else {
        retval =  (x * _ts5_status.graphics.target_width);
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a relative vertical coordinate into an 
/// absolute vertical coordinate.
///
/// This function can be called using the macro ay(y)
///
/// \param y Vertical coordinate value as a proportion.
///
/// \return Vertical coordinate value in pixels.
///
/// Its behaviour completely parallells that of
/// ts5_relative_to_absolute_coordinate_x().
////////////////////////////////////////////////////////////////////////////////
double ts5_relative_to_absolute_coordinate_y(const double y)
{
    ts5_check_graphics("ts5_relative_to_absolute_coordinate_y");
    ts5_log(TS5_LOGLEVEL_6, "ts5_relative_to_absolute_coordinate_y(%f)\n", y);

    double retval;

    if (_ts5_status.graphics.coordinate_system 
            == TS5_CARTESIAN_COORDINATES) {
        retval = (y * (_ts5_status.graphics.target_height) / 2.0);
    }
    else {
        retval = (y * _ts5_status.graphics.target_height);
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert an absolute horizontal coordinate into a 
/// relative horizontal coordinate.
///
/// This function can be called using the macro rx(x)
///
/// \param x Horizontal coordinate value in pixels.
///
/// \return Horizontal coordinate value as a proportion.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_absolute_to_relative_coordinate_x(const double x)
{
    ts5_check_graphics("ts5_absolute_to_relative_coordinate_x");
    ts5_log(TS5_LOGLEVEL_6, "ts5_absolute_to_relative_coordinate_x(%f)\n", x);

    double retval;

    if (_ts5_status.graphics.coordinate_system 
            == TS5_CARTESIAN_COORDINATES) {
        retval =  (x / (_ts5_status.graphics.target_width) * 2.0);
    }
    else {
        retval =  (x / _ts5_status.graphics.target_width);
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert an absolute vertical coordinate into a 
/// relative vertical coordinate.
///
/// This function can be called using the macro ry(y)
///
/// \param y Vertical coordinate value in pixels.
///
/// \return Vertical coordinate value as a proportion.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_absolute_to_relative_coordinate_y(const double y)
{
    ts5_check_graphics("ts5_absolute_to_relative_coordinate_y");
    ts5_log(TS5_LOGLEVEL_6, "ts5_absolute_to_relative_coordinate_y(%f)\n", y);

    double retval;

    if (_ts5_status.graphics.coordinate_system 
            == TS5_CARTESIAN_COORDINATES) {
        retval =  (y / (_ts5_status.graphics.target_height) * 2.0);
    }
    else {
        retval =  (y / _ts5_status.graphics.target_height);
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a horizontal Cartesian coordinate into a 
/// horizontal display coordinate.
///
/// This function can be called using the macro dx(x)
///
/// \param x Horizontal coordinate value in the Cartesian coordinate system.
///
/// \return The coordinate value in the display coordinate system.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_cartesian_to_display_coordinate_x(const double x)
{
    ts5_check_graphics("ts5_cartesian_to_display_coordinate_x");
    ts5_log(TS5_LOGLEVEL_6, "ts5_cartesian_to_display_coordinate_x(%f)\n", x);

    return (_ts5_status.graphics.target_width) / 2.0 + x;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a vertical Cartesian coordinate into a 
/// vertical display coordinate.
///
/// This function can be called using the macro dy(y)
///
/// \param y Vertical coordinate value in the Cartesian coordinate system.
///
/// \return The coordinate value in the display coordinate system.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_cartesian_to_display_coordinate_y(const double y)
{
    ts5_check_graphics("ts5_cartesian_to_display_coordinate_y");
    ts5_log(TS5_LOGLEVEL_6, "ts5_cartesian_to_display_coordinate_y(%f)\n", y);

    return (_ts5_status.graphics.target_height) / 2.0 - y;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a horizontal display coordinate into a 
/// horizontal Cartisian coordinate.
///
/// This function can be called using the macro cx(x)
///
/// \param x Horizontal coordinate value in the display coordinate system.
///
/// \return The coordinate value in the Cartesian coordinate system.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_display_to_cartesian_coordinate_x(const double x)
{
    ts5_check_graphics("ts5_display_to_cartesian_coordinate_x");
    ts5_log(TS5_LOGLEVEL_6, "ts5_display_to_cartesian_coordinate_x(%f)\n", x);

    return x - (_ts5_status.graphics.target_width) / 2.0;
}


////////////////////////////////////////////////////////////////////////////////
/// Convert a vertical display coordinate into a 
/// vertical Cartisian coordinate.
///
/// This function can be called using the macro cy(y)
///
/// \param y Vertical coordinate value in the display coordinate system.
///
/// \return The coordinate value in the Cartesian coordinate system.
///
/// Mainly for internal use by Tscope5 itself.
////////////////////////////////////////////////////////////////////////////////
double ts5_display_to_cartesian_coordinate_y(const double y)
{
    ts5_check_graphics("ts5_display_to_cartesian_coordinate_y");
    ts5_log(TS5_LOGLEVEL_6, "ts5_display_to_cartesian_coordinate_y(%f)\n", y);

    return (_ts5_status.graphics.target_height) / 2.0 - y;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name Color definitions
/// Tscope5 describes colors in a structure (TS5_COLOR) containing red (r), 
/// green (g), blue (b) and alpha (a, transparency) values between 0.0 and 1.0.
///
/// The functions below generate such a color structure using 
/// the RGB, HSL or HSV color specification or using the w3c naming system.
///
/// Please note that the color structure is a structure, not a variable 
/// (they can only be assigned at the moment of declaration, not afterwards).
/// See the examples for instructions on how to use them.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Generate a color specification based on an RGB triplet
/// plus an alpha channel.
///
/// \param r Red. Range from 0.0 to 1.0.
/// \param g Green. Range from 0.0 to 1.0.
/// \param b Blue. Range from 0.0 to 1.0.
/// \param a Alpha. 0.0 is completely transparant and 1.0 is completely opaque.
///
/// \return TS5_COLOR structure.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_make_rgb_color(const double r, const double g, const double b, 
                                const double a)
{
    ts5_check_graphics("ts5_make_rgb_color");
    ts5_log(TS5_LOGLEVEL_5, "ts5_make_rgb_color(%f,%f,%f,%f)\n", r, g, b, a);

    if (r < 0.0|| g < 0.0 || b < 0.0 || a < 0.0 
            || r > 1.0 || g > 1.0 || b > 1.0 || a > 1.0) {
        ts5_fatal("%s: %s\n", "ts5_make_rgb_color",
                    "color values must be between 0.0 and 1.0");
    }

    return al_map_rgba_f(r, g, b, a);
}


////////////////////////////////////////////////////////////////////////////////
/// Generate a color specification based on an HSL triplet 
/// plus an alpha channel.
///
/// \param h Hue. Range from 0.0 to 360.0.
/// \param s Saturation. Range from 0.0 to 1.0.
/// \param l Lightness. Range from 0.0 to 1.0.
/// \param a Alpha. 0.0 is completely transparant and 1.0 is completely opaque.
///
/// \return TS5_COLOR sctructure.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_make_hsl_color(const double h, const double s, const double l, 
                                const double a)
{
    ts5_check_graphics("ts5_make_hsl_color");
    ts5_log(TS5_LOGLEVEL_5, "ts5_make_hsl_color(%f,%f,%f,%f)\n", h, s, l, a);

    if (h < 0.0 || s < 0.0 || l < 0.0 || a < 0.0 
        || h > 360.0 || s > 1.0 || l > 1.0 || a > 1.0) {
        ts5_fatal("%s: %s\n", "ts5_make_hsl_color",
                    "h:0.0-360.0, s:0.0-1.0, l:0.0-1.0, a:0.0-1.0");
    }

    float r, g, b;
    al_color_hsl_to_rgb(h, s, l, &r, &g, &b);

    return al_map_rgba_f(r, g, b, a);
}


////////////////////////////////////////////////////////////////////////////////
/// Generate a color specification based on an HSV triplet 
/// plus an alpha channel.
///
/// \param h Hue. Range from 0.0 to 360.0.
/// \param s Saturation. Range from 0.0 to 1.0.
/// \param v Value Range from 0.0 to 1.0.
/// \param a Alpha. 0.0 is completely transparant and 1.0 is completely opaque.
///
/// \return TS5_COLOR sctructure.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_make_hsv_color(const double h, const double s, const double v, 
                                const double a)
{
    ts5_check_graphics("ts5_make_hsv_color");
    ts5_log(TS5_LOGLEVEL_5, "ts5_make_hsv_color(%f,%f,%f,%f)\n", h, s, v, a);

    if (h < 0.0 || s < 0.0 || v < 0.0 || a < 0.0 
        || h > 360.0 || s > 1.0 || v > 1.0 || a > 1.0) {
        ts5_fatal("%s: %s\n", "ts5_make_hsv_color",
            "h:0.0-360.0, s:0.0-1.0, v:0.0-1.0, a:0.0-1.0");
    }

    float r, g, b;
    al_color_hsv_to_rgb(h, s, v, &r, &g, &b);

    return al_map_rgba_f(r, g, b, a);
}


////////////////////////////////////////////////////////////////////////////////
/// Return a color that corresponds to name.
///
/// \param name Name of the color.
/// \param a Alpha. 0.0 is completely transparant and 1.0 is completely opaque.
///
/// \return TS5_COLOR sctructure.
///
/// There recognized names are: aliceblue, antiquewhite, aqua, aquamarine,
/// azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown,
/// burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue,
/// cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray,
/// darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange,
/// darkorchid, darkred, darksalmon, darkseagreen, darkslateblue,
/// darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray,
/// dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro,
/// ghostwhite, goldenrod, gold, gray, green, greenyellow, honeydew, hotpink,
/// indianred, indigo, ivory, khaki, lavenderblush, lavender, lawngreen,
/// lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow,
/// lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue,
/// lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen,
/// magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple,
/// mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise,
/// mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, avajowhite,
/// navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod,
/// palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink,
/// plum, powderblue, purple, purwablue, red, rosybrown, royalblue,
/// saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver,
/// skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal,
/// thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow and
/// yellowgreen.
///
/// Colors are taken from
/// http://www.w3.org/TR/2010/PR-css3-color-20101028/#svg-color.
///
/// If the color is not found then black is returned.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_make_named_color(const char *name, const double a)
{
    ts5_check_graphics("ts5_make_named_color");
    ts5_log(TS5_LOGLEVEL_5, "ts5_make_named_color(%s,%f)\n", name, a);

    float r, g, b;

    if (!al_color_name_to_rgb(name, &r, &g, &b)) {
        ts5_fatal("ts5_make_named_color: color name %s not found\n", name);
    }

    return al_map_rgba_f(r, g, b,  a);
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name Graphics parameter functions
/// This part contains functions to change the graphics parameters 
/// of the text output and primitives drawing functions. 
/// - By default, text appears 20pt Courier Bold.
/// - Primitives are not filled, and drawn with hairline thickness.
/// - All drawing is done in white against a black background.
///
/// The text and drawing functions do not have arguments to alter
/// the graphics parameters. 
/// This is done with the parameter functions below. 
/// They all change one parameter, e.g. the foreground color. 
/// Once a parameter value is changed, that value is used for 
/// all further drawing until it is changed again.
///
/// The parameter functions all return the previous parameter setting. 
/// This can be useful when you want to change some parameters 
/// in one part of a program, 
/// do some drawing and set the previous parameters again 
/// without causing undesired parameter changes to other parts of the program.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Set the foreground color.
///
/// \param foreground_color TS5_COLOR color specification.
///
/// \return The previous foreground color.
///
/// Changes the drawing color of all subsequent drawing operations.
/// The default color is white. Once a color is set, 
/// it remains active until another color is set.
///
/// Tscope5 represents colors in an opaque structure (TS5_COLOR).
/// Several functions exist for generating such a color definition (see above).
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_set_foreground_color(const TS5_COLOR foreground_color)
{
    ts5_check_graphics("ts5_set_foreground_color");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_foreground_color((%f,%f,%f,%f))\n",
                foreground_color.r, foreground_color.g, foreground_color.b,
                foreground_color.a);

    TS5_COLOR oldcolor = _ts5_status.graphics.foreground_color;
    _ts5_status.graphics.foreground_color = foreground_color;

    unsigned char r, g, b, a;
    al_unmap_rgba(foreground_color, &r, &g, &b, &a);

    ts5_log(TS5_LOGLEVEL_4, "%s: r:%f, g:%f, b:%f, alpha:%f\n", 
        "ts5_set_foreground_color", r/256, g/256, b/256, a/256);
    
    return oldcolor;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the foreground color.
///
/// \return The foreground color.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_get_foreground_color()
{
    ts5_check_graphics("ts5_get_foreground_color");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_foreground_color()\n");

    return _ts5_status.graphics.foreground_color;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the background color.
///
/// \param background_color TS5_COLOR color specification.
///
/// \return The previous background color.
///
/// Changes the background color of all new drawing targets or when a
/// drawing target is cleared.
///
/// The default color is black. 
/// Once a color is set, it remains active until another color is set.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_set_background_color(const TS5_COLOR background_color)
{
    ts5_check_graphics("ts5_set_background_color");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_background_color((%f,%f,%f,%f))\n",
                background_color.r, background_color.g, background_color.b,
                background_color.a);

    TS5_COLOR oldcolor = _ts5_status.graphics.background_color;
    _ts5_status.graphics.background_color = background_color;

    unsigned char r, g, b, a;
    al_unmap_rgba(background_color, &r, &g, &b, &a);
    ts5_log(TS5_LOGLEVEL_4, "%s: r:%f, g:%f, b:%f, alpha:%f\n", 
        "ts5_set_background_color", r/256, g/256, b/256, a/256);

    return oldcolor;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the background color.
///
/// \return The background color.
////////////////////////////////////////////////////////////////////////////////
TS5_COLOR ts5_get_background_color()
{
    ts5_check_graphics("ts5_get_background_color");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_background_color()\n");

    return _ts5_status.graphics.background_color;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the drawing thickness.
///
/// \param drawing_thickness Drawing thickness in pixels.
///
/// \return The previous thickness.
///
/// Changes thickness of lines for all drawing operations.
///
/// The default thickness is 0 (hairline).
////////////////////////////////////////////////////////////////////////////////
double ts5_set_drawing_thickness(double drawing_thickness)
{
    ts5_check_graphics("ts5_set_drawing_thickness");
    
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_drawing_thickness(%f)\n", 
                drawing_thickness);

    double retval = _ts5_status.graphics.drawing_thickness;

    if (drawing_thickness < 0.0) {
        drawing_thickness = -1.0;
    }

    _ts5_status.graphics.drawing_thickness = drawing_thickness;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %f (was %f)\n", 
                "ts5_set_drawing_thickness", "set drawing_thickness to",
                _ts5_status.graphics.drawing_thickness, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the drawing thickness.
///
/// \return The drawing thickness.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_drawing_thickness()
{
    ts5_check_graphics("ts5_get_drawing_thickness");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_drawing_thickness()\n");

    return _ts5_status.graphics.drawing_thickness;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the fill mode.
///
/// \param fill_mode Fill mode. Can be TS5_FILL_ON or TS5_FILL_OFF.
///
/// \return The previous fill mode.
///
/// Changes the fill mode for future drawing operations.
///
/// The default fill mode is TS5_FILL_OFF.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_fill_mode(const int fill_mode)
{
    ts5_check_graphics("ts5_set_fill_mode");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_fill_mode(%d)\n", fill_mode);

    int retval = _ts5_status.graphics.fill_mode;

    if (fill_mode != TS5_FILL_ON && fill_mode != TS5_FILL_OFF) {
        ts5_fatal("%s: %s %s\n", "ts5_set_fill_mode", "fill_mode should be",
                    "TS5_FILL_OFF (off) or TS5_FILL_ON (on)");
    }

    _ts5_status.graphics.fill_mode = fill_mode;

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_fill_mode: set mode to %d (was %d)\n",
                _ts5_status.graphics.fill_mode, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the fill mode.
///
/// \return The fill mode.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_fill_mode()
{
    ts5_check_graphics("ts5_get_fill_mode");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_fill_mode()\n");

    return _ts5_status.graphics.fill_mode;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the font type.
///
/// \param font_type Font type. Can be TS5_COURIER, TS5_ARIAL and TS5_TIMES.
///
/// \return The previous font type.
///
/// The default font type is TS5_COURIER.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_font_type(const int font_type)
{
    ts5_check_graphics("ts5_set_font_type");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_type(%d)\n", font_type);

    int retval = _ts5_status.graphics.font_type;

    if (font_type != TS5_COURIER 
            && font_type != TS5_ARIAL 
            && font_type != TS5_TIMES) {
                
        ts5_fatal("%s: %s %s\n", "ts5_set_font_type", "font_type should be",
                    "TS5_COURIER, TS5_ARIAL or TS5_TIMES");
    }

    _ts5_status.graphics.font_type = font_type;

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_type: set font type to %d (was %d)\n",
                                _ts5_status.graphics.font_type, retval);

    _ts5_status.graphics.font_index =
        _ts5_status.graphics.font_type * TS5_FONTSTYLES * TS5_FONTSIZES +
        _ts5_status.graphics.font_style * TS5_FONTSIZES +
        _ts5_status.graphics.font_size - 8;

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the font type.
///
/// \return The font type.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_font_type()
{
    ts5_check_graphics("ts5_get_font_type");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_font_type()\n");

    return _ts5_status.graphics.font_type;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the font style.
///
/// \param font_style Font style. 
/// Can be TS5_REGULAR, TS5_BOLD, TS5_ITALIC or TS5_BOLD_ITALIC.
///
/// \return The previous font style.
///
/// The default font style is TS5_BOLD.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_font_style(const int font_style)
{
    ts5_check_graphics("ts5_set_font_style");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_style(%d)\n", font_style);

    int retval = _ts5_status.graphics.font_style;

    if (font_style != TS5_REGULAR 
            && font_style != TS5_BOLD 
            && font_style != TS5_ITALIC 
            && font_style != TS5_BOLD_ITALIC) {
                
        ts5_fatal("%s: %s %s\n", "ts5_set_font_style", "font_style should be",
                    "TS5_REGULAR, TS5_BOLD, TS5_ITALIC or TS5_BOLD_ITALIC");
    }

    _ts5_status.graphics.font_style = font_style;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n",
                "ts5_set_font_style", "set font style to",
                _ts5_status.graphics.font_style, retval);

    _ts5_status.graphics.font_index =
        _ts5_status.graphics.font_type * TS5_FONTSTYLES * TS5_FONTSIZES +
        _ts5_status.graphics.font_style * TS5_FONTSIZES +
        _ts5_status.graphics.font_size - 8;

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the font style.
///
/// \return The font style.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_font_style()
{
    ts5_check_graphics("ts5_get_font_style");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_font_style()\n");

    return _ts5_status.graphics.font_style;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the font size.
///
/// \param font_size Font size. Can be any value between 8 and 107.
///
/// \return The previous font size.
///
/// The default font size is 20.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_font_size(int font_size)
{
    ts5_check_graphics("ts5_set_font_size");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_size(%d)\n", font_size);

    int retval = _ts5_status.graphics.font_size;

    if (font_size < 8 || font_size > 107) {
        ts5_fatal("ts5_set_font_size: font_size should be between 8 and 107\n");
    }

    _ts5_status.graphics.font_size = font_size;

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_size: set font size to %d (was %d)\n",
                _ts5_status.graphics.font_size, retval);

    _ts5_status.graphics.font_index =
        _ts5_status.graphics.font_type * TS5_FONTSTYLES * TS5_FONTSIZES +
        _ts5_status.graphics.font_style * TS5_FONTSIZES +
        _ts5_status.graphics.font_size - 8;

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the font size.
///
/// \return The font size.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_font_size()
{
    ts5_check_graphics("ts5_get_font_size");
    ts5_check_textio("ts5_get_font_size");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_font_size()\n");

    int size = _ts5_status.graphics.font_size;

    return size;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the font index.
///
/// \param font_index Font index. Can be any integer between 0 and TS5_NFONTS-1.
///
/// \return The previous font index.
///
/// Sets the font type, style and width at once.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_font_index(const int font_index)
{
    ts5_check_graphics("ts5_set_font_index");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_font_index(%d)\n", font_index);

    int retval = _ts5_status.graphics.font_index;

    if (font_index < 0 || font_index >= TS5_NFONTS) {
        ts5_fatal("%s: %s", "ts5_set_font_index",
                    "font_index should be between 0 and TS5_NFONTS-1\n");
    }

    _ts5_status.graphics.font_index = font_index;

    // update size etc.
    _ts5_status.graphics.font_size = 
        (font_index % TS5_FONTSIZES) + 8;
    
    _ts5_status.graphics.font_style = 
        (font_index / TS5_FONTSIZES) % TS5_FONTSTYLES;
    
    _ts5_status.graphics.font_type = 
        font_index / (TS5_FONTSIZES * TS5_FONTSTYLES);

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n", 
                "ts5_set_font_index", "set font index to", 
                _ts5_status.graphics.font_index, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the font index.
///
/// \return The font index.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_font_index()
{
    ts5_check_graphics("ts5_get_font_index");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_font_index()\n");

    return _ts5_status.graphics.font_index;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the alignment of text.
///
/// \param text_alignment Text alignment. 
/// Can be TS5_ALIGN_LEFT, TS5_ALIGN_CENTER or TS5_ALIGN_RIGHT.
///
/// \return The previous alignment setting.
///
/// The default aligment is TS5_ALIGN_CENTER.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_text_alignment(const int text_alignment)
{
    ts5_check_graphics("ts5_set_text_alignment");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_text_alignment(%d)\n", text_alignment);

    int retval = _ts5_status.graphics.text_alignment;

    if (text_alignment != TS5_ALIGN_LEFT 
            && text_alignment != TS5_ALIGN_CENTER 
            && text_alignment != TS5_ALIGN_RIGHT) {

        ts5_fatal("%s: %s %s\n", "ts5_set_text_alignment",
                    "text_alignment should be",
                    "TS5_ALIGN_LEFT, TS5_ALIGN_CENTER or TS5_ALIGN_RIGHT");
    }

    _ts5_status.graphics.text_alignment = text_alignment;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n",
                "ts5_set_text_alignment", "set alignment to", 
                _ts5_status.graphics.text_alignment, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the alignment of text.
///
/// \return The alignment setting.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_text_alignment()
{
    ts5_check_graphics("ts5_get_text_alignment");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_text_alignment()\n");

    return _ts5_status.graphics.text_alignment;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////