Getting Started

The libgfx library can be used for writing both console-oriented and GUI programs. All programs, whether console or GUI, should begin by including the standard header:

    #include <gfx/gfx.h>

The Standard Header: gfx.h

The first task of the standard header file is to provide a consist code environment. It begins by including a set of standard C++ headers <cstdlib>, <cmath>, <climits>, and <iostream>. It then makes sure that various common symbols, such as bool, M_PI, and HUGE are defined.

Numerical Procedures

Graphics programs typically involve a substantial amount of mathematical calculation. Indeed, much the the libgfx library is devoted to supporting things such as matrix/vector computations. Certain mathematical procedures are common enough, and simple enough, that they are included in the standard header.

First, there are the procedures for generating random numbers:

    inline double random1();        // Random number between 0 and 1
    inline char   random_byte();    // Random byte between 0 and 255
These functions use the internal random() procedure if it's available, or rand() if not.

Next, are procedures for comparing floating point numbers:

    const double FEQ_EPS = 1e-6;
    const double FEQ_EPS2 = 1e-12;

    inline bool  FEQ(double a, double b, double eps=FEQ_EPS);
    inline bool  FEQ2(double a, double b, double eps=FEQ_EPS2);
The FEQ() procedures return true if a and b are within eps of each other.

Timing Procedures

To characterize the performance of a program, it is often useful to measure it's running time. For this reason, libgfx provides some basic facilities for measuring time.

    extern double get_cpu_time();
The function returns the number of seconds on the CPU clock. Based on the platform you're using, this function may use various system services to compute this clock. Therefore, it does not use a consistent measure across all systems; however, the returned quantity will usually be the number of seconds since the system was turned on.

A more convenient way to measure running time is to use the following macro:

    #define TIMING(t, cmd) { t=get_cpu_time(); cmd; t=get_cpu_time() - t; }
Given a procedure test_proc() whose performance we want to measure, we can use the following code:
    double running_time;

    TIME(running_time, test_proc());

    cout << "The running time was: " << running_time << " seconds." << endl;
This will print the running time of test_proc() on the console.

Configuration Definitions

The final task of the standard header is to include the libgfx configuration header. This header is generated when the library is compiled. On Unix-like platforms, the header is named <gfx/config.h> and is generated automatically by the configuration script. For Microsoft Visual Studio platforms, a hand-coded header such as <gfx/config-vc5.h> is used instead. The symbols defined in this header can be used to detect the presence of various language features and external libraries. The symbols of interest to external programs are summarized below:

SymbolDefined when ...
HAVE_LIBTIFF library supporting TIFF image I/O is available.
HAVE_LIBTIFF_LZW libtiff supports patented LZW compression.
HAVE_LIBPNG library supporting PNG image I/O is available.
HAVE_LIBJPEG library supporting JPEG image I/O is available.
HAVE_OPENGL OpenGL is available. Value is name of implementation (e.g., "OpenGL" or "Mesa").

These configuration symbols should be tested with #ifdef directives, as in the following example:

    #ifdef HAVE_LIBTIFF
    generate_tiff_output();
    #endif