Un naufragio personal

Ángel Ortega

QDGDF API

This reference documents the version 0.9.2-dev of the C API.

By Category

Audio Functions

Audio Variables

File Management

Font Functions

Font Variables

Keyboard Functions

Keyboard Variables

Support Functions

Support Variables

Video Functions

Video Variables

By Source

qdgdf_audio.c

qdgdf_video.c

qdgdf_video_font.c

Alphabetical

_qdgdfa_16_bit

Name

_qdgdfa_16_bit - 16 bit sound card toggle.

Synopsis

 int _qdgdfa_16_bit = 1;

Description

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.

Categories

_qdgdfa_big_sound_threshold

Name

_qdgdfa_big_sound_threshold - Threshold for a sound to be considered big.

Synopsis

 int _qdgdfa_big_sound_threshold = 1024 * 1024;

Description

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

Categories

_qdgdfa_fopen_path

Name

_qdgdfa_fopen_path - Search path for _qdgdfa_fopen().

Synopsis

 char _qdgdfa_fopen_path[250] = "";

Description

This string can contain a semicolon-separated list of paths where files to be open with _qdgdfa_fopen() will be tried.

Categories

_qdgdfa_sound

Name

_qdgdfa_sound - Main sound switch.

Synopsis

 int _qdgdfa_sound = 1;

Description

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.

Categories

_qdgdfa_window_title

Name

_qdgdfa_window_title - title of the window.

Synopsis

 char _qdgdfa_window_title[150] = "";

Description

This string holds the title of the window.

Categories

_qdgdfv_accum_buffer

Name

_qdgdfv_accum_buffer - Accumulation buffer.

Synopsis

 unsigned char *_qdgdfv_accum_buffer = NULL;

Description

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.

Categories

_qdgdfv_additional_info

Name

_qdgdfv_additional_info - Additional string info for the driver.

Synopsis

 char _qdgdfv_additional_info[150] = "";

Description

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.

Categories

_qdgdfv_additional_int_info

Name

_qdgdfv_additional_int_info - Additional integer info for the driver.

Synopsis

 int _qdgdfv_additional_int_info = 0;

Description

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.

Categories

_qdgdfv_clear_color

Name

_qdgdfv_clear_color - The clear color.

Synopsis

 unsigned char _qdgdfv_clear_color = 0;

Description

This color will be used to clear the screen when using qdgdfv_clear_virtual_screen().

Categories

_qdgdfv_double_antialias

Name

_qdgdfv_double_antialias - Antialias flag for double modes.

Synopsis

 int _qdgdfv_double_antialias = 0;

Description

If you set this variable, double modes will be dumped using a basic antialiasing mechanism, if the video driver implements one.

Categories

_qdgdfv_double_mode

Name

_qdgdfv_double_mode - Sets the double mode.

Synopsis

 int _qdgdfv_double_mode = 0;

Description

The use of this variable is deprecated. Use _qdgdfv_scale instead.

Categories

_qdgdfv_font_blend

Name

_qdgdfv_font_blend - Blending percentage for font printing.

Synopsis

 int _qdgdfv_font_blend = 100;

Description

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.

Categories

_qdgdfv_font_height

Name

_qdgdfv_font_height - Height of the font, in pixels.

Synopsis

 int _qdgdfv_font_height = 16;

Description

This variable holds the height of the currently loaded font, in pixels.

Categories

_qdgdfv_fopen_path

Name

_qdgdfv_fopen_path - Search path for qdgdfv_fopen().

Synopsis

 char _qdgdfv_fopen_path[250] = "";

Description

This string can contain a semicolon-separated list of paths where files to be open with qdgdfv_fopen() will be tried before banging.

Categories

_qdgdfv_full_screen

Name

_qdgdfv_full_screen - Full screen flag.

Synopsis

 int _qdgdfv_full_screen = -1;

Description

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

Name

_qdgdfv_gamma_correct - Gamma correction.

Synopsis

 int _qdgdfv_gamma_correct = 0;

Description

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

Name

qdgdfv_key - The key flags.

Synopsis

 int _qdgdfv_key_up = 0;

Description

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.

Categories

_qdgdfv_logger_file

Name

_qdgdfv_logger_file - Logger file.

Synopsis

 char _qdgdfv_logger_file[150] = "";

Description

This string holds the path of the logger file.

Categories

_qdgdfv_scale

Name

_qdgdfv_scale - Sets the scale.

Synopsis

 int _qdgdfv_scale = 0;

Description

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.

Categories

_qdgdfv_scale2x

Name

