API for libcrtxy (CRT X-Y Library)

http://libcrtxy.sf.net/
by Bill Kendrick <bill@newbreedsoftware.com>

August 3, 2008 - August 3, 2008
Version: 0.0.1


Compiling with libcrtxy

Use the "crtxy-config" command to get the options necessary to compile and link an application against libcrtxy.

crtxy-config --cflags
This outputs compiler flags necessary to compile a C or C++ program with libcrtxy.
Example: gcc game.c -c `crtxy-config --cflags`
crtxy-config --libs
This outputs compiler flags necessary to link a program against libcrtxy as a shared library.
Example: gcc -o game game.o other.o `crtxy-config --libs`
crtxy-config --static-libs
This outputs compiler flags necessary to link a program against libcrtxy as a static library.
Example: gcc -o game game.o other.o `crtxy-config --static-libs`
crtxy-config --version
This outputs the version of libcrtxy that is installed. It's useful for automated checking of whether the installed version of libcrtxy is compatible with what your application expects.

Note: Since libcrtxy depends on libSDL, the output of crtxy-config includes the output of libSDL's sdl-config for --cflags, --libs and --static-libs.

Including libcrtxy header

crtxy-config --cflags should have told your compiler where to find libcrtxy's headers, so you should include the main header like this:

#include "crtxy.h"

Note: libcrtxy depends on libSDL, so its SDL.h is included automatically. SDL_image library's SDL_image.h may also have been included. However, no harm is done by including them in your own source.

Using libcrtxy

Basic Types

XY_bool
A boolean; either XY_TRUE or XY_FALSE.
XY_bitmap
A bitmap. libcrtxy lets you load images, and returns a pointer to a new XY_bitmap structure.
XY_fixed
Since libcrtxy is meant to help you target even very low-end systems, fixed-point math is used, rather than floating-point. Floating-point calculations are generally slower than fixed-point, and low-end systems often lack an FPU.

Basic Types Constants

XY_TRUE and XY_FALSE
These represent true/success and false/failure, respectively.
XY_FIXED_ONE and XY_FIXED_HALF
These represent 1 and 0.5 in libcrtxy's fixed-point.
XY_FIXED_MIN and XY_FIXED_MAX
These represent the smallest number (a very large negative value) and largest number (a very large positive value) that can be represented in libcrtxy's fixed-point.
XY_FIXED_NAN
Not-a-number, returned if you try to divide a fixed-point value by 0. (It happens to also be equal to XY_FIXED_MAX.)
XY_FIXED_SHIFT
How much shifting ("<<" and ">>") is done when converting between integers and libcrtxy's fixed-point. For example, XY_FIXED_ONE (1.0 in fixed-point) is equal to "1 << XY_FIXED_SHIFT", and XY_FIXED_HALF (0.5 in fixed-point) is equal to "1 << (XY_FIXED_SHIFT - 1)".

Errors in libcrtxy

When calls to libcrtxy functions fail, they typically return a value that you should test for. (Some functions return an XY_bool of XY_FALSE, others return a NULL pointer, etc.) They also set an error code which you can access:

int XY_errcode(void)
Returns the current error code. (See below.)
const char * XY_errstr(void)
Returns a human-readable string representing the current error code.

Error codes

Gathering libcrtxy options

One of libcrtxy's main goals is to separate gameplay from rendering. Your game should play the same on a 320x240 screen on a system with a slow CPU as it does on a 1280x1024 screen on a high-end system. How good things can look depends on the capabilities of the system your game is running on. The end-user is given the ability to change libcrtxy's options to help get your game to run well on their system.

libcrtxy provides a number of functions that determine what settings the user wants for libcrtxy's options, and places them in an "XY_options" structure:

void XY_default_options(XY_options * opts)
You must call this.
This fills the contents of "opts" with the default libcrtxy settings (determined when libcrtxy itself was compiled.)
XY_bool XY_load_options(XY_options * opts)
You are encouraged to call this.
This opens and reads the contents of two files: a system-wide (global) configuration file for libcrtxy, and a user-specific (local) configuration file for libcrtxy. Neither file is required, but if there are any errors reading from it (a bad value to an option, or an unknown option), this function returns XY_FALSE and sets the error code to XY_ERR_OPTION_BAD or XY_ERR_OPTION_UNKNOWN, respectively.
XY_bool XY_load_options_from_file(char * fname, XY_options * opts, XY_bool ignore_unknowns)
This is useful for letting end-users place libcrtxy settings in your game's config. file.
This opens and reads the contents of the specified file ('fname') and looks for libcrtxy option settings. If the file is not found or cannot be opened, this function returns XY_FALSE and sets the error code to XY_ERR_FILE_CANT_OPEN. If 'ignore_unknowns' is set to XY_TRUE, it will ignore any lines in the file that don't seem to have libcrtxy-related settings, otherwise it will stop reading the file, set the error code to XY_ERR_OPTION_UNKNOWN, and return XY_FALSE. If it comes across any bad values for an option, it will stop reading the file, set the error code to XY_ERR_OPTION_BAD and return XY_FALSE.
int XY_parse_options(int * argc, char * argv[], XY_options * opts)
You are encouraged to call this, then check command-line arguments for your game's own settings.
This checks your program's command-line arguments for any libcrtxy-related option settings. It 'consumes' any arguments that it recognizes, by removing them from 'argv', and reducing the value of 'argc'. If it comes across any bad values for an option, it will stop parsing the arguments, set the error code to XY_ERR_OPTION_BAD and return an index into 'argv' for the questionable option. If it comes across any arguments that begin with "--crtxy-" that it doesn't recognize, it will stop parsing, set the error code to XY_ERR_OPTION_UNKNOWN and return an index into 'argv' for that argument. If it parses the command-line with no error, it returns 0 to denote success. If the user supplies an argument of "--help-crtxy", the available libcrtxy-related options will be displayed to stdout, and the program will terminate.
XY_bool XY_parse_envvars(XY_options * opts)
You are encouraged to call this.
This checks the enviroment (via getenv()) for various variables which are used to set libcrtxy options. If it comes across any bad values for an option, it will stop checking environment variables, set the error code to XY_ERR_OPTION_BAD and return XY_FALSE.

Generally, if any of the functions return an error (non-0 from XY_parse_options or XY_FALSE from any of the others), you should terminate your program.

If you want to show a human-readable list of the settings inside of an XY_options structure, you can use:

void XY_print_options(FILE * fi, XY_options opts)
'fi' is a writable file stream (e.g., a logfile opened for write, stderr or stdout).

Example

#include "crtxy.h"

int main(int argc, char * argv[])
{
  XY_options opts;
  int ret;

  XY_default_options(&opts);
  if (XY_load_options(&opts) == XY_FALSE)
  {
    fprintf(stderr, "Error loading options: %s\n", XY_errstr());
    return(1);
  }
  if (XY_parse_envvars(&opts) == XY_FALSE)
  {
    fprintf(stderr, "Error with env. vars.: %s\n", XY_errstr());
    return(1);
  }
  ret = XY_parse_options(&argc, argv, &opts);
  if (ret != 0)
  {
    fprintf(stderr, "Error with arg %s: %s\n", argv[ret], XY_errstr());
    return(1);
  }
  
... etc.

Available libcrtxy options:

The options libcrtxy supports are listed below, along with how they should be presented in configuration files, on the command-line, and as environment variables:

FIXME: More Using... content