Loading and setting options for rendering quality.

Data Structures
struct	XY_options
	Structure containing libcrtxy options (rendering level, screen size, etc. More...
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.
Defines
#define	XY_INIT_LIB_CONFIG_FILE_GLOBAL   CONFDIR "/libcrtxy.conf"
	Where system-wide (global) config file lives.
#define	XY_INIT_LIB_CONFIG_FILE_LOCAL   ".libcrtxyrc"
	Where user's (local) config file lives.
Enumerations
enum	XY_opt_fullscreen {   XY_OPT_WINDOWED,   XY_OPT_FULLSCREEN_REQUEST,   XY_OPT_FULLSCREEN_REQUIRED }
	Display settings for options.fullscreen. More...
enum	XY_opt_alpha {   XY_OPT_ALPHA_BLEND,   XY_OPT_ALPHA_FAKE,   XY_OPT_ALPHA_OFF }
	Alpha-blending settings for options.alpha. More...
enum	XY_opt_scaling {   XY_OPT_SCALE_BEST,   XY_OPT_SCALE_FAST }
	Bitmap scaling quality settings for options.scaling. More...

---

Define Documentation

#define XY_INIT_LIB_CONFIG_FILE_GLOBAL   CONFDIR "/libcrtxy.conf"

Where system-wide (global) config file lives.

Todo:

Make config locations configurable at build (FIXME)

#define XY_INIT_LIB_CONFIG_FILE_LOCAL   ".libcrtxyrc"

Where user's (local) config file lives.

Todo:

Make config locations configurable at build (FIXME)

---

Enumeration Type Documentation

enum XY_opt_fullscreen

Display settings for options.fullscreen.

Enumerator:

XY_OPT_WINDOWED	Display in a window.
XY_OPT_FULLSCREEN_REQUEST	Fullscreen; fall back to window.
XY_OPT_FULLSCREEN_REQUIRED	Fullscreen; abort if we cannot.

enum XY_opt_alpha

Alpha-blending settings for options.alpha.

Enumerator:

XY_OPT_ALPHA_BLEND	Combine current pixel with new pixel.
XY_OPT_ALPHA_FAKE	Combine background color with new pixel.
XY_OPT_ALPHA_OFF	Just draw new pixel.

enum XY_opt_scaling

Bitmap scaling quality settings for options.scaling.

Enumerator:

XY_OPT_SCALE_BEST	Blend to smooth any stretching.
XY_OPT_SCALE_FAST	Stretch pixels with no blending.

---

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_ERR_MEM_CANT_ALLOC
• XY_ERR_OPTION_BAD
• XY_ERR_OPTION_UNKNOWN

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:

• XY_ERR_FILE_CANT_OPEN
• XY_ERR_MEM_CANT_ALLOC
• XY_ERR_OPTION_BAD
• XY_ERR_OPTION_UNKNOWN

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_ERR_OPTION_BAD
• XY_ERR_OPTION_UNKNOWN

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:

• XY_ERR_OPTION_BAD