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'ssdl-config
for --cflags, --libs and --static-libs.
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'sSDL_image.h
may also have been included. However, no harm is done by including them in your own source.
Basic Types
XY_bool
- A boolean; either
XY_TRUE
orXY_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
andXY_FALSE
- These represent true/success and false/failure, respectively.
XY_FIXED_ONE
andXY_FIXED_HALF
- These represent 1 and 0.5 in libcrtxy's fixed-point.
XY_FIXED_MIN
andXY_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
", andXY_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
ofXY_FALSE
, others return aNULL
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
XY_ERR_NONE
- No error occured.XY_ERR_OPTION_BAD
- Invalid value for an option.XY_ERR_OPTION_UNKNOWN
- Unknown option.XY_ERR_FILE_CANT_OPEN
- Unable to open a file.XY_ERR_MEM_CANT_ALLOC
- Ran out of memory.XY_ERR_INIT_VIDEO
- Unable to initialize video subsystem.XY_ERR_INIT_DISPLAY
- Unable to open the display.XY_ERR_INIT_UNSUPPORTED_BPP
- Color depth not supported.XY_ERR_BITMAP_CANT_DECODE
- Unable to decode an image file.XY_ERR_BITMAP_CANT_CONVERT
- Unable to convert a bitmap.XY_ERR_BITMAP_CANT_SCALE
- Unable to scale a bitmap.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 returnsXY_FALSE
and sets the error code toXY_ERR_OPTION_BAD
orXY_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 returnsXY_FALSE
and sets the error code toXY_ERR_FILE_CANT_OPEN
. If 'ignore_unknowns' is set toXY_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 toXY_ERR_OPTION_UNKNOWN
, and returnXY_FALSE
. If it comes across any bad values for an option, it will stop reading the file, set the error code toXY_ERR_OPTION_BAD
and returnXY_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 toXY_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 toXY_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 tostdout
, and the program will terminate.XY_bool XY_parse_envvars(XY_options * opts)
- You are encouraged to call this.
This checks the enviroment (viagetenv()
) 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 toXY_ERR_OPTION_BAD
and returnXY_FALSE
.Generally, if any of the functions return an error (non-0 from
XY_parse_options
orXY_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
orstdout
).Example
#include "crtxy.h"
... etc.
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);
}
Available libcrtxy options:
FIXME: More Using... contentThe 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: List them...
--crtxy-width WIDTH --crtxy-height HEIGHT --crtxy-bpp [16|24|32|any] --crtxy-fullscreen --crtxy-fullscreen-or-windo --crtxy-windowed --crtxy-alpha [on|off|fake] --crtxy-antialias [on|off] --crtxy-blur [on|off] --crtxy-additive [on|off] --crtxy-backgrounds [on|off --crtxy-scaling [best|fast]