Reference
*********

aa_attrs
========

     #include <aalib.h>

     char *aa_attrs(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

The attribute output buffer is simple array of characters specifying the attributes. The array is organizated in the aa_scrheight (a) rows of aa_scrwidth(a) characters.

Return value
============

Pointer the text output buffer used by AA-lib.

aa_autoinitkbd
==============

     #include <aalib.h>

     int aa_autoinitkbd
     (
         struct aa_context *context,
         int mode
     );

Parameters
==========

     struct aa_context *context
          Specifies the AA-lib context to operate on.

     int mode
          Mask of extra features you request. Can contain AA_SENDRELEASE if you are interested in release events too.

Description
===========

Attempts to find available keyboard driver supporting the specified mode.  First attempts to initialize the recommended drivers and then in order drivers available in the aa_kbddrivers array (all regular output drivers compiled into AA-lib).

Every AA-lib program ought to have call to aa_parseoptions before first call to aa_init.

Return value
============

1 when succesfull or 0 on failure.

aa_autoinitmouse
================

     #include <aalib.h>

     int aa_autoinitmouse
     (
         struct aa_context *c,
         int mode
     );

Parameters
==========

     struct aa_context *c
          Specifies the AA-lib context to operate on.

     int mode
          Mask of extra features you request.  No such features are available in the current AA-lib version.

Description
===========

Attempts to find available mouse driver supporting the specified mode.  First attempts to initialize the recommended drivers and then in order drivers available in the aa_kbddrivers array (all regular output drivers compiled into AA-lib).

Return value
============

1 when succesfull or 0 on failure.

aa_autoinit
===========

     #include <aalib.h>

     aa_context *aa_autoinit(const struct aa_hardware_params *params);

Parameters
==========

     const struct aa_hardware_params *params
          Hardware parameters you want.  Use aa_defparams for default values.

Description
===========

Attempts to find available output driver supporting the specified parameters.  First attempts to initialize the recommended drivers and then in order drivers available in the aa_drivers array (all regular output drivers compiled into AA-lib).

Return value
============

Pointer to initialized context structure when succesfull or NULL on failure.

aa_close
========

     #include <aalib.h>

     void aa_close(aa_context *c);

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

Description
===========

Uninitialize all activated drivers and frees the memory used by context structures.

aa_createedit
=============

     #include <aalib.h>

     struct aa_edit *aa_createedit
     (
         aa_context *c,
         int x,
         int y,
         int size,
         char *s,
         int maxsize
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate of the edited text.

     int y
          Y coordinate of the edited text.

     int size
          Length of the editor window.

     char *s
          Buffer to edit (containing default value).

     int maxsize
          Size of the buffer.

Description
===========

You might use this function to input strings in AA-lib programs. This function initializes the aa_edit structure used by event-based editor. You might then call the aa_editkey function when key is pressed.

Return value
============

Pointer to edit context when succesfull and NULL on failure.

aa_currentfont
==============

     #include <aalib.h>

     const struct aa_font *aa_currentfont(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns specification of the fonts used by AA-lib rendering routines.

aa_defparams
============

     #include <aalib.h>

     extern struct aa_hardware_params aa_defparams;

Description
===========

Pa Default hardware paramters requested by AA-lib programs. Passed to aa_init function familly.

aa_defrenderparams
==================

     #include <aalib.h>

     extern struct aa_renderparams aa_defrenderparams;

Description
===========

Default rendering parameters. Passed to aa_render function familly.

aa_displayrecommended
=====================

     #include <aalib.h>

     extern aa_linkedlist *aa_displayrecommended;

Description
===========

List of recommended drivers is used by aa_autoinit familly of functions and altered by aa_recommend familly of functions.

aa_dithernames
==============

     #include <aalib.h>

     extern const char *const aa_dithernames[];

Description
===========

NULL terminated array containing the names of supported dithering methods as ascii strings.

aa_drivers
==========

     #include <aalib.h>

     extern const struct aa_driver *const aa_drivers[];

Description
===========

NULL-terminated array of output drivers available in AA-lib.

aa_editkey
==========

     #include <aalib.h>

     void aa_editkey
     (
         struct aa_edit *e,
         int c
     );

Parameters
==========

     struct aa_edit *e
          Editor context to use (see aa_createedit).

     int c
          Key pressed.

Description
===========

Notify the line editor about keypress.

aa_edit
=======

     #include <aalib.h>

     void aa_edit
     (
         aa_context *c,
         int x,
         int y,
         int size,
         char *s,
         int maxsize
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate of the edited text.

     int y
          Y coordinate of the edited text.

     int size
          Length of the editor window.

     char *s
          Buffer to edit (containing default value).

     int maxsize
          Size of the buffer.

Description
===========

This function produces the simple interactive line editor that can be used by AA-lib programs to input strings.

aa_fastrender
=============

     #include <aalib.h>

     void aa_fastrender
     (
         aa_context *c,
         int x1,
         int y1,
         int x2,
         int y2
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x1
          Column of top left coner of rendered area (in characters!).

     int y1
          Row of top left coner of rendered area.

     int x2
          Column of bottom right coner of rendered area.

     int y2
          Row of bottom right coner of rendered area.

Description
===========

This function does the trick of converting the emulated framebuffer into high quality ASCII-art. It is slightly faster and less flexible the aa_render function.

Note that to see the effect you need to call aa_flush too.

First call to this function may take a while, because the rendering tables are produced.

aa_fonts
========

     #include <aalib.h>

     extern const struct aa_font *aa_fonts[];

Description
===========

Null-terminated array of available fonts.

aa_formats
==========

     #include <aalib.h>

     extern const struct aa_format *const aa_formats[];

Description
===========

NULL terminated array of save formats supported by AA-lib.

aa_getevent
===========

     #include <aalib.h>

     int aa_getevent
     (
         aa_context *c,
         int wait
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int wait
          1 if you wish to wait for the even when queue is empty.

Description
===========

Return next event from queue. Return next even from queue. Optionally wait for even when queue is empty.

Return value
============

Next event from queue (values lower than 256 are used to report ascii values of pressed keys and higher values have special meanings) See the AA-lib texinfo documentation for more details. 0 is returned when queue is empty and wait is set to 0.

aa_getkey
=========

     #include <aalib.h>

     int aa_getkey
     (
         aa_context *c,
         int wait
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int wait
          1 if you wish to wait for the even when queue is empty.

Description
===========

Return next keypress event from queue.

Return value
============

Next keypress event from queue (values lower than 256 are used to report ascii values of pressed keys and higher values are used to represent some special keys like arrows) See the AA-lib texinfo documentation for more details.

aa_getmouse
===========

     #include <aalib.h>

     void aa_getmouse
     (
         aa_context *c,
         int *x,
         int *y,
         int *b
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int *x
          Used to return X coordinate of mouse in characters.

     int *y
          Used to return Y coordinate of mouse in characters.

     int *b
          Used to return button mask of mouse. (Values used are AA_BUTTON1, AA_BUTTON2 and AA_BUTTON3).

Description
===========

Get mouse position as specified by last mouse event read by aa_getevent.

aa_gotoxy
=========

     #include <aalib.h>

     void aa_gotoxy
     (
         aa_context *c,
         int x,
         int y
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate of new position.

     int y
          Y coordinate of the position.

Description
===========

Move the hardware cursor (if any) to specified position. To see the effect you need to call aa_flush too.

aa_help
=======

     #include <aalib.h>

     extern const char *const aa_help;

Description
===========

AA-lib help string for the default command line parser.

aa_hidecursor
=============

     #include <aalib.h>

     void aa_hidecursor(aa_context *c);

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

Description
===========

Hide the hardware cursor. This function may be ignored by some drivers.

aa_hidemouse
============

     #include <aalib.h>

     void aa_hidemouse(aa_context *c);

Parameters
==========

     aa_context *c
          Not Documented.

Description
===========

Hide the mouse cursor. This function may be ignored by some drivers.

aa_image
========

     #include <aalib.h>

     char *aa_image(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

The framebuffer is simple array of characters specifying the brightness value (or palette index depending on the aa_render call). The array is organizated in the aa_imgheight (a) rows of aa_imgwidth(a) characters.

Return value
============

Pointer to framebuffer emulated by AA-lib.

aa_imgheight
============

     #include <aalib.h>

     int aa_imgheight(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns height of the emulated image in pixels.

aa_imgwidth
===========

     #include <aalib.h>

     int aa_imgwidth(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns width of the emulated image in pixels.

aa_initkbd
==========

     #include <aalib.h>

     int aa_initkbd
     (
         struct aa_context *context,
         const struct aa_kbddriver *drv,
         int mode
     );

Parameters
==========

     struct aa_context *context
          Specifies the AA-lib context to operate on.

     const struct aa_kbddriver *drv
          Driver you wish to use.

     int mode
          Mask of extra features you request. Can contain AA_SENDRELEASE if you are interested in release events too.

Description
===========

This is the most primitive AA-lib keyboard initialization function. Allows better control over the process than the easier to use aa_autoinitkbd function.

Return value
============

1 on success and 0 on fail.

aa_initmouse
============

     #include <aalib.h>

     int aa_initmouse
     (
         struct aa_context *c,
         const struct aa_mousedriver *d,
         int mode
     );

Parameters
==========

     struct aa_context *c
          Specifies the AA-lib context to operate on.

     const struct aa_mousedriver *d
          Driver you wish to use.

     int mode
          Mask of extra features you request.  No such features are available in the current AA-lib version.

Description
===========

This is the most primitive AA-lib keyboard initialization function. Allows better control over the process than the easier to use aa_autoinitmouse function.

Return value
============

1 on success and 0 on fail.

aa_init
=======

     #include <aalib.h>

     aa_context *aa_init
     (
         const struct aa_driver *driver,
         const struct aa_hardware_params *defparams,
         const void *driverdata
     );

Parameters
==========

     const struct aa_driver *driver
          Driver you want to use.  Available drivers are listed in the NULL terminated aa_drivers array.

     const struct aa_hardware_params *defparams
          Hardware parameters you want.  Use aa_defparams for default values.

     const void *driverdata
          This pointer is passed dirrectly to driver used to specify additional driver dependent parameters.

Description
===========

This is the most primitive AA-lib initialization function. Allows better control over the process than the easier to use aa_autoinit function.

Every AA-lib program ought to have call to aa_parseoptions before first call to aa_init.

Return value
============

Pointer to new AA-lib context or NULL if failed.

aa_kbddrivers
=============

     #include <aalib.h>

     extern const struct aa_kbddriver *const aa_kbddrivers[];

Description
===========

NULL-terminated array of keyboard drivers available in AA_lib.

aa_kbdrecommended
=================

     #include <aalib.h>

     extern aa_linkedlist *aa_kbdrecommended;

Description
===========

List of recommended drivers is used by aa_autoinit familly of functions and altered by aa_recommend familly of functions.

aa_mmheight
===========

     #include <aalib.h>

     int aa_mmheight(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns height of the output screen in millimeters.

aa_mmwidth
==========

     #include <aalib.h>

     int aa_mmwidth(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns width of the output screen in millimeters.

aa_mousedrivers
===============

     #include <aalib.h>

     extern const struct aa_mousedriver *const aa_mousedrivers[];

Description
===========

NULL terminated array of mouse drivers supported by AA-lib.

aa_mouserecommended
===================

     #include <aalib.h>

     extern aa_linkedlist *aa_mouserecommended;

Description
===========

List of recommended drivers is used by aa_autoinit familly of functions and altered by aa_recommend familly of functions.

aa_parseoptions
===============

     #include <aalib.h>

     int aa_parseoptions
     (
         struct aa_hardware_params *p,
         aa_renderparams *r,
         int *argc,
         char **argv
     );

Parameters
==========

     struct aa_hardware_params *p
          Hardware parameters structure to alter. It is expected that this structure only with necessary modifications will be later used to initialize the AA-lib context.

     aa_renderparams *r
          Rendering prameters structure to alter. It is expected that this structure only with necessary modifications will be later used to render images.

     int *argc
          Pointer to argc parameter passed to function "main".

     char **argv
          Pointer to argv parameter passed to function "main".

Description
===========

Use this function to parse the standard command line options used by AA-lib. Every AA-lib program ought to call this function to let user specify some extra parameters.  The function alters the aa_hardware_params and aa_renderparams structures and removes known options from the argc/argv lists. It also parse the AAOPTS environment variable. When called with NULL for the argc/argv parameters, it parses AAOPTS only. At least this call ought to be in every AA-lib program.

Return value
============

1 when sucesfull and 0 on failure. The program then can print the help text available in aa_help variable.

aa_printf
=========

     #include <aalib.h>

     int aa_printf
     (
         aa_context *c,
         int x,
         int y,
         enum aa_attribute attr,
         const char *fmt,
         ...
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate of the first character.

     int y
          Y coordinate of the first character.

     enum aa_attribute attr
          Attribute to use.

          Possible values for an enum aa_attribute are as follows:

               AA_NORMAL
                    Normal characters.

               AA_DIM
                    Dark characters.

               AA_BOLD
                    Bright characters.

               AA_BOLDFONT
                    Characters rendered in bold font.

               AA_REVERSE
                    Reversed (black on whilte) characters.

               AA_SPECIAL
                    Render characters in a way easilly visible on the screen.  The exact rendering is driver dependent, but this mode ought to be used to output texts you want to make easilly visible in the image.

     const char *fmt
          Text to output in standard printf format.

     ...
          Not Documented.

Description
===========

Print given text to AA-lib output buffers.  To see the effect you need to call aa_flush too.

aa_putpixel
===========

     #include <aalib.h>

     void aa_putpixel
     (
         aa_context *c,
         int x,
         int y,
         int color
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate.

     int y
          Y coordinate.

     int color
          Palette index or brightness value (0..255).

Description
===========

Put pixel to emulated framebuffer.

aa_puts
=======

     #include <aalib.h>

     void aa_puts
     (
         aa_context *c,
         int x,
         int y,
         enum aa_attribute attr,
         const char *s
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int x
          X coordinate of the first character.

     int y
          Y coordinate of the first character.

     enum aa_attribute attr
          Attribute to use.

          Possible values for an enum aa_attribute are as follows:

               AA_NORMAL
                    Normal characters.

               AA_DIM
                    Dark characters.

               AA_BOLD
                    Bright characters.

               AA_BOLDFONT
                    Characters rendered in bold font.

               AA_REVERSE
                    Reversed (black on whilte) characters.

               AA_SPECIAL
                    Render characters in a way easilly visible on the screen.  The exact rendering is driver dependent, but this mode ought to be used to output texts you want to make easilly visible in the image.

     const char *s
          String to output.

Description
===========

Output given string to AA-lib output buffers.  To see the effect you need to call aa_flush too.

aa_recommendhidisplay
=====================

     #include <aalib.h>

     void aa_recommendhidisplay(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Insert the given driver on beggining of the list of recommended display drivers.

aa_recommendhikbd
=================

     #include <aalib.h>

     void aa_recommendhikbd(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Insert the given driver on beggining of the list of recommended keyboard drivers.

aa_recommendhimouse
===================

     #include <aalib.h>

     void aa_recommendhimouse(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Insert the given driver on beggining of the list of recommended mouse drivers.

aa_recommendhi
==============

     #include <aalib.h>

     void aa_recommendhi
     (
         aa_linkedlist **l,
         const char *name
     );

Parameters
==========

     aa_linkedlist **l
          List to operate on (aa_displayrecommended, aa_kbdrecommended or aa_mouserecommended).

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Insert the given driver on beggining of the list of recommended drivers.

aa_recommendlowdisplay
======================

     #include <aalib.h>

     void aa_recommendlowdisplay(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Add the given driver to the end of list of display recommended drivers.

aa_recommendlowkbd
==================

     #include <aalib.h>

     void aa_recommendlowkbd(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Add the given driver to the end of list of keyboard recommended drivers.

aa_recommendlowmouse
====================

     #include <aalib.h>

     void aa_recommendlowmouse(const char *name);

Parameters
==========

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Add the given driver to the end of list of mouse recommended drivers.

aa_recommendlow
===============

     #include <aalib.h>

     void aa_recommendlow
     (
         aa_linkedlist **l,
         const char *name
     );

Parameters
==========

     aa_linkedlist **l
          List to operate on (aa_displayrecommended, aa_kbdrecommended or aa_mouserecommended).

     const char *name
          Name of the driver (ought to match the "shortname" field of the driver definition structure).

Description
===========

Add the given driver to the end of list of recommended drivers.

aa_registerfont
===============

     #include <aalib.h>

     int aa_registerfont(const struct aa_font *f);

Parameters
==========

     const struct aa_font *f
          Font specification structure.

Description
===========

Add new font specification to aa_fonts array.

Return value
============

1 when succesfull or 0 on failure.

aa_render
=========

     #include <aalib.h>

     void aa_render
     (
         aa_context *c,
         const aa_renderparams *p,
         int x1,
         int y1,
         int x2,
         int y2
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     const aa_renderparams *p
          Rendering parametters used to specify brightness, gamma correction and other usefull stuff. Use aa_defrenderparams for default values.

     int x1
          Column of top left coner of rendered area (in characters!).

     int y1
          Row of top left coner of rendered area.

     int x2
          Column of bottom right coner of rendered area.

     int y2
          Row of bottom right coner of rendered area.

Description
===========

This function does the trick of converting the emulated framebuffer into high quality ASCII-art. If you want to be really fast, you might use aa_fastrender.  If you want to emulate palette, use aa_renderpalette.

Note that to see the effect you need to call aa_flush too.

First call to this function may take a while, because the rendering tables are produced.

aa_resizehandler
================

     #include <aalib.h>

     void aa_resizehandler
     (
         aa_context *c,
         void (*handler)(aa_context *)
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     void (*handler)(aa_context *)
          Function to be called when resize happends.

Description
===========

Set user handler to be called on resize event.

aa_resize
=========

     #include <aalib.h>

     int aa_resize(aa_context *c);

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

Description
===========

Do resize action. This function ought to be called when application takes into account the AA_RESIZE event.  The context is reinitialized and set to new sizes.

Return value
============

0 when no resizing is done and 1 when resizing was succesfull.

aa_scrheight
============

     #include <aalib.h>

     int aa_scrheight(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns height of the output screen in characters.

aa_scrwidth
===========

     #include <aalib.h>

     int aa_scrwidth(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

Returns width of the output screen in characters.

aa_setfont
==========

     #include <aalib.h>

     void aa_setfont
     (
         aa_context *c,
         const struct aa_font *font
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     const struct aa_font *font
          Font specification structure.

Description
===========

Set font specification to be used by rendering functions.

aa_setsupported
===============

     #include <aalib.h>

     void aa_setsupported
     (
         aa_context *c,
         int supported
     );

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

     int supported
          New mask of requested features. Can contain AA_EXTENDED to enable use of all 256 characters and AA_EIGHT to enable use of the character numbered higher than 127.

Description
===========

This function can be used to alter "supported" field of hardware-params structure used by AA-lib.

aa_showcursor
=============

     #include <aalib.h>

     void aa_showcursor(aa_context *c);

Parameters
==========

     aa_context *c
          Specifies the AA-lib context to operate on.

Description
===========

Show the hardware cursor. This function may not be ignored by some drivers.

aa_showmouse
============

     #include <aalib.h>

     void aa_showmouse(aa_context *c);

Parameters
==========

     aa_context *c
          Not Documented.

Description
===========

Show the mouse cursor. This function may be ignored by some drivers.

aa_text
=======

     #include <aalib.h>

     char *aa_text(aa_context *a);

Parameters
==========

     aa_context *a
          Specifies the AA-lib context to operate on.

Description
===========

The text output buffer is simple array of characters specifying the ascii-value of the characters. The array is organizated in the aa_scrheight (a) rows of aa_scrwidth(a) characters.

Return value
============

Pointer the text output buffer used by AA-lib.

aa_uninitkbd
============

     #include <aalib.h>

     void aa_uninitkbd(aa_context *context);

Parameters
==========

     aa_context *context
          Specifies the AA-lib context to operate on.

Description
===========

Calls "uninitialize" function of the keyboard driver. It ought to undo all actions done by "initialize" function.

aa_uninitmouse
==============

     #include <aalib.h>

     void aa_uninitmouse(aa_context *context);

Parameters
==========

     aa_context *context
          Specifies the AA-lib context to operate on.

Description
===========

Calls "uninitialize" function of the mouse driver. It ought to undo all actions done by "initialize" function.

mem_d
=====

     #include <aalib.h>

     extern const struct aa_driver mem_d;

Description
===========

Used to render ascii-art images into memory. You might use this driver to render images into memory and then use your own routines to handle them in case you want to avoid AA-lib's output mechanizms.

save_d
======

     #include <aalib.h>

     extern const struct aa_driver save_d;

Description
===========

Initialize this driver using aa_init function and specify the driver dependent parameters in aa_savedata structure to save image into file. See the texinfo documentation for details.