_qdgdfv_scale2x - Scale2x algorithm flag.

Synopsis

 int _qdgdfv_scale2x = 1;

Description

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.

Categories

_qdgdfv_screen_x_size

Name

_qdgdfv_screen_x_size - Horizontal screen size.

Synopsis

 unsigned int _qdgdfv_screen_x_size = 320;

Description

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

Categories

_qdgdfv_screen_y_size

Name

_qdgdfv_screen_y_size - Vertical screen size.

Synopsis

 unsigned int _qdgdfv_screen_y_size = 200;

Description

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

Categories

_qdgdfv_use_logger

Name

_qdgdfv_use_logger - Logger use flag.

Synopsis

 int _qdgdfv_use_logger = 1;

Description

If this variable is set, the logger will be active.

Categories

_qdgdfv_virtual_screen

Name

_qdgdfv_virtual_screen - The virtual screen.

Synopsis

 unsigned char *_qdgdfv_virtual_screen = NULL;

Description

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

Categories

_qdgdfv_window_title

Name

_qdgdfv_window_title - Title for the window.

Synopsis

 char _qdgdfv_window_title[150] = "qdgdf Window";

Description

This string holds the title for the window. Take note that some systems are fullscreen and has no window titles.

Categories

_qdgdfv_window_x

Name

_qdgdfv_window_x - Initial x position of the window.

Synopsis

 int _qdgdfv_window_x = 60;

Description

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.

Categories

_qdgdfv_window_y

Name

_qdgdfv_window_y - Initial y position of the window.

Synopsis

 int _qdgdfv_window_y = 60;

Description

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.

Categories

qdgdfa_app_dir

Name

qdgdfa_app_dir - Returns the applications directory.

Synopsis

 char *qdgdfa_app_dir(void);

Description

Returns a system-dependent directory where the applications store their private data, as components or resources.

Categories

qdgdfa_dup_sound

Name

qdgdfa_dup_sound - Duplicates a sound.

Synopsis

 int qdgdfa_dup_sound(int snd);

Arguments

sound
the sound to be duplicated

Description

Duplicates a sound. The new sound will share the sound data with the old one. Returns the id for the new sound.

Categories

qdgdfa_home_dir

Name

qdgdfa_home_dir - Returns the home user directory.

Synopsis

 char *qdgdfa_home_dir(void);

Description

Returns a system-dependent directory where the user can write documents and create subdirectories.

Categories

qdgdfa_load_big_sound

Name

qdgdfa_load_big_sound - Loads a big sound (deprecated).

Synopsis

 int qdgdfa_load_big_sound(char *wavfile);

Arguments

wavfile
the file containing the sound

Description

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

Categories

qdgdfa_load_sound

Name

qdgdfa_load_sound - Loads a sound.

Synopsis

 int qdgdfa_load_sound(char *wavfile);

Arguments

wavfile
the file containing the sound

Description

Loads a sound file (in .WAV format). A sound handle is returned.

Categories

qdgdfa_path_find

Name

qdgdfa_path_find - Finds a file in _qdgdfa_fopen_path.

Synopsis

 char *qdgdfa_path_find(const char *file);

Arguments

file
the file to be found

Description

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

Name

qdgdfa_pause - Pause the sound system.

Synopsis

 void qdgdfa_pause(int p);

Arguments

p
toggle flag

Description

Pauses the sound system. The p argument acts as a boolean to pause or unpause the sound system.

Categories

qdgdfa_play_sound

Name

qdgdfa_play_sound - Starts playing a sound.

Synopsis

 void qdgdfa_play_sound(int snd, int loop);

Arguments

snd
the sound handle
loop
neverending loop flag

Description

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.

Categories

qdgdfa_reset

Name

qdgdfa_reset - Resets the sound system.

Synopsis

 void qdgdfa_reset(void);

Description

Resets the sound system, shuting up all sounds and unloading them from memory.

Categories

qdgdfa_respawn_sound

Name

qdgdfa_respawn_sound - Respawns a sound.

Synopsis

 void qdgdfa_respawn_sound(int snd);

Arguments

snd
the sound to be respawn

Description

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.

Categories

qdgdfa_set_attenuation

Name

qdgdfa_set_attenuation - Sets the attenuation of a sound.

Synopsis

 void qdgdfa_set_attenuation(int snd, int att);

Arguments

snd
the sound handle
att
the attenuation

Description

Sets the attenuation of a sound. It ranges from 0 (no attenuation, sound is as is) to 63 (total silence).

Categories

qdgdfa_set_pan

Name

qdgdfa_set_pan - Sets the pan of a sound.

