libgfx: Getting Started
Author: Michael Garland

## 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:

Symbol | Defined 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