The CRT X-Y library (libcrtxy)


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_bitmapXY_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.

Backends that libcrtxy can use for drawing

libcrtxy is being built on top of libSDL, the Simple DirectMedia Layer library (http://www.libsdl.org/), and therefore uses it (and SDL_Image for bitmap loading) as a backend. It should be reasonable for someone to develop an SDL+OpenGL backend for accelerated graphics.

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.

Todo:
Add OpenGL support.

Options for rendering quality that libcrtxy provides

Depending on the target system (e.g., a high-powered desktop PC or an embedded handheld system with a slow CPU and no FPU), various options can be set in libcrtxy. On a slow system, fancy visual effects intended to simulate an arcade experience can be disabled (anti-aliasing, blurring, etc.).

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:

libcrtxy display settings

libcrtxy rendering quality settings

libcrtxy special effects settings

libcrtxy options propagation

The options that get used are determined by the following, and should occur in this order: See also: Setting Options

Installing libcrtxy

libcrtxy requirements

libcrtxy requires the Simple DirectMedia Layer library (libSDL), available from http://www.libsdl.org/

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/

libcrtxy - compiling the library

To compile libcrtxy, simply type make.

Compilation Options

You may override the following Makefile variables via command-line arguments to make (e.g., make PREFIX=/home/username/opt/):

Todo:
Documentation installation
Todo:
Man page installation

libcrtxy - installing the library

To install libcrtxy's library files, header files, default global configuration file and the 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)

libcertxy - compiling the test applications

Once libcrtxy is installed, you can build the test applications that came with the source. Type: make tests.

Building Games with libcrtxy

libcrtxy - Using crtxy-config to compile and link

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

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.

libcrtxy - Using crtxy-config to compile and link

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.

Setting Options

libcrtxy options breakdown

Display options

Rendering quality options

Visual effects

libcrtxy - Where Options Can Get Set

Options such as rendering quality settings and screen resolution can come from various places. They are listed below, in the most reasonable order that they should be picked up:

Defaults

The 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.

Config. Files

The 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).

Environment Variables

XY_parse_envvars() examines the application's runtime enviroment for libcrtxy-related variables.

Command-Line Arguments

Finally, the XY_parse_options() function can look for and parse and libcrtxy-related options found in the command-line arguments to an application.


Function Documentation

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.

Parameters:
opts is a pointer to an options structure to fill.

XY_bool XY_load_options ( XY_options opts  ) 

Load global, then local (user) libcrtxy config files into opts.

Parameters:
opts is a pointer to an options structure to fill.
Returns:
On success: XY_TRUE. On failure, XY_FALSE, and sets error code to one of the following:

XY_bool XY_load_options_from_file ( char *  fname,
XY_options opts,
XY_bool  ignore_unknowns 
)

Load arbitrary config file into opts.

Parameters:
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.)
Returns:
On success: XY_TRUE. On failure, XY_FALSE, and sets error code to one of the following:
Todo:
Support a callback function for processing non-libcrtxy-related options without processing files twice.

int XY_parse_options ( int *  argc,
char *  argv[],
XY_options opts 
)

Parse libcrtxy-related command-line arguments into opts.

Parameters:
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.
Returns:
On success: 0 on success. On failure, an index into argv[] of an offending argument, and sets error code to one of the following:

XY_bool XY_parse_envvars ( XY_options opts  ) 

Read any libcrtxy-related environment variables into opts.

Parameters:
opts is a pointer to an options structure to fill.
Returns:
On success: XY_TRUE. On failure, XY_FALSE, and sets error code to one of the following:

const char* XY_errstr ( void   ) 

Gets a string representing the most recent error code.

Returns:
a string containing a human-readable message describing the latest error code value.

void XY_print_options ( FILE *  fi,
XY_options  opts 
)

Dumps options in opts to the file stream (eg, stderr or an opened logfile).

Parameters:
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.

Parameters:
buffer is a pointer to memory containing image file data.
size is the size of the image file data.
Returns:
an XY_bitmap pointer on success, or NULL on failure and set error code to one of the following:

void XY_free_bitmap ( XY_bitmap bitmap  ) 

Free a bitmap.

Parameters:
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.

Parameters:
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.
Returns:
On success: XY_TRUE. On failure, XY_FALSE, and sets error code to one of the following:
Todo:
Support repeating backgrounds
Todo:
Support color overlays
Todo:
Support scaling bitmaps, relative to canvas

void XY_enable_background ( XY_bool  enable  ) 

Enable or disable the background bitmap (affects next frame).

Parameters:
enable set to XY_TRUE enables background bitmap (if any), and XY_FALSE disables it.

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.

Parameters:
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).


Generated on Tue Sep 2 23:45:36 2008 for libcrtxy by  doxygen 1.5.5