Synopsis

 void qdgdfa_set_pan(int snd, int pan);

Arguments

snd
the sound handle
pan
pan of the sound

Description

Sets the pan of a sound. The pan argument can be -1 (left channel only), 0 (both channels, center) or 1 (right channel only).

Categories

qdgdfa_shutdown

Name

qdgdfa_shutdown - Shuts down the sound system.

Synopsis

 void qdgdfa_shutdown(void);

Description

Shuts down the sound system.

Categories

qdgdfa_startup

Name

qdgdfa_startup - Starts the sound system.

Synopsis

 void qdgdfa_startup(void);

Description

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.

Categories

qdgdfa_stop_sound

Name

qdgdfa_stop_sound - Stop playing a sound.

Synopsis

 void qdgdfa_stop_sound(int snd);

Arguments

snd
the sound handle

Description

Stops playing a sound.

Categories

qdgdfv_app_dir

Name

qdgdfv_app_dir - Returns the applications directory.

Synopsis

 char *qdgdfv_app_dir(void);

Description

Returns a system-dependent directory where the applications store their private data, as components or resources.

Categories

qdgdfv_assert_in_virtual_screen

Name

qdgdfv_assert_in_virtual_screen - Asserts that a pointer is inside the virtual screen.

Synopsis

 void qdgdfv_assert_in_virtual_screen(char *func, unsigned char *ptr);

Arguments

func
function where the test is happening
ptr
the pointer

Description

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

Name

qdgdfv_bang - Bangs on unrecoverable problems.

Synopsis

 void qdgdfv_bang(char *where, char *msg);

Arguments

where
caller function name
msg
message

Description

Logs the message to the logger and returns to the system.

Categories

qdgdfv_blend_color

Name

qdgdfv_blend_color - Blends two colors into one.

Synopsis

 unsigned char qdgdfv_blend_color(unsigned char c1, unsigned char c2, int percent);

Arguments

c1
first color
c2
second color
percent
percentage of blending

Description

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.

Categories

qdgdfv_build_light_table

Name

qdgdfv_build_light_table - Builds a light table.

Synopsis

 void qdgdfv_build_light_table(unsigned char *lut, int levels, int mid);

Arguments

lut
the buffer where to store the light table
levels
number of light levels
mid
the level where color is 100%

Description

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.

Categories

qdgdfv_build_light_table_ext

Name

qdgdfv_build_light_table_ext - Builds a light table (extended).

Synopsis

 void qdgdfv_build_light_table_ext(unsigned char *lut, int levels,
				  int mid, int fr, int fg, int fb);

Arguments

lut
the buffer where to store the light table
levels
number of light levels
mid
the level where color is 100%
fr
red component of fade color
fg
green component of fade color
fb
blue component of fade color

Description

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.

Categories

qdgdfv_clear_virtual_screen

Name

qdgdfv_clear_virtual_screen - Clears the virtual screen.

Synopsis

 void qdgdfv_clear_virtual_screen(void);

Description

Clears the virtual screen, using _qdgdfv_clear_color.

Categories

qdgdfv_dump_virtual_screen

Name

qdgdfv_dump_virtual_screen - Dumps the virtual screen.

Synopsis

 void qdgdfv_dump_virtual_screen(void);

Description

Dumps the virtual screen into the real one.

Categories

qdgdfv_extended_key_status

Name

qdgdfv_extended_key_status - Returns more status about a key.

Synopsis

 int qdgdfv_extended_key_status(int *key_var);

Arguments

key_var
pointer to the wanted key variable (_qdgdfv_key_up, etc.)

Description

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.

Categories

qdgdfv_font_print

Name

qdgdfv_font_print - Prints a string on the virtual screen.

Synopsis

 void qdgdfv_font_print(int x, int y, unsigned char * string, unsigned char color);

Arguments

x
x position
y
y position
string
string to be written
color
text color

Description

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.

Categories

qdgdfv_font_size

Name

qdgdfv_font_size - Returns the size of a string, in pixels.

Synopsis

 int qdgdfv_font_size(char * string);

Arguments

string
the string to be measured

Description

Returns the size of the string in pixels.

Categories

qdgdfv_fopen

Name

qdgdfv_fopen - 'Secure' open.

Synopsis

 FILE *qdgdfv_fopen(char *file, char *mode);

Arguments

file
file to be opened
mode
mode for the file

Description

Opens a file, banging if could not be opened. Optional search paths can be defined in _qdgdfv_fopen_path. Returns the opened file.

Categories

qdgdfv_home_dir

Name

qdgdfv_home_dir - Returns the home user directory.

