Modules | |
libcrtxy boolean type | |
libcrtxy background bitmap management | |
libcrtxy color manipulation and conversion | |
libcrtxy fixed-point | |
libcrtxy geometry | |
libcrtxy option constants and functions | |
XY_err - libcrtxy error reporting | |
libcrtxy bitmap positioning flags | |
libcrtxy options for scaling bitmaps that don't match screen/window size | |
Initializing and quitting libcrtxy. | |
Starting and ending a drawing frame. | |
Line collection manipulation. | |
Drawing primitives. | |
Fixed-point math functions. | |
Screen/canvas conversions and queries. | |
Intersection tests. | |
void | XY_default_options (XY_options *opts) |
Set opts to default (libcrtxy's compiled-time) options. | |
XY_bool | XY_load_options (XY_options *opts) |
Load global, then local (user) libcrtxy config files into opts. | |
XY_bool | XY_load_options_from_file (char *fname, XY_options *opts, XY_bool ignore_unknowns) |
Load arbitrary config file into opts. | |
int | XY_parse_options (int *argc, char *argv[], XY_options *opts) |
Parse libcrtxy-related command-line arguments into opts. | |
XY_bool | XY_parse_envvars (XY_options *opts) |
Read any libcrtxy-related environment variables into opts. | |
const char * | XY_errstr (void) |
Gets a string representing the most recent error code. | |
void | XY_print_options (FILE *fi, XY_options opts) |
Dumps options in opts to the file stream (eg, stderr or an opened logfile). | |
XY_bitmap * | XY_load_bitmap_from_buffer (unsigned char *buffer, int size) |
Create a bitmap based on image data in a buffer. | |
void | XY_free_bitmap (XY_bitmap *bitmap) |
Free a bitmap. | |
XY_bool | XY_set_background (XY_color color, XY_bitmap *bitmap, XY_fixed x, XY_fixed y, int posflags, int scaling) |
Set the background color, and optional bitmap, its position, and options for scaling it to the screen size. | |
void | XY_enable_background (XY_bool enable) |
Enable or disable the background bitmap (affects next frame). | |
void | XY_getcolor (XY_color c, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a) |
Breaks an XY_color into its R, G, B and A components. |
For events (keyboard, mouse, joystick, etc.), your event loop, sound effects, etc., you use SDL functions and types directly. For video initialization, loading and displaying of bitmaps, and drawing vectors, libcrtxy's "XY_" functions and types should be used.
Screen-size shouldn't matter to game-play, so physical screen size in pixels (e.g., 640x480 or 1280x1024) is up to the end-user, or person packaging your software for a particular target, as well. Your game logic is based around a virtual canvas size, and line positions are given using fixed-point values.
The options that can be set at runtime include:
For support for various formats of bitmap images (PNG, JPEG, GIF, etc.), SDL_image is also required, available from http://www.libsdl.org/projects/SDL_image/
make
.Makefile
variables via command-line arguments to make
(e.g., make PREFIX=/home/username/opt/
):
PREFIX
- Base path of where everything gets installed (default: /usr/local
) CONFDIR
- Path where libcrtxy's global configuration file will be installed, and looked for. (default: $PREFIX/etc/libcrtxy
, unless PREFIX
is /usr
, in which case it is simply /etc/libcrtxy
) LIBDIR
- Path where libcrtxy's object files will be placed (and where crtxy-config --libs
will report them). (default: $PREFIX/lib
) INCDIR
- Path where libcrtxy's header files will be placed (and where crtxy-config --cflags
will report them). (default: $PREFIX/include
) BINDIR
- Path where the crtxy-config
helper tool will be installed. (default: $PREFIX/bin
)crtxy-config
helper tool, simply type make install
.
Note: Provide make
with the same variable overrides you gave it when installing (e.g., make PREFIX=/home/username/opt/ install
)
make tests
.
crtxy-config
command get the options necessary to compile and link an application against libcrtxy.
crtxy-config --cflags
gcc game.c -c `crtxy-config --cflags`
crtxy-config --libs
gcc -o game game.o other.o `crtxy-config --libs`
crtxy-config --static-libs
gcc -o game game.o other.o `crtxy-config --static-libs`
crtxy-config --version
crtxy-config
includes the output of libSDL's sdl-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's SDL_image.h
may also have been included. However, no harm is done by including them in your own source.
XY_default_options()
function sets some base values for the various options, in case no others are sent elsewhere. These are the values compiled into libcrtxy.XY_load_options()
function loads options from configuration files specific to libcrtxy. XY_load_options_from_file()
may be used by applications to load options from arbitrary files (such as a game's own config. file).
crtxy-width=NNN
crtxy-height=NNN
crtxy-bpp={16|24|32|any}
crtxy-windowed
crtxy-fullscreen
crtxy-fullscreen-or-window
crtxy-alpha={on|fake|off}
crtxy-antialias={on|off}
crtxy-backgrounds={on|off}
crtxy-scaling={best|fast}
crtxy-gamma-correction={on|off}
crtxy-blur={on|off}
crtxy-additive={on|off}
XY_parse_envvars()
examines the application's runtime enviroment for libcrtxy-related variables.
CRTXY_WIDTH
CRTXY_HEIGHT
CRTXY_BPP
(16|24|32|ANY) CRTXY_FULLSCREEN
(ON|OPTIONAL|OFF) CRTXY_ALPHA
(ON|FAKE|OFF) CRTXY_ANTIALIAS
(ON|OFF) CRTXY_BACKGROUNDS
(ON|OFF) CRTXY_SCALING
(BEST|FAST) CRTXY_GAMMA_CORRECTION
(ON|OFF) CRTXY_BLUR
(ON|OFF) CRTXY_ADDITIVE
(ON|OFF)XY_parse_options()
function can look for and parse and libcrtxy-related options found in the command-line arguments to an application.
--crtxy-width NNN
--crtxy-height NNN
--crtxy-bpp {16|24|32|any}
--crtxy-windowed
--crtxy-fullscreen
--crtxy-fullscreen-or-window
--crtxy-alpha {on|fake|off}
--crtxy-antialias {on|off}
--crtxy-backgrounds {on|off}
--crtxy-scaling {best|fast}
--crtxy-gamma-correction {on|off}
--crtxy-blur {on|off}
--crtxy-additive {on|off}
--help-crtxy
- Presents a list of libcrtxy-related usage, and quits. void XY_default_options | ( | XY_options * | opts | ) |
Set opts to default (libcrtxy's compiled-time) options.
Call this first, to get a base set of options, in case no other means is available.
opts | is a pointer to an options structure to fill. |
XY_bool XY_load_options | ( | XY_options * | opts | ) |
XY_bool XY_load_options_from_file | ( | char * | fname, | |
XY_options * | opts, | |||
XY_bool | ignore_unknowns | |||
) |
Load arbitrary config file into opts.
fname | is the name of a file to load options from. | |
opts | is a pointer to an options structure to fill. | |
ignore_unknowns | set to XY_TRUE to prevent function from aborting on unrecognized lines (useful if you want to let users put libcrtxy configuration options in an app-specific config file.) |
int XY_parse_options | ( | int * | argc, | |
char * | argv[], | |||
XY_options * | opts | |||
) |
Parse libcrtxy-related command-line arguments into opts.
argc | is a count of arguments to parse. | |
argv | is an array of arguments to parse. | |
opts | is a pointer to an options structure to fill. |
XY_bool XY_parse_envvars | ( | XY_options * | opts | ) |
const char* XY_errstr | ( | void | ) |
Gets a string representing the most recent error code.
void XY_print_options | ( | FILE * | fi, | |
XY_options | opts | |||
) |
Dumps options in opts to the file stream (eg, stderr or an opened logfile).
fi | is a file pointer to output to (stderr or stdout could be used, or a file that you've opened for write or append using fopen()) | |
opts | is a pointer to an options structure that has been filled. |
XY_bitmap* XY_load_bitmap_from_buffer | ( | unsigned char * | buffer, | |
int | size | |||
) |
Create a bitmap based on image data in a buffer.
buffer | is a pointer to memory containing image file data. | |
size | is the size of the image file data. |
void XY_free_bitmap | ( | XY_bitmap * | bitmap | ) |
Free a bitmap.
bitmap | is an XY_bitmap pointer to free. (Do not use the pointer any more! You may reuse your variable, if you create a new bitmap, of course.) |
XY_bool XY_set_background | ( | XY_color | color, | |
XY_bitmap * | bitmap, | |||
XY_fixed | x, | |||
XY_fixed | y, | |||
int | posflags, | |||
int | scaling | |||
) |
Set the background color, and optional bitmap, its position, and options for scaling it to the screen size.
Enables background bitmap.
color | is an XY_color for the display's background. (The entire display will be this color, if no bitmap is provided, otherwise any part of the display not covered by the bitmap will be this color. Lines alpha-blended or anti-aliased in 'fake' rendering mode will blend against this color, as well.) | |
bitmap | is an XY_bitmap pointer for a background image to use. It may be NULL if no background image is desired. | |
x | represents how far right (or left, if negative) to nudge the background image after it has been positioned, in canvas units. Use 0 for no nudging. | |
y | represents how far down (or up, if negative) to nudge the background image after it has been positioned, in canvas units. Use 0 for no nudging. | |
posflags | determines how to position a bitmap. Use the "|" (or) bitwise operator to combine one horizontal choice (XY_POS_LEFT, XY_POS_HCENTER or XY_POS_RIGHT) with one vertical choice (XY_POS_TOP, XY_POS_VCENTER or XY_POS_BOTTOM). Use 0 as a shortcut for 'top left'. | |
scaling | describes how the bitmap should be scaled. Use one of the following: XY_SCALE_NONE, XY_SCALE_STRETCH, XY_SCALE_KEEP_ASPECT_WIDE or XY_SCALE_KEEP_ASPECT_TALL. |
void XY_enable_background | ( | XY_bool | enable | ) |
void XY_getcolor | ( | XY_color | c, | |
Uint8 * | r, | |||
Uint8 * | g, | |||
Uint8 * | b, | |||
Uint8 * | a | |||
) |
Breaks an XY_color into its R, G, B and A components.
c | An XY_color from which color components should be extracted. | |
r | Pointer to a variable to contain the red component. | |
g | Pointer to a variable to contain the blue component. | |
b | Pointer to a variable to contain the green component. | |
a | Pointer to a variable to contain the alpha component (0 represents transparent, 255 represents opaque). |