This reference documents the version 0.9.2-dev of the C API.
_qdgdfa_fopen().
qdgdfv_fopen().
_qdgdfa_16_bit - 16 bit sound card toggle.
int _qdgdfa_16_bit = 1;
If set to 0 previous to startup, use only 8 bit sound output. If it has a value of 0 after startup, the sound card does not support 16 bit PCM audio.
_qdgdfa_big_sound_threshold - Threshold for a sound to be considered big.
int _qdgdfa_big_sound_threshold = 1024 * 1024;
This integer holds the minimum size a sound must have to be considered a 'big' sound (a sound that is paged in disk instead of being loaded completely in memory).
_qdgdfa_fopen_path - Search path for _qdgdfa_fopen().
char _qdgdfa_fopen_path[250] = "";
This string can contain a semicolon-separated list of paths
where files to be open with _qdgdfa_fopen() will be tried.
_qdgdfa_sound - Main sound switch.
int _qdgdfa_sound = 1;
If set to 0 previous to startup, disables the whole sound system. If it has a value of 0 after startup, something wrong occurred in the initialization of the sound card.
_qdgdfa_window_title - title of the window.
char _qdgdfa_window_title[150] = "";
This string holds the title of the window.
_qdgdfv_accum_buffer - Accumulation buffer.
unsigned char *_qdgdfv_accum_buffer = NULL;
This buffer holds the last dumped virtual screen if the accumulation buffer is used, or a NULL pointer otherwise. It's rarely used directly, as the accumulation buffer is treated transparently.
_qdgdfv_additional_info - Additional string info for the driver.
char _qdgdfv_additional_info[150] = "";
This string can be filled with some information for the driver. Its content is purposely driver dependent and can contain, for example, the remote X Window display.
_qdgdfv_additional_int_info - Additional integer info for the driver.
int _qdgdfv_additional_int_info = 0;
This integer can be filled with some information for the driver. Its content is purposely driver dependent and can contain, for example, the Windows instance handler.
_qdgdfv_clear_color - The clear color.
unsigned char _qdgdfv_clear_color = 0;
This color will be used to clear the screen when using
qdgdfv_clear_virtual_screen().
_qdgdfv_double_antialias - Antialias flag for double modes.
int _qdgdfv_double_antialias = 0;
If you set this variable, double modes will be dumped using a basic antialiasing mechanism, if the video driver implements one.
_qdgdfv_double_mode - Sets the double mode.
int _qdgdfv_double_mode = 0;
The use of this variable is deprecated. Use _qdgdfv_scale instead.
_qdgdfv_font_blend - Blending percentage for font printing.
int _qdgdfv_font_blend = 100;
This variable holds the color blending percentage for the selected color when printing a string. If it's 100 (the default) the string will be 100% the specified color; lower values mixes the pixels currently on the virtual screen with that of the drawn characters.
_qdgdfv_font_height - Height of the font, in pixels.
int _qdgdfv_font_height = 16;
This variable holds the height of the currently loaded font, in pixels.
_qdgdfv_fopen_path - Search path for qdgdfv_fopen().
char _qdgdfv_fopen_path[250] = "";
This string can contain a semicolon-separated list of paths
where files to be open with qdgdfv_fopen() will be tried
before banging.
_qdgdfv_full_screen - Full screen flag.
int _qdgdfv_full_screen = -1;
When set before initialization, it expresses the preference of running full screen or not (a value of -1 means it doesn't matter). After initialization, contains what really happened.
_qdgdfv_gamma_correct - Gamma correction.
int _qdgdfv_gamma_correct = 0;
This variable containts the amount of gamma correction to be applied when colors are created. It ranges from 0 (colors as defined in the palette) to 255 (absolutely saturate).
qdgdfv_key - The key flags.
int _qdgdfv_key_up = 0;
This variables are set by qdgdfv_input_poll() accordingly to
the current keyboard status. These variables are:
_qdgdfv_key_up, _qdgdfv_key_down, _qdgdfv_key_left,
_qdgdfv_key_right, _qdgdfv_key_escape, _qdgdfv_key_space,
_qdgdfv_key_enter, _qdgdfv_key_control_l, _qdgdfv_key_control_r,
_qdgdfv_key_control, _qdgdfv_key_shift_l, _qdgdfv_key_shift_r,
_qdgdfv_key_pgup, _qdgdfv_key_pgdn, _qdgdfv_key_home, _qdgdfv_key_end
and _qdgdfv_key_f1 to f10.
_qdgdfv_logger_file - Logger file.
char _qdgdfv_logger_file[150] = "";
This string holds the path of the logger file.
_qdgdfv_scale - Sets the scale.
int _qdgdfv_scale = 0;
Sets the scale. If not set, a 1 scale (no scale) will be tried; if it's impossible to set due to hardware limitations (for example, a 320x200 resolution has been requested and current hardware don't support it, but can do 640x400), a 2 scale (double) will be tried. Some drivers allow even bigger scales.
This variable obsoletes the old _qdgdfv_double_mode.
_qdgdfv_scale2x - Scale2x algorithm flag.
int _qdgdfv_scale2x = 1;
When set, double screen dumping is done by using the scale2x algorithm (read about it at http://scale2x.sourceforge.net). It's set by default.
_qdgdfv_screen_x_size - Horizontal screen size.
unsigned int _qdgdfv_screen_x_size = 320;
This variable holds the horizontal screen size in pixels. It can be set to whatever wanted before the startup. The real horizontal screen size will be stored here after the startup (it can be a different value).
_qdgdfv_screen_y_size - Vertical screen size.
unsigned int _qdgdfv_screen_y_size = 200;
This variable holds the vertical screen size in pixels. It can be set to whatever wanted before the startup. The real vertical screen size will be stored here after the startup (it can be a different value).
_qdgdfv_use_logger - Logger use flag.
int _qdgdfv_use_logger = 1;
If this variable is set, the logger will be active.
_qdgdfv_virtual_screen - The virtual screen.
unsigned char *_qdgdfv_virtual_screen = NULL;
This variable points to a buffer of (_qdgdfv_screen_x_size *
_qdgdfv_screen_y_size) unsigned chars. All video operations are
done over this space. To dump it to the real screen, use
qdgdfv_dump_virtual_screen().
_qdgdfv_window_title - Title for the window.
char _qdgdfv_window_title[150] = "qdgdf Window";
This string holds the title for the window. Take note that some systems are fullscreen and has no window titles.
_qdgdfv_window_x - Initial x position of the window.
int _qdgdfv_window_x = 60;
This variable must be set before startup and holds the desired initial position of the window. Not all supported systems let this be set (some of them even have no window at all, just fullscreen graphics), so it's purely orientative there.
_qdgdfv_window_y - Initial y position of the window.
int _qdgdfv_window_y = 60;
This variable must be set before startup and holds the desired initial position of the window. Not all supported systems let this be set (some of them even have no window at all, just fullscreen graphics), so it's purely orientative there.
qdgdfa_app_dir - Returns the applications directory.
char *qdgdfa_app_dir(void);
Returns a system-dependent directory where the applications store their private data, as components or resources.
qdgdfa_dup_sound - Duplicates a sound.
int qdgdfa_dup_sound(int snd);
Duplicates a sound. The new sound will share the sound data with the old one. Returns the id for the new sound.
qdgdfa_home_dir - Returns the home user directory.
char *qdgdfa_home_dir(void);
Returns a system-dependent directory where the user can write documents and create subdirectories.
qdgdfa_load_big_sound - Loads a big sound (deprecated).
int qdgdfa_load_big_sound(char *wavfile);
In previous versions, sounds considered (by the programmer)
to be big were loaded by using this function, but now the
'bigness' of a file is controlled by the value in the
_qdgdfa_big_sound_threshold variable, so it's use is deprecated.
Now it's exactly equivalent to qdgdfa_load_sound().
qdgdfa_load_sound - Loads a sound.
int qdgdfa_load_sound(char *wavfile);
Loads a sound file (in .WAV format). A sound handle is returned.
qdgdfa_path_find - Finds a file in _qdgdfa_fopen_path.
char *qdgdfa_path_find(const char *file);
Searches for file in the path stored in _qdgdfa_fopen_path. If it's found in some of the directories there, a string is allocated contaning the full path, that should be freed when no longer needed. Otherwise, returns NULL.
qdgdfa_pause - Pause the sound system.
void qdgdfa_pause(int p);
Pauses the sound system. The p argument acts as a boolean to pause or unpause the sound system.
qdgdfa_play_sound - Starts playing a sound.
void qdgdfa_play_sound(int snd, int loop);
Starts playing a sound. If loop is set, the sound restarts from the beginning when reaches the end. If the sound is already playing, nothing is done.
qdgdfa_reset - Resets the sound system.
void qdgdfa_reset(void);
Resets the sound system, shuting up all sounds and unloading them from memory.
qdgdfa_respawn_sound - Respawns a sound.
void qdgdfa_respawn_sound(int snd);
Respawns a sound, playing it even if the sound is already playing. This new, duplicated sound inherits all properties (as pan, etc.) from the original one and cannot be stopped nor controlled in any way. The poll of respawned sounds is limited; if it can't hold more sounds, nothing is done. A respawned sound is automatically deleted when finished.
qdgdfa_set_attenuation - Sets the attenuation of a sound.
void qdgdfa_set_attenuation(int snd, int att);
Sets the attenuation of a sound. It ranges from 0 (no attenuation, sound is as is) to 63 (total silence).
qdgdfa_set_pan - Sets the pan of a sound.
void qdgdfa_set_pan(int snd, int pan);
Sets the pan of a sound. The pan argument can be -1 (left channel only), 0 (both channels, center) or 1 (right channel only).
qdgdfa_shutdown - Shuts down the sound system.
void qdgdfa_shutdown(void);
Shuts down the sound system.
qdgdfa_startup - Starts the sound system.
void qdgdfa_startup(void);
Starts the sound system. If _qdgdfa_sound is not set, no action is done. If _qdgdfa_16_bit is set, it tries to use the 16 bit capabilities of the sound card. It also sets both previous variables accordingly to the current configuration.
qdgdfa_stop_sound - Stop playing a sound.
void qdgdfa_stop_sound(int snd);
Stops playing a sound.
qdgdfv_app_dir - Returns the applications directory.
char *qdgdfv_app_dir(void);
Returns a system-dependent directory where the applications store their private data, as components or resources.
qdgdfv_assert_in_virtual_screen - Asserts that a pointer is inside the virtual screen.
void qdgdfv_assert_in_virtual_screen(char *func, unsigned char *ptr);
Asserts that a pointer falls inside the virtual screen. If it's outside (less than _qdgdfv_virtual_screen or further the end of the virtual screen), aborts.
qdgdfv_bang - Bangs on unrecoverable problems.
void qdgdfv_bang(char *where, char *msg);
Logs the message to the logger and returns to the system.
qdgdfv_blend_color - Blends two colors into one.
unsigned char qdgdfv_blend_color(unsigned char c1, unsigned char c2, int percent);
Blends two colors into the nearest matching one. If percent is 100, the returned color will be c1, if it's 0, c2, or a blending between both otherwise.
qdgdfv_build_light_table - Builds a light table.
void qdgdfv_build_light_table(unsigned char *lut, int levels, int mid);
Builds a light table. The lut argument must have enough size to store (256 * levels) bytes, and be easily accessed (so it can wisely be defined as unsigned char lut[levels][256]). The mid value is the level where color is 100% (i.e. equal to the color itself). Below, colors fade to black and above colors saturate to white.
qdgdfv_build_light_table_ext - Builds a light table (extended).
void qdgdfv_build_light_table_ext(unsigned char *lut, int levels, int mid, int fr, int fg, int fb);
This function is an extended version of qdgdfv_build_light_table().
Instead of fading to black, this function allows to specify what
color the dark light levels fade to.
qdgdfv_clear_virtual_screen - Clears the virtual screen.
void qdgdfv_clear_virtual_screen(void);
Clears the virtual screen, using _qdgdfv_clear_color.
qdgdfv_dump_virtual_screen - Dumps the virtual screen.
void qdgdfv_dump_virtual_screen(void);
Dumps the virtual screen into the real one.
qdgdfv_extended_key_status - Returns more status about a key.
int qdgdfv_extended_key_status(int *key_var);
Returns extended status for the variable pointed by key_var. Returned values are: 0, key not pressed; 1, key just pressed; 2, key pressed; 3, key just released; -1, no information about the key is found.
qdgdfv_font_print - Prints a string on the virtual screen.
void qdgdfv_font_print(int x, int y, unsigned char * string, unsigned char color);
Prints the string on the virtual screen in the specified coordinates. x and y are in pixels. If x is -1, the string is centered; if is -2, the string is right aligned. If y is negative, it starts counting from below.
qdgdfv_font_size - Returns the size of a string, in pixels.
int qdgdfv_font_size(char * string);
Returns the size of the string in pixels.
qdgdfv_fopen - 'Secure' open.
FILE *qdgdfv_fopen(char *file, char *mode);
Opens a file, banging if could not be opened. Optional search paths can be defined in _qdgdfv_fopen_path. Returns the opened file.
qdgdfv_home_dir - Returns the home user directory.
char *qdgdfv_home_dir(void);
Returns a system-dependent directory where the user can write documents and create subdirectories.
qdgdfv_input_poll - Polls the input system.
void qdgdfv_input_poll(void);
Polls the input system, setting the individual key variables accordingly.
qdgdfv_load_ktl_font - Loads a KTL font.
void qdgdfv_load_ktl_font(char * fontfile);
Loads a KTL font and sets it as the current font. The KTL fonts are monospaced (8 bit wide) fonts from the Kaplan Graphical Environment. They are used in Space Plumber as well. If fontfile is NULL, an internal font (the default one) is activated.
qdgdfv_load_palette - Loads an external palette.
void qdgdfv_load_palette(char *palette_file);
Loads an external palette. The file is a text one having
lines with three decimal values from 0 to 255 for the red,
green and blue parts of each color, respectively. To be used,
qdgdfv_set_palette() must be called afterwards.
qdgdfv_load_pcx - Loads a graphic in PCX format.
void qdgdfv_load_pcx(unsigned char *pcx, char *pcxfile, int size);
Loads a graphic into the supplied pcx buffer. The file must be in 256 color PCX format. The palette included inside the file is not used.
qdgdfv_load_pcx_pal - Loads a graphic in PCX format using its palette.
void qdgdfv_load_pcx_pal(unsigned char *pcx, char *pcxfile, int size);
This function does the same as qdgdfv_load_pcx(), but taking into
account the palette information stored inside the file to match
the current palette.
qdgdfv_load_pcx_pal_set - Loads a graphic in PCX format setting its palette.
void qdgdfv_load_pcx_pal_set(unsigned char *pcx, char *pcxfile, int size);
This function does the same as qdgdfv_load_pcx(), but setting the palette
store inside the file as the default.
qdgdfv_logger - Logs a message.
void qdgdfv_logger(char *where, char *msg);
Logs the message to the logger file, usually an error.
qdgdfv_malloc - 'Secure' malloc.
void *qdgdfv_malloc(int size);
Tries to alloc the desired memory size and, if not succesful, bangs out to the system. This make unnecesary to test if the block could be allocated. Returns the allocated block.
qdgdfv_path_find - Finds a file in _qdgdfv_fopen_path.
char *qdgdfv_path_find(const char *file);
Searches for file in the path stored in _qdgdfv_fopen_path. If it's found in some of the directories there, a string is allocated contaning the full path, that should be freed when no longer needed. Otherwise, returns NULL.
qdgdfv_seek_color - Searches for the nearest matching color.
unsigned char qdgdfv_seek_color(int r, int g, int b);
Searches the internal palette for the nearest color matching the r, g and b values. This values must range from 0 to 255. Returns the selected color.
qdgdfv_set_accum_buffer - Sets or resets the accumulation buffer.
void qdgdfv_set_accum_buffer(int percent);
If percent is set to a non zero value (the default), the contents of the previous frame is blended with the actual one with the specified percent.
qdgdfv_set_palette - Sets the palette.
void qdgdfv_set_palette(void);
Sets the stored palette as the current one, probably loading it into video hardware.
qdgdfv_shutdown - Shuts down the video system.
void qdgdfv_shutdown(void);
Shuts down the video system.
qdgdfv_sprintf - Static sprintf.
char *qdgdfv_sprintf(char *fmt, ...);
Formats a string, using sprintf. A static buffer is returned.
qdgdfv_startup - Inits the video system.
void qdgdfv_startup(void);
Starts up the video system.
qdgdfv_timer - Returns the elapsed time in microseconds.
int qdgdfv_timer(int reset);
Returns the elapsed time between calls, in milliseconds. If reset is set to 1, the timer is reset any time the function is called, or accumulative otherwise. It's mainly used for calculating the elapsed time per frame. It's wise to reset the timer just before entering the main loop.