Synopsis

 char *qdgdfv_home_dir(void);

Description

Returns a system-dependent directory where the user can write documents and create subdirectories.

Categories

qdgdfv_input_poll

Name

qdgdfv_input_poll - Polls the input system.

Synopsis

 void qdgdfv_input_poll(void);

Description

Polls the input system, setting the individual key variables accordingly.

Categories

qdgdfv_load_ktl_font

Name

qdgdfv_load_ktl_font - Loads a KTL font.

Synopsis

 void qdgdfv_load_ktl_font(char * fontfile);

Arguments

fontfile
the file containing the font

Description

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.

Categories

qdgdfv_load_palette

Name

qdgdfv_load_palette - Loads an external palette.

Synopsis

 void qdgdfv_load_palette(char *palette_file);

Arguments

palette_file
the file containing the palette

Description

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.

Categories

qdgdfv_load_pcx

Name

qdgdfv_load_pcx - Loads a graphic in PCX format.

Synopsis

 void qdgdfv_load_pcx(unsigned char *pcx, char *pcxfile, int size);

Arguments

pcx
the buffer where the graphic will be stored
pcxfile
the file containing the graphic
size
the size in bytes of the graphic data

Description

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.

Categories

qdgdfv_load_pcx_pal

Name

qdgdfv_load_pcx_pal - Loads a graphic in PCX format using its palette.

Synopsis

 void qdgdfv_load_pcx_pal(unsigned char *pcx, char *pcxfile, int size);

Arguments

pcx
the buffer where the graphic will be stored
pcxfile
the file containing the graphic
size
the size in bytes of the graphic data

Description

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.

Categories

qdgdfv_load_pcx_pal_set

Name

qdgdfv_load_pcx_pal_set - Loads a graphic in PCX format setting its palette.

Synopsis

 void qdgdfv_load_pcx_pal_set(unsigned char *pcx, char *pcxfile, int size);

Arguments

pcx
the buffer where the graphic will be stored
pcxfile
the file containing the graphic
size
the size in bytes of the graphic data

Description

This function does the same as qdgdfv_load_pcx(), but setting the palette store inside the file as the default.

Categories

qdgdfv_logger

Name

qdgdfv_logger - Logs a message.

Synopsis

 void qdgdfv_logger(char *where, char *msg);

Arguments

where
caller function name
msg
message

Description

Logs the message to the logger file, usually an error.

Categories

qdgdfv_malloc

Name

qdgdfv_malloc - 'Secure' malloc.

Synopsis

 void *qdgdfv_malloc(int size);

Arguments

size
the size of the block to malloc

Description

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.

Categories

qdgdfv_path_find

Name

qdgdfv_path_find - Finds a file in _qdgdfv_fopen_path.

Synopsis

 char *qdgdfv_path_find(const char *file);

Arguments

file
the file to be found

Description

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

Name

qdgdfv_seek_color - Searches for the nearest matching color.

Synopsis

 unsigned char qdgdfv_seek_color(int r, int g, int b);

Arguments

r
the red part of the color
g
the green part of the color
b
the blue part of the color

Description

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.

Categories

qdgdfv_set_accum_buffer

Name

qdgdfv_set_accum_buffer - Sets or resets the accumulation buffer.

Synopsis

 void qdgdfv_set_accum_buffer(int percent);

Arguments

percent
percentage of buffer lasting

Description

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.

Categories

qdgdfv_set_palette

Name

qdgdfv_set_palette - Sets the palette.

Synopsis

 void qdgdfv_set_palette(void);

Description

Sets the stored palette as the current one, probably loading it into video hardware.

Categories

qdgdfv_shutdown

Name

qdgdfv_shutdown - Shuts down the video system.

Synopsis

 void qdgdfv_shutdown(void);

Description

Shuts down the video system.

Categories

qdgdfv_sprintf

Name

qdgdfv_sprintf - Static sprintf.

Synopsis

 char *qdgdfv_sprintf(char *fmt, ...);

Arguments

fmt
the format string

Description

Formats a string, using sprintf. A static buffer is returned.

Categories

qdgdfv_startup

Name

qdgdfv_startup - Inits the video system.

Synopsis

 void qdgdfv_startup(void);

Description

Starts up the video system.

Categories

qdgdfv_timer

Name

qdgdfv_timer - Returns the elapsed time in microseconds.

Synopsis

 int qdgdfv_timer(int reset);

Arguments

reset
reset flag

Description

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.

Categories

Angel Ortega - angel@triptico.com - Built with mp_doccer 1.2.2-dev