This is aalib.info, produced by makeinfo version 4.8 from aalib.texinfo.

INFO-DIR-SECTION Libraries
START-INFO-DIR-ENTRY
* AA-lib: (aalib).              An ASCII-art graphics library
END-INFO-DIR-ENTRY

   (C) 1997 Jan Hubicka & Kamil Toman

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.


File: aalib.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

AA-lib 1.4
**********

                                                   An ascii-art library
                                                        API DESCRIPTION
                                                           Apr 17, 2001

* Menu:

* Overview::		What does this software do then ?
* AA-Project::		You want join ?
* Skeleton::		AA-lib program skeleton::
* Initialization::	How to start up AA-lib?
* Drawing image::	How to draw image?
* Rendering::		Rendering of image into ascii-art
* Flushing::		Flushing into screen and text output functions
* Keyboard::		Handling keyboard
* Mouse::		Handling mouse
* Resizing::		Resizing of display
* Other functions::	Functions that was not documented yet.
* Designing new driver::How to port AA-lib to new platform
* Reference::		All AA-lib functions and variables.
* Index::		Index of functions, types, macros and constants



                              .,.  _.    .
                           .%qwmy1(/.  .
                         _x]WWWK1==s,<aaa,=  .
                    .  ,jwdWWW#oa=%+{3WBW#oa>_,-
                    `.amWWWWWZ13x|:=|{?W#Ee==++=_
                   _jmWBWWWB}l=:;:.<%|!??+;- ~.;==,
                 _ud$WWWW#Xecc_|=-::<3{~ .  . .. ;::_
                ++|>{?+X*bSx%>`=: ..-<:-. .  .   -:==i,
              ....:`---+|+{S=..-=:...= `       .....-<?;.
               -. . ...__=:--..  - . ..      .  . :-<=>|:.
                   ..  .--  . ..::;:=:+.  . . .._--;<nx>=:
                 .        .:;==|=|=|||:: .......:<,=.=:+==.
                     .. .::==|||iilxil|;::_=:+::=<(-+==.  -
                    .: .:;==+|<illvivnxs==<:~=. --:.. . ..
                     . .::==|+|iilIvvnnns|..:=.  .  .  :... .   .
                       .:;=+||ixxxnvxnnnon> ;)s         .--`__,:-
                       -:==|+|xoS2oo22ooX2Xa,.^x.    i.     -~~
                  .   .::;===+|I12SSnnSXSXmX#s, +,.  -`
                  .. --  . ----+++|||II}**!!!!|> '....,  .,.
                 .::.. .        ..-:===::.    :=%i<j#me. ][
                 .-::.- . .   ..  .:xwmo(._ ` s,:|3WmQk;.d
             :.  ..:;;::....... ...=3m#Bm%~=<3UWBWWWWW#.)h
             :=.  :;;:;:;;::.......=X#WWWWQmmmmBWWWWWWF`jf
              -= .:;==;;;;:::::....=dmWWWBmWWWWWWWWWWW[jQ[
                 ..:;;:::;;=::....;)X#WWWm>3XWWWWWWWW#??
                  ...:-:::::... . .:+*Y?YXo=|3XWWWWBW[
                  .....:...........:.=nZmWms;=IX#####
                  .............:-~+1s%X#####2s<nXZ##P
                   .....:.. . .  .___=aaa_a_%<2Z####`
                 __;...............-+inXZBm#ZoZm#m#s_,   - .
        _   .%uoon=.  ...:-:.:.--;<xaudmZmWmmm###mmBQQQmw..|=__
     /?'.....XXSnx..........:::::=ln#WWmWWWWW#XXWWWWWWWWe.|==|:iT
     ...c    )Xon>...... ........:+*1SX####XSommWWWWWWW[.+=:=:s%=
     QQQWL..  -{1;...:.-..  . .......--+<ixnS#mWWWWWWY`:=+:;=mWWQ
     WWWWWb.. . -:....:.:...... ......:|%nXZm#WWWWW?=::=;;:<mWWWW
     ^-- . . .    ......-.... .... .:=ixnXX##mWBE?-:-:::::|>=i+==
     . . .  . .      . .......... -:=+lxSXXZ#Z?`.:::::.:==::===;=
      . . .. . ..       . . .    ...:=|lvn}!...:.....:==<|:<|saaw
     QWQWQQWQWm#Qwa_,      .. .... .:;~~ .......:=sawwWWWWWQWWWWW

                   Honza Hubicka <hubicka@freesoft.cz>


                          _a,an}|^-=-:._._
                       .aJ#XS*||:::--::;=>=|_.
                    ._JZSo1|+:;;:::.:.:=||===:..
                   _=nn31}=,==:..::.:::__=====;...
                  .=+"!+i%*+==::-:;=<;==+<+==..
                 .. .__|+~_;>`. . ..:===|:==-; .
                   .--~-~~...-- ..:.;::+====>==_ .
                       .. : .  ....-+|;-:=<i=::,_.
                      . .        ..==|l|==+:;|=i:.       .
                              . ..-:+|>+li===|!+:...     :.
                            .  ...:::i||iixi|==;=|_._.. ..;
                          . ...:.==|ixxunnns%iiaoouis%,=:==
                         . ....:==iiv22XXXZZ#ZmZXXXdupoz=<>
                      ........::=|ilvn2S2ZZ#####ZZZXZ#Xx=u>.
                    . . . . .-:;=iill11X2X#m###mmZXzIl>{`I`;
                     ... ..-::;=|||illvv3XXXXXX#XmoS;==::-..
                    .   . ...=====|i|||+"""~~++*1SoXs,-::...
                          ......---===;.  ..:=|i>"{2S( ;_</|
                                 .:::=;=     ,.--+`"`=%)d#(;
             . .    . .           ...;i>....--+._=us_J1s.+s;
              -.  .. . .  .       :{m, =|::::==xxoXzXonX(:x(
              ...  ` ..... . .   .:xZXc`|||=||ln2ZX'Snvc<oS(
              ..  . `........  . .={SXXb/~|i|iixn}\non1XXXr
               ..  .    .    .   .;{2ZXS21,____%xonnnxiSX'
                    . ........   .:<v**X1IIxoo2nnonvvx=
                      . . .. . .   :Isxunos%lxnonn1vvl;
                       . .  . .  ....InSoonIixnxvnvIl>
                      .   . .  ..:l=.innnn1xIiixnIIIl'
                         .           . _.:.-|linxvl|`
                            .      -~-++iii|iivvl|||
                               . ....__|ixxxIvIi=|Il
                            . . .::=|i%nnonnvI+=v1nl
                                ...:=|Innn1}+||vvnvv;
                                  ....:+++=xivvnnnno> .
                                     .:;=ivvnnvvno2o` .   ..
                ..:        .          :=+|iIxvnvo2e';,. ...:<+:.
            ...--             .      ..==iivlvIn1".|=:;.. . . -::
        .::.                        ...=|iliIli~ =|`:<:/.. .. .
     n;:  .                       .   .::=|+~       :=+;;:.: :

     	      Kamil Toman <toman@artax.karlin.mff.cuni.cz>


File: aalib.info,  Node: Overview,  Next: AA-Project,  Prev: Top,  Up: Top

1 Overview
**********

* Menu:

* Why?::		Why such library?
* What?::		What does this software do then?
* History::		How this all started?


File: aalib.info,  Node: Why?,  Next: What?,  Prev: Overview,  Up: Overview

1.1 Why such library?
=====================

I vote for simplicity. There are many problems of various kinds with
video cards, low frequency monitors, crashing graphical apps... AA-lib
IS the solution. It works on a terminal of any kind, it is fast and
portable, it gives to you standard API. It gives to your old hardware
more power!


File: aalib.info,  Node: What?,  Next: History,  Prev: Why?,  Up: Overview

1.2 What does this software do then ?
=====================================

AA-lib is a low level gfx library just as many other libraries are. The
main difference is that AA-lib does not require graphics device. In
fact, there is no graphical output possible. AA-lib replaces those
old-fashioned output methods with powerful ascii-art renderer. Now my
linux boots with a nice penguin logo at secondary display (yes! Like
Win95 does:) AA-lib API is designed to be similar to other graphics
libraries. Learning a new API would be a piece of cake!


File: aalib.info,  Node: History,  Prev: What?,  Up: Overview

1.3 How this all started
========================

Once upon a time we've (my friend Kamil and I) bought two old Herculeses
as secondary monitors. We didn't know for that time that our Diamond
Stealths 64 cards would become obsolete soon. The next day we downloaded
the logo of Linux Texas Users Group - nice silly penguin looking like a
cowboy! It was so exciting logo ... we decided that we couldn't live
without it and we wanted to see it at boot time as a logo on our
secondary monitors. There was a small problem - Hercules doesn't
support color graphics. So we decided to convert the penguin image to
ascii art using netpbm tools.

   The output was very ugly because the converting algorithm was
absolutly stupid.  During the night I designed a new convertor that
used a font bitmap to create an aproximation table. The output wasn't
very good since the algorithm wasn't tuned so well. Many months this
small piece of code was waiting on my disc for the day "D". Meanwhile I
started a new project XaoS (a fractal zoomer) with my friend Thomas.
And then I got an idea: Ascii Art Mandelbrots!  I was really impressed
by the result! XaoS was faster, portable and looking much better than
ever before. I found a new way to go ...


File: aalib.info,  Node: AA-Project,  Next: Skeleton,  Prev: Overview,  Up: Top

2 AA-Project
************

                               dT8  8Tb
                              dT 8  8 Tb
                             dT  8  8  Tb
                          <PROJECT><PROJECT>
                           dT    8  8    Tb
                          dT     8  8     Tb

Three goals of AA-Project:

  1. Port all important software (like Doom, Second Reality, X windows
     etc..)  on AA-lib.

  2. Port AA-lib on all available platforms (mainly ZX-Spectrum and
     Sharp).

  3. Force IBM to start manufacturing MDA cards again.

   AA-project was started by Jan Hubicka. In that times just a few
people knew about it. Then a new demo named BB has been relased to show
the power of AA-lib technology. Now the project is freely available and
anyone can help.

   Just join our mailing list:
`aa-project-discuss@lists.sourceforge.net'.

   Or just browse our homepage at `http://aa-project.sourceforge.net'.
A ton of examples of ascii-art generated by aalib, pointers to other
AA-Project resources etc.


File: aalib.info,  Node: Skeleton,  Next: Initialization,  Prev: AA-Project,  Up: Top

3 AA-lib program skeleton
*************************

Following piece of code you may want to use as base for your future
AA-lib program:

     #include <aalib.h>
     int
     main (int argc, char **argv)
     {
       aa_context *context;       /* The information about currently
       				initialized device.  */
       aa_palette palette;        /* Emulatted palette (optional) */

       char *framebuffer;

       /* Parse command line options and output the help text.  */
       if (!aa_parseoptions (NULL, NULL, &argc, argv) || argc != 1)
         {
           printf ("%s", aa_help);
           exit (1);
         }

       /* Initialize output driver.  */
       context = aa_autoinit (&aa_defparams);
       if (context == NULL)
         {
           printf ("Failed to initialize aalib\n");
           exit (1);
         }

       /* Pointer to the emulated videoram.  */
       framebuffer = aa_image (context);


       /* Create palette if needed: */
       for (i = 0; i < 256; i++)
         aa_setpalette (palette, i, /* R value 0..255 */ ,
                                    /* G value 0..255 */ ,
                                    /* B value 0..255 */ );

       /* Draw something using: */
       aa_putpixel (context, /* X coord */ , /* Y coord */ , /* Color */ );

       /* Render whole screen: */

       aa_renderpalette (context, palette, aa_defrenderparams,
     		    /* Top left conner of rendered area: */ 0, 0,
     		    /* Bottom right */  aa_scrwidth (context), aa_scrheight (context));

       /* If you don't use palette use following function:
       aa_render (context, aa_defrenderparams,
                  0, 0, aa_scrwidth (context), aa_scrheight (context));
       */

       /* And make it visible: */
       aa_flush (context);

       /* And uninitialize the AA_lib (this probably makes the picture invisible
          again) */
       aa_close (context);

       return 1;
     }


File: aalib.info,  Node: Initialization,  Next: Drawing image,  Prev: Skeleton,  Up: Top

4 Initialization
****************

It is possible to initialize AA-lib in various modes.  The main
initialization is done by following `aa_init'

     aa_context *aa_init(struct aa_driver *DRIVER,
                         struct aa_hardware_params *DEFPARAMS,
                         void *DRIVERDATA)

   This function prepares `aa_context *' type variable used by all
AA-lib functions. The DRIVER parameter specifies hardware driver to
initialize, DEFPARAMS parameters of hardware you require and DRIVERDATA
is used to pass implementation dependent extra information to the
hardware driver.

   To undo all actions done by `aa_init' function, call `aa_close':

     aa_close(aa_context *CONTEXT)

   This function frees allocated memory for `aa_context' and call's
unintialize function of the output drivers.

   Initializing AA-lib directly is non-trivial task. Many display
drivers and modes are available. Several helper functions are provided
to do this job for you.

   You may want initialize AA-lib in one of the following modes:

* Menu:

* Initialization as a normal graphics library::
* Initialization as an ascii art renderer::
* Initialization for image saving::
* Specifying hardware parameters::


File: aalib.info,  Node: Initialization as a normal graphics library,  Next: Initialization as an ascii art renderer,  Prev: Initialization,  Up: Initialization

4.1 Initialization as normal graphics library
=============================================

If you initialize AA-lib as a normal graphics library you can use one
of available hardware drivers. It initializes a display device and sets
the output to the screen. Hardware drivers depend on a platform you are
running at, configuration of your computer and many other things.
Typically more than one driver is available. AA-lib can make the
decision for you if you use `aa_autoinit' function:

     aa_context *aa_autoinit(struct aa_hardware_params *PARAMS)

   This function initializes the hardware driver and returns
`aa_context' structure used by other functions.  `NULL' is returned on
failure.  Parameter PARAMS is used to specify hardware parameters you
require.

* Menu:

* Easy initialization of AA-lib::
* Parsing of command line options::
* How does the autodetection work::
* Recommending drivers::


File: aalib.info,  Node: Easy initialization of AA-lib,  Next: Parsing of command line options,  Prev: Initialization as a normal graphics library,  Up: Initialization as a normal graphics library

4.1.1 Easy initialization of AA-lib
-----------------------------------

Following example is the most trivial way to initialize AA-lib.

     #include <stdio.h>
     #include <aalib.h>
     aa_context *context;
     void main(void)
     {
       aa_parseoptions (NULL, NULL, NULL, NULL);

           /* Every AA-lib program ought to call the aa_perseoptions at least
              in this way to make the AAOPTS environment variable work.  */

       context = aa_autoinit(&aa_defparams);
       if(context == NULL) {
         fprintf(stderr,"Cannot initialize AA-lib. Sorry\n");
         exit(1);
       }
       ...
       aa_close(context);
     }

   This code will do all autodetection/initialization stuff for you and
it will fire up AA-lib (using default parameters). Because AA-lib
supports output driver using ordinarry stdio functions, the failure is
very unlikely, but you ought to check it.


File: aalib.info,  Node: Parsing of command line options,  Next: How does the autodetection work,  Prev: Easy initialization of AA-lib,  Up: Initialization as a normal graphics library

4.1.2 Parsing of command line options
-------------------------------------

AA-lib works at many different output devices so it can be initialized
with many different options. Somebody might want to change the defaults.
This can be done using command line options.  This is done using
function `aa_parseoptions' that uses `argc/argv' variables and parses
options for AA-lib. The options for AA-lib are removed during parsing
from `argc/argv' so call to aa_parseoptions can preceede the normal
command line options parsing code done by your program.  `aa_help'
variable contains help about options parsed by `aa_parseoptions'.

     int aa_parseoptions(aa_hardwareparams *P,
                         aa_renderparams *R,
                         int *ARGC, char **ARGV);

   First parameter is used for AA-lib initialization. It specifies the
hardware parameters you require and is altered by `aa_parseoptions'. It
is expected that your program will define his prefered parameters
first, call `aa_parseoptions' and then alter it only when necessary to
make program working correctly. If you don't brother about the hardware
specification, you may use `aa_defparams' variable in both places (here
and as passed to `aa_init' function familly).  You may also pass NULL
to use defaults (aa_defparams variable).

   The second argument is set of parameters for rendering. It works in
similar way as the first parameters. Both of this variables will be
explained later. Use NULL to force defaults (aa_defrenderparams).
Fuction returns: `1' if OK or `0' on error.

   The function returns 1 on sucess and 0 on failure.

     #include <stdio.h>
     #include <aalib.h>
     aa_context *context;
     void main(int argc, char **argv)
     {
       if(!aa_parseoptions(NULL, NULL, &argc, argv) || argc!=1) {
         printf("Usage: %s [options]\n"
                "Options:\n"
                "%s", argv[0], aa_help);
         exit(1);
       }
       context = aa_autoinit(&aa_defparams);
       if(context == NULL) {
         fprintf(stderr,"Cannot initialize AA-lib. Sorry\n");
         exit(2);
       }
       ...
       aa_close(context);
     }

   Note that options are parsed from command line and also from
`AAOPTS' enviroment variable. This makes possible to set parameters for
all AA-Lib programs. If you pass `NULL' as `argc/argv' only the
enviroment variable is parsed.

   Variable `aa_help' contains help string similiar to this one:
       -driver        select driver
                       available drivers:linux slang X11
       -kbddriver     select keyboard driver
                       available drivers:slang X11
       -kbddriver     select mouse driver
                       available drivers:X11 gpm
     Size options:
       -width         set width
       -height        set height
       -minwidth      set minimal width
       -minheight     set minimal height
       -maxwidth      set maximal width
       -maxheight     set maximal height
       -recwidth      set recomended width
       -recheight     set recomended height
     Attributes:
       -dim           enable usage of dim (half bright) attribute
       -bold          enable usage of bold (double bright) attribute
       -reverse       enable usage of reverse attribute
       -normal        enable usage of normal attribute
       -boldfont      enable usage of boldfont attrubute
       -no<attr>      disable (i.e -nobold)

     Font rendering options:
       -extended      use all 256 characters
       -eight         use eight bit ascii
       -font <font>   select font(This option have effect just on hardwares
                      where aalib is unable to determine current font
                       available fonts:vga8 vga9 mda14 vga14 X8x13 X8x16
                       X8x13bold vgagl8 line

     Rendering options:
       -inverse       enable inverse rendering
       -noinverse     disable inverse rendering
       -bright <val>  set bright (0-255)
       -contrast <val>set contrast (0-255)
       -gamma <val>   set gamma correction value(0-1)

     Ditherng options:
       -nodither      disable dithering
       -floyd_steinberg floyd steinberg dithering
       -error_distribution error distribution dithering
       -random <val>  set random dithering value(0-inf)


File: aalib.info,  Node: How does the autodetection work,  Next: Recommending drivers,  Prev: Parsing of command line options,  Up: Initialization as a normal graphics library

4.1.3 How does the autodetection work
-------------------------------------

To fully understand customizing of `aa_autoinit' you have to know (at
least something) how does the autodetection work.

   All hardware drivers are stored in `aa_drivers' array -- array of
pointers to drivers terminated by `NULL' pointer. Order is significant.
First driver is tested before the second etc.

   It is possible to customize your own order of drivers. This can be
done using `aa_displayrecomended' list. It's a double linked list of
strings that are interpreted as names of drivers. These drivers are
tested before `aa_drivers' is procesed. There are several reasons to do
it this way.  Firstly, this "aditional" list is passed before the first
of "standard array" drivers is used. Thus you can recommend the probing
order of drivers in a very natural and comfortable way.  Second, this
method reduces executable file size.  Third, you can prefer different
drivers on different platforms with no aditional care about current
configuration of AA-lib.


File: aalib.info,  Node: Recommending drivers,  Prev: How does the autodetection work,  Up: Initialization as a normal graphics library

4.1.4 Recommending drivers
--------------------------

Manipulation with recomended drivers (`aa_displayrecomended' list) can
be done using macros:

     aa_recomendhidisplay(NAME)
     aa_recomendlowdisplay(NAME)

   `aa_displayrecomended' is a cyclic list. You can easily add drivers
to the begining (using `aa_recomendhidisplay(name)') or to the end
using `aa_recomendlowdisplay(name)'.  In other words
`aa_recomendhidisplay' inserts with "high priority".  (at the beggining
of the list). The check for duplicity is performed.  Despite
`aa_recomendhidisplay(name)', that moves an existing display to the
begining, function `aa_recomendlowdisplay(name)' inserts to the end.
Thus nothing can lower the required priority of your driver.

   This two priorities are usefull in many situations. For example:
many display drivers recomend keyboard or mouse drivers (it's a good
idea use `curses' keyboard when `curses' display driver is used). But
some users may want to change it -- for example they might want to
drive an aplication from a script and they might want to use `stdin'
keyboard driver instead of `X11' recomended by `X11' driver.

   The following piece of code:

     aa_recomendhidisplay ("testa1");
     aa_recomendlowdisplay("teste1");
     aa_recomendhidisplay ("testa2");
     aa_recomendlowdisplay("teste2");
     aa_recomendlowdisplay("teste1");
     aa_recomendhidisplay ("teste1");

   will produce the following list:

     teste1, testa2, testa1, teste1 teste2

   And autoprobing will first test in order all drivers on the lists
(if such drivers exist in current AA-lib configuration) and then try
all available drivers in the default order.


File: aalib.info,  Node: Initialization as an ascii art renderer,  Next: Initialization for image saving,  Prev: Initialization as a normal graphics library,  Up: Initialization

4.2 Initialization as an ascii art renderer
===========================================

If you want to use just AA-lib's rendering routines but no output to
screen (eg. you have your own output routines) you can use dummy memory
driver.  It's named `mem_d' and it's initialization should look like
this:

      context = aa_init(MEM_D,&AA_DEFPARAMS,NULL);


File: aalib.info,  Node: Initialization for image saving,  Next: Specifying hardware parameters,  Prev: Initialization as an ascii art renderer,  Up: Initialization

4.3 Initialization for image saving
===================================

AA-Lib also have a driver specialized for image saving. It's name is
`save_d'(currently only driver that uses `aa_savedata' structure):

     struct aa_savedata {
           char *name;
           struct aa_format *format;
           FILE *file;
     };

   Field `name' contains a filename (without extension).  If you wish
to specify file descriptor, you might want to use field `file' instead.
Set `name' to `NULL' in this cases.  Note that then file will not be
closed automatically. In `name' you should use following tags:
`%x'
     X coordinate of page, if pages enabled otherwise none

`%y'
     Y coordinate of page, if pages enabled otherwise none

`%c'
     Coordinates in format: `_%x_%y', if pages enabled otherwise none

`%e'
     Default extension (like `.html')
   `Format' is a pointer to `aa_format' structure (format information):

     struct aa_format {
           int width, height;        /*default width/height*/
           int pagewidth, pageheight;/*in case output is made from pages*/
           int flags;                /*should be made from:
                                       AA_USE_PAGES
                                       AA_NORMAL_SPACES
                                     */
           int supported;            /*mask of supported attributes*/
           struct aa_font *font;     /*font used by hardware device*/
           char *formatname;	        /*name of format*/
           char *extension;          /*file extension*/
           char *head;               /*text at the beggining of file*/
           char *end;                /*text at the end of file*/
           char *newline;            /*text at the end of line*/
           char *prints[AA_NATTRS];  /*printf seqence for printing character*/
           char *begin[AA_NATTRS];   /*text printed at the beggining of block
                                       of character at gived attribute*/
           char *ends[AA_NATTRS];    /*text printed at the end of block*/
           char **conversions	/*conversion tabe*/
     };

   Conversions is array of strings in format: character, replacement,
terminated by `NULL'.

   Following code is an example of `HTML' format description:

     static char *html_escapes[] = {"<", "&lt;", ">", "&gt;", "&", "&amp;", NULL};

     struct aa_format aa_html_format =
     {
           79, 25,
           0, 0,
           0,
           AA_NORMAL_MASK | AA_BOLD_MASK | AA_BOLDFONT_MASK,
           NULL,
           "Pure html",
           ".html",
           "<HTML>\n <HEAD> <TITLE>Ascii arted image
            done using aalib</TITLE>\n</HEAD>\n<BODY><PRE>\n",
           "</PRE></BODY>\n</HTML>\n",
           "\n",
           /*The order is:normal, dim, bold, boldfont, reverse, special*/
           { "%s", "%s", "%s", "%s", "%s", },
           {"", "", "<B>", "", "<B>" },
           {"", "", "</B>", "", "</B>" },
           html_escapes
     };
   
   Usually you don't need to worry about filling in this large
structure since the formats are already defined: `aa_nhtml_format',
`aa_html_format', `aa_html_alt_format', `aa_ansi_format',
`aa_text_format', `aa_more_format', `aa_hp_format', `aa_hp2_format',
`aa_zephyr_format', `aa_irc_format'.  All formats are collected in
`aa_formats' array. It is array of pointers to `aa_format' terminated
by `NULL'

   All additional new formats are welcomed.


File: aalib.info,  Node: Specifying hardware parameters,  Prev: Initialization for image saving,  Up: Initialization

4.4 Specifying hardware parameters
==================================

In previous examples we used `aa_defparams' without description. This
variable says to AA-lib what hardware do you expect.

     struct aa_hardware_params {
           struct aa_font *font;
           int supported;
           int minwidth, minheight;
           int maxwidth, maxheight;
           int recwidth, recheight;
           int mmwidth, mmheight;
           int width, height;
     };

   Filed `font' contains the default font. If your driver is unable to
autodetect the font used by the output device (such as terminal drivers
or most of saving drivers), you may want to select one of the fonts
compiled into aalib.  Following fonts are available: `font8', `font14',
`font16', `font9', `fontline', `fontgl', `fontX13', `fontX16',
`fontX13B'.  If you specify `NULL' as an argument `font16' is used.

   Integer `supported' contains a mask. Following masks are available: `AA_NORMAL_MASK',
`AA_DIM_MASK', `AA_BOLD_MASK', `AA_BOLDFONT_MASK', `AA_REVERSE_MASK'.

   You can use `AA_EXTENDED' to enable all 256 of characters or
`AA_EIGHT' to enable using of characters numbered higher than 127. This
should be set also after the initialization using `aa_setsupported'

   Other fields are used to specify the display size. If your program
requires a fixed size of the display you should set `width',`height'
fields (otherwise expect problems ;).  You can also adjust how tolerant
AA-lib should be. Minimum is set by `minwidth/minheight', maximum is
set by `maxwidth/maxheight'.  Then you can set `width/height'
parameters and call the init function.  The nearest value (in specified
bounds `coz) will be set.

   If all these fields are set to zero (default) hardware drivers
prompt user for the size and memory/save drivers will set some
defaults. Hardware drivers also have default values(forced by enter).
If you wanted to modify them you'd have to set `recwidth/recheight'.
Note that `minwidth/minheight' and `maxwidth/maxheight' still have an
effect even if `width/height' is zero.

   It is recomended to set all the parameters that can be alternated by
user just before `aa_parseoptions' is called, so options can't be
changed.

   `mmwidth/mmheight' should be used to specify size of window in
milimeters (but it is ignored by all drivers now ;).


File: aalib.info,  Node: Drawing image,  Next: Rendering,  Prev: Initialization,  Up: Top

5 How to draw an image?
***********************

AA-lib emulates video-ram so it looks just like a plain memory. It
contains `aa_imgheight (context)' lines of `aa_imgwidth(context)' bytes
where each of them specifies a grayscale value or an index to a colormap
(or graymap ?).  Pointer to this memory can be obtained using
`aa_image(context)' macro.

   Note that width and height of videoram differ from physical
width/height of a device (stored in `aa_hardwareparams' variables).
Currently it is twice bigger because every four pixels are rendered
into one character.  Future versions should (possibly) support nine
pixels.

   There's nearly no difference in API between classical gfx libraries
and AA-lib.  There are currently no higher level graphics functions.
But AA-lib provides `aa_putpixel(context,x,y,color)' macro. There is no
problem to make more complex functions. A great help to a potential
programmer is the fact that AA-lib provides a colormap mode emulation.
To set the palette you should use macro:

     aa_setpalette(PALETTE, INDEX, RED, GREEN, BLUE)

   Red, green and blue components are recalculated into super-grayscale.
Values are in range 0-255 where 0 means black. You can also set
directly value using something like:

     palette[index]=value;

   Another difference is that your aplication is expected to handle
various imgwidth/imgheights (in case you didn't exacly specified them in
hardwareparams during initialization). Also your aplication should take
care for `aa_mmwidth(context)' and `aa_mmheight(context)' values that
contain real size in millimeters of output device. You cannot simply
expect that pixel has the same width and height as at normal graphics
libraries.

   Many old programs may require some scalling functions to convert
images from their internal size (320x200) to AA-Lib real size.

   Note that image WON'T be displayed on the screen unless it is
rendered and FLUSHED !


File: aalib.info,  Node: Rendering,  Next: Flushing,  Prev: Drawing image,  Up: Top

6 Rendering of image into ascii-art
***********************************

Once image is drawn it needs to be rendered. For this purpose three
functions are provided:

     void aa_fastrender(aa_context *C, int X1, int Y1, int X2, int Y2);
     void aa_render(aa_context * C, aa_renderparams *P,
                           int X1, int Y1, int X2, int Y2);
     void aa_renderpalette(aa_context *C, aa_palette TABLE,
                           aa_renderparams *P,
                           int X1, int Y1, int X2, int Y2);

   `x1', `y1', `x2', `y2' parameters specify Top left/bottom right
corner of rendered rectangle. Note that these coordinates are SCREEN
not IMAGE ones. So they can be twice smaller !!  Specify the range
0...`aa_scrwidth(context)' or 0...`aa_scrheight(context)').  Please do
NOT confuse them with image coords otherwise you'll get strange results!
Note that the first call of our rendering function can take
significantly more time becouse it pre-computes internal look-up tables.

   Function `aa_fastrender' does very fast (but not as perfect)
results. It is designed for aplications that prefers simplicity and
speed to the quality of output.  Quick and easy way to use render
routines is to call:

     aa_fastrender(context, 0, 0, aa_scrwidth(context), aa_scrheight(context));

   Function `aa_render' is a bit more complex than the previous one.
It uses 256 colors instead of 16 ones and it has an extra parameter `p'.
This parameter allows a control of its advanced features. It's a pointer
to the following structure:

     struct aa_renderparams {
         int bright, contrast;
         float gamma;
         int dither;
         int inversion;
         int randomval;
     };

   Values `bright', `contrast', `gamma' let you control the quality of
the output image. Brightness of range 0...255 and contrast 0...127;
dither can be set to one of the following values:
`AA_NONE'
     disables dithering

`AA_ERROR_DISTRIB'
     enables error distribution dithering

`AA_FLOYD_S'
     enables floyd-steinberg dithering

   Inversion enables/disables the inversion. Randomval can be used to
control the random dithering. If randomval is non-zero a random value
in range ( -randomval / 2 , ranomval / 2) is added to every pixel value
before the rendering.  Note that this can be combined with all other
ditherings too.

   Function `aa_renderpalette' is similiar to `aa_render'. The only
difference is that it lets you specify the palette.


File: aalib.info,  Node: Flushing,  Next: Keyboard,  Prev: Rendering,  Up: Top

7 Flushing into screen and text output functions
************************************************

We've written the whole charapter for small functions to get your
attention.  None of them without flusing the image into screen will
work. Once AA-lib is started, image drawn and rendered it needs to be
finally displayed on the screen.  Yes! That's it! You have to flush the
data (or you'll get a blank screen:).

     void aa_flush(aa_context *C);

   This function will update the screen due to the situation stored in
text and attribute buffers. This buffers are filled by rendering but
they may be also accesed directly. A pointer to them can be obtained by
calling `aa_text(context)' or `aa_attrs(context)' macros.

   The `aa_text' returns pointer to array representing text output
buffer.  An "videroram-like" array represented in the same way as
`aa_image' (with the screen, not image dimenstions) where each byte is
ascii value of character to display.

   The `aa_attrs' return pointer to array representing additional
attribute for each character.  Attribute buffer can contain following
values:
`AA_NORMAL'
     for normal characters

`AA_BOLD'
     for bold (double bright) characters

`AA_DIM'
     for dim (half bright) characters

`AA_BOLDFONT'
     for characters displayed using bold font

`AA_REVERSE'
     for reversed characters

`AA_SPECIAL'
     this can be used for displaying text over images. Its
     implementation depends at driver. Most drivers implement it as a
     white text on a blue background.

   For more comfortable output you may use:

     void aa_puts(aa_context *C, int X, int Y, int ATTR, char *S);
     int aa_printf(aa_context *C, int X, int Y, int ATTR, char *FMT, ...);

   It puts a string `s' (and atribute `attr') at coordinates `x', `y'.
Note that it doesn't move the cursor nor flushes buffers to screen.  To
move the cursor you have to use following function

     void aa_gotoxy(aa_context *C, int X, int Y);

   Some drivers can also support cursor hiding: `aa_hidecursor' or
`aa_showcursor' functions.


File: aalib.info,  Node: Keyboard,  Next: Mouse,  Prev: Flushing,  Up: Top

8 Keyboard
**********

AA-lib provides a simple interface to keyboard. It helps to make
aplications portable since the same keyboard interface is available on
all platforms. On the other hand it is very "dumb" (who cares...wait
till the next version).

* Menu:

* Initialization of keyboard::
* Getting events::


File: aalib.info,  Node: Initialization of keyboard,  Next: Getting events,  Prev: Keyboard,  Up: Keyboard

8.1 Initialization
==================

Keyboard interface needs to be initialized after display driver since
the existence of aa_context is required. The following function is
available for initializing:

     int aa_autoinitkbd(struct aa_context *CONTEXT, int MODE);
     int aa_initkbd(struct aa_context *CONTEXT,
                    struct aa_kbddriver *DRV, int MODE);

   The situation is very similiar to the initialization of hardware
display drivers.  The meaning is almost the same. Mode variable can be
set to zero for normal keyboard mode or to AA_SENDRELEASE that forces
driver to inform you about keys releasing (currently, only a few
drivers support this feature :().

   You can recommend drivers:

     aa_recomendhikbd(NAME);
     aa_recomendlowkbd(NAME);

   Close context or use

     void aa_uninitkbd(struct aa_context *CONTEXT);

   to uninitialize a keyboard driver.


File: aalib.info,  Node: Getting events,  Prev: Initialization of keyboard,  Up: Keyboard

8.2 Getting events
==================

Once keyboard is up you should use following function to get the events:

     int aa_getevent(aa_context *C, int WAIT);

   if WAIT is set to 1 functions wait for an event otherwise they just
peek for an event (and might return AA_NONE). Event can be:

  1. ascii code of pressed key (value is lower than 255)

  2. one of the following special keys: AA_UP, AA_DOWN, AA_LEFT,
     AA_RIGHT, AA_BACKSPACE, AA_ESC

  3. value higher or equal to AA_UNKNOWN but lower than AA_RELEASE
     means unknown key.

  4. two special events AA_MOUSE and AA_RESIZE (will be explained later)

  5. higher value than AA_RELEASE means released key. To get keycode
     use: `value &= ~AA_RELEASE'.


   If you don't want to be informed about such strange events and if
you want to know just about the keys use:

     int aa_getkey(aa_context *C, int WAIT);


File: aalib.info,  Node: Mouse,  Next: Resizing,  Prev: Keyboard,  Up: Top

9 Mouse
*******

AA-lib also provides a simple mouse interface. It needs to be
initialized after the keyboard driver (and uninitialized before) since
it uses it to report events. Its initialization is almost identical to
keyboards (just replace kbd by mouse in function names). If you need
more details read the keyboard section.

   The only difference is mode parameter.  It says what kind of events
you should be informed about.  It is a mask from the following fields:
AA_MOUSEMOVEMASK, AA_MOUSEPRESSMASK and AA_PRESSEDMOVEMAKS.  Note that
mouse driver should ignore this mask. Set it to AA_MOUSEALLMASK to
enables all these events.

   Mouse event is reported by AA_MOUSE value returned by `aa_getevent'
function. Then the mouse possition can be obtained using:

     void aa_getmouse(aa_context *C, int *X, int *Y, int *B);

   `X' and `y' are reported in screen coordinates (not image ones).
`B' contains state of buttons (AA_BUTTON1, AA_BUTTON2, AA_BUTTON3).

     void aa_hidemouse(aa_context *C);
     void aa_showmouse(aa_context *C);

   This functions should be used to hide/show mouse cursor.


File: aalib.info,  Node: Resizing,  Next: Other functions,  Prev: Mouse,  Up: Top

10 Resizing of display
**********************

Some display devices (like unix terminals or X11 windows) allows
runtime resizing.  This event is reported by AA_RESIZE. Then
application is expected to call the function

     int aa_resize(aa_context *C);

   that changes the values in aa_context and resizes buffer. Function
returns 0 if it failed. If everything went OK application must redraw
the screen according to the new size because the original one has been
lost. If your aplication handles these events at many various places or
uses `aa_getkey' the catch of AA_RESIZE is more complicated and you
should use the resize handler.

     void aa_resizehandler(aa_context *C, void (*HANDLER) (aa_context *));

   Then the resize handler is called by `aa_getevent' or `aa_getkey'
functions when AA_RESIZE event appears. Some simple apps that don't
rely on the display size and they redraw the whole screen after every
event (some animations) should also use a bit tricky construction:

     aa_resizehandler(aa_context *C, (void *)aa_resize);

   This will cause automatical handling of resize events without any
special stuff done by the application.


File: aalib.info,  Node: Other functions,  Next: Designing new driver,  Prev: Resizing,  Up: Top

11 Other functions
******************

     aa_renderparams *aa_getrenderparams(void);

   This functions allocates a copy of aa_defrenderparams variable. It
should be used by aplications that use more rendering parameters and
that don't want to change aa_defrenderparams every time.

     int aa_registerfont(struct aa_font *F);

   This functions allows you to register a new font into font databaze
(that is contained in `aa_fonts' array). This is often used by hardware
drivers (that autodetect their fonts ...).

     void aa_setsupported(aa_context *C, int SUPPORTED);

   Allows you to change a supported variable (see Initialization) at
runtime.

     void aa_setfont(aa_context *C, struct aa_font *FONT);

   Allows you to change a font used for approximation tables at runtime.

     void aa_edit(aa_context *C, int X, int Y, int SIZE, char *S, int MAXSIZE);

   A simple line editor: `X', `y', `size' express possitions of editor
window, `s' - pointer to string you may want to edit and `maxsize'
specifies the maximal size of input line.

     struct aa_edit *aa_createedit(aa_context *C, int X, int Y,
                                   int SIZE, char *S, int MAXSIZE);
     void aa_editkey(struct aa_edit *E, int C);

   Event handled version of an editor. `aa_createedit' fills in the
struct `aa_edit' for the input line and `aa_editkey' processes an event
for editor. Can be used by some "user friendly (huh:)" aplications....


File: aalib.info,  Node: Designing new driver,  Next: Reference,  Prev: Other functions,  Up: Top

12 Designing new driver
***********************

To write new driver is quite easy. You need to implement just few very
basic functions (like initialization, drawing to screen etc...) and
register it in the driver registry. There is separate drivers for
screen, mouse and keyboard.

12.0.1 Display driver
---------------------

Display driver is the most significant driver (of course) so it is
recomended to implement it first. Its structure is as follows:

     struct aa_driver {
       char *shortname, *name;
       int (*init) (struct aa_hardware_params *, void *, struct aa_hardware_params);
       void (*uninit) (struct aa_context *);
       void (*getsize) (struct aa_context *, int *, int *);
       void (*setattr) (struct aa_context *, int);
       void (*print) (struct aa_context *, char *);
       void (*gotoxy) (struct aa_context *,
           int, int);
       void (*flush) (struct aa_context *);
       void (*cursormode) (struct
           aa_context *, int);
     };

 -- Text: shortname
     SHORTNAME is an string that contain short name of your driver.
     Short name is expected to be one word name like "`linux'".

 -- Text: name
     NAME is an string that contain full name of your driver. It should
     contain version etc. like "`Linux console driver version 1.0'"

 -- Function: init
     This function is expected to initialize driver. It returns 0 if
     failed or 1 if driver is initialized. Note that driver can't
     produce any garbage when failed since AAlib will try to initialize
     other driver. First parameter specifies hardware parameters that
     user expect. Structure contain mask of attributes and recomended
     size. Mechanizm of handling sizes is described in section.  Second
     parameter is pointer to user data that should be passed by
     application.  It is `NULL' by default. Last is pointer to
     hardware_params structure, where driver will put parameters of
     initialized device.  This structure holds information about
     atributes and parameters supported by your driver. *Note
     Initialization for image saving::.  Just first two fields are used
     (`font' and `supported').  FONT is pointer to font structure used
     by hardware. This field should be filed at runtime (see
     `aalinux.c' for example), set statically to one of aalib's fonts
     or set to `NULL' if hardware does not allow detection of font
     (such as text terminals). SUPPORTED is mask of all atributes
     supported by your hardware ( `AA_NORMAL_MASK', `AA_DIM_MASK',
     `AA_BOLD_MASK', `AA_BOLDFONT_MASK', `AA_REVERSE_MASK') and rage of
     useable characters (by default just standard ASCII characters are
     used) use `AA_EXTENDED' if your driver supports all characters
     (0-255).  `AA_ALL' should be used if your driver displays
     characters instead of blanks (cr, tab etc..), `AA_EIGHT' lets
     AAlib use characters greater than 128.  `Mmwidth' and `mmheight'
     fields should be also set if is possible to determine physical
     size of screen/window.  *Note Specifying hardware parameters::

     Last parameter should be used to define pointer that will be later
     set to `driverdata' field of `aa_context'. If driver needs some
     additional data, it should alloc driverdata structure, that will
     hold this data. AAlib will automatically free this pointer at
     `aa_close' if it is non-NULL.

     This function should also recomend best available keyboard and
     mouse drivers.  *Note How does the autodetection work::.

 -- Function: uninit
     This functin uninitializes driver and frees all resources used by
     it.

 -- Function: getsize
     This function returns width and height of screen in characters.

   There is two alternate ways to implement screen output. First way is
commonly used by text libraries - print/gotoxy/setattr mechanizm.
Second one is flush. Flush should be fast function that display AAlibs
internal buffer to screen. This way is preffered.  In case PRINT field
is set to `NULL' AAlib will call just flush and expect that driver will
update screen automatically from internal buffers. When both PRINT and
FLUSH are non`NULL' AAlib will first use PRINT/SETATTR/GOTOXY to update
screen and then call FLUSH. Note that in case PRINT is `NULL', SETATTR
should be also `NULL' but `gotoxy' needs to be non`NULL' since it is
used to sed hardware cursor.

 -- Function: setattr
     Set current attributes

 -- Function: print
     Print text at current cursor possition using current attrubutes

 -- Function: gotoxy
     Change cursor possition (coordinated begins by 0,0 in top left
     corner)

 -- Function: flush
     Flush current screen to output. In case you use AAlibs internal
     buffers to update screen (not PRINT) mechanizm get pointer to text
     and attribute buffer using `aa_text' and `aa_attr' functions.
     Buffers are formated into "normal" videoram - starting in top left
     corner and continue like english text. Attribute buffer should
     contain `AA_NORMAL', `AA_BOLD', `AA_BOLDFONT', `AA_DIM',
     `AA_REVERSE' and `AA_SPECIAL' values.

 -- Function: cursormode
     This function is used to enable/disable cursor. 1 means enable, 0
     disable.  Should be set to `NULL' if your hardware don't support
     this.

12.0.2 Keyboard driver
----------------------

This driver is defined by structure:
     struct aa_kbddriver {
           char *shortname, *name;
           int flags;
           int (*init) (struct aa_context *, int mode);
           void (*uninit) (struct aa_context *);
           int (*getkey) (struct aa_context *, int);
     };

 -- String: shortname

 -- String: name
     This fields have similiar as in display drivers.

 -- Integer: flags
     This field informs about extensions supported by driver. Currently
     should be set to `AA_SENDRELEASE' in case driver should inform
     about key releases too.

 -- Function: init
     Similiar functionality as in display drivers. MODE should be set
     to 0 or `AA_SENDRELEASE' in case application wants to be informed
     about key releases too. Note that driver should send releases even
     MODE is 0.

     This function should also recomend best available mouse driver.
     *Note How does the autodetection work::.

 -- Function: uninit
     Uninitializes driver

 -- Function: getkey
     This funtion return key. Second parameters is set to 1 if function
     is expected to wait for key or 0 if is expected to return
     `AA_NONE' of no event is pending. Function returns also key
     releases -- like normal keys masked by `AA_RELEASE'. It also
     recognizes some special keys. *Note Getting events::. It should
     also cooperate with mouse driver and return `AA_MOUSE' if mouse
     event is pending. Second way is to ignore wait parameters and
     never wait for key when mouse driver is enabled. This way is not
     recomended for multitasking enviroments.

12.0.3 Mouse driver
-------------------

This driver is defined by structure:
     struct aa_mousedriver {
           char *shortname, *name;
           int flags;
           int (*init) (struct aa_context *, int mode);
           void (*uninit) (struct aa_context *);
           void (*getmouse) (struct aa_context *, int *x, int *y, int *buttons);
           void (*cursormode) (struct aa_context *,int);
     };

   First five fields has very similiar meaning to ones in keyboard
driver.  `flags' is set to all events driver should report about:
`AA_MOUSEMOVEMASK', `AA_MOUSEPRESSMASK' and `AA_PRESSEDMOVEMAKS'. All
of them are colected into `AA_MOUSEALLMASK'. If driver has
showcursor/hidecursor functionality set also flag `AA_HIDECURSOR'. MODE
parameter to INIT function should be set to mask of events application
wants to know about, like in FLAGS.

 -- Function: getmouse
     This function returns coordinates of cursor and mask of buttons
     (`AA_BUTTON1', `AA_BUTTON2', `AA_BUTTON3'). Coordinates are same
     as for `gotoxy' call.

 -- Function: cursormode
     This function is used to show/disable mouse cursor.  Should be set
     to `NULL' if not supported.


File: aalib.info,  Node: Reference,  Next: Index,  Prev: Designing new driver,  Up: Top

Appendix A Reference
********************

* Menu:


* aa_attrs::             returns pointer to the text output buffer used by AA-lib.
* aa_autoinitkbd::       easy to use AA-lib keyboard initialization function.
* aa_autoinitmouse::     easy to use AA-lib mouse initialization function.
* aa_autoinit::          easy to use AA-lib initialization function.
* aa_close::             close the AA-lib context.
* aa_createedit::        Simple interactive line editor provided as helper function.
* aa_currentfont::       returns specification of the fonts used by AA-lib rendering routines.
* aa_defparams::         default hardware paramters requested by AA-lib programs.
* aa_defrenderparams::   default rendering parameters.
* aa_displayrecommended::List of recommended drivers.
* aa_dithernames::       Names of dithering methods supported by AA-lib.
* aa_drivers::           NULL-terminated array of output drivers available in AA-lib.
* aa_editkey::           Notify the line editor about keypress.
* aa_edit::              Simple interactive line editor.
* aa_fastrender::        simple and fast AA-lib rendering function.
* aa_fonts::             Null-terminated array of available fonts.
* aa_formats::           NULL terminated array of save formats supported by AA-lib.
* aa_getevent::          keyboard functions
* aa_getkey::            return next keypress event from queue.
* aa_getmouse::          Get mouse position as specified by last mouse event read by aa_getevent.
* aa_gotoxy::            move the hardware cursor (if any) to specified position.
* aa_help::              AA-lib help string for the default command line parser.
* aa_hidecursor::        hide the hardware cursor.
* aa_hidemouse::         hide the mouse cursor.
* aa_image::             returns pointer to the framebuffer emulated by AA-lib.
* aa_imgheight::         returns height of the emulated image in pixels.
* aa_imgwidth::          returns width of the emulated image in pixels.
* aa_initkbd::           initialize the AA-lib keyboard driver.
* aa_initmouse::         initialize the AA-lib mouse driver.
* aa_init::              open the output display for AA-lib.
* aa_kbddrivers::        NULL-terminated array of keyboard drivers available in AA_lib.
* aa_kbdrecommended::    List of recommended drivers.
* aa_mmheight::          returns height of the output screen in millimeters.
* aa_mmwidth::           returns width of the output screen in millimeters.
* aa_mousedrivers::      NULL terminated array of mouse drivers supported by AA-lib.
* aa_mouserecommended::  List of recommended drivers.
* aa_parseoptions::      parse the standard command line options used by AA-lib.
* aa_printf::            print text to AA-lib output buffers.
* aa_putpixel::          put pixel to emulated framebuffer
* aa_puts::              output string to AA-lib output buffers.
* aa_recommendhidisplay::insert the given driver on beggining of the list of recommended display drivers.
* aa_recommendhikbd::    insert the given driver on beggining of the list of recommended keyboard drivers.
* aa_recommendhimouse::  insert the given driver on beggining of the list of recommended mouse drivers.
* aa_recommendhi::       insert the given driver on beggining of the list of recommended drivers.
* aa_recommendlowdisplay::Add the given driver to the end of list of display recommended drivers.
* aa_recommendlowkbd::   Add the given driver to the end of list of keyboard recommended drivers.
* aa_recommendlowmouse:: Add the given driver to the end of list of mouse recommended drivers.
* aa_recommendlow::      Add the given driver to the end of list of recommended drivers.
* aa_registerfont::      add new font specification to aa_fonts array.
* aa_render::            convert image buffer to ASCII-art.
* aa_resizehandler::     Set user handler to be called on resize event.
* aa_resize::            resize functions
* aa_scrheight::         returns height of the output screen in characters.
* aa_scrwidth::          returns width of the output screen in characters.
* aa_setfont::           set font specification to be used by rendering functions.
* aa_setsupported::      alter the "supported" field of hardware_params structure used by AA-lib
* aa_showcursor::        show the hardware cursor.
* aa_showmouse::         show the mouse cursor.
* aa_text::              returns pointer to the text output buffer used by AA-lib.
* aa_uninitkbd::         uninitialize the keyboard driver.
* aa_uninitmouse::       uninitialize the mouse driver.
* mem_d::                AA-lib memory driver.
* save_d::               AA-lib driver used to save ascii-art image into file in used specified format.


File: aalib.info,  Node: aa_attrs,  Next: aa_autoinitkbd,  Up: Reference

A.1 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.


File: aalib.info,  Node: aa_autoinitkbd,  Next: aa_autoinitmouse,  Prev: aa_attrs,  Up: Reference

A.2 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.


File: aalib.info,  Node: aa_autoinitmouse,  Next: aa_autoinit,  Prev: aa_autoinitkbd,  Up: Reference

A.3 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.


File: aalib.info,  Node: aa_autoinit,  Next: aa_close,  Prev: aa_autoinitmouse,  Up: Reference

A.4 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.


File: aalib.info,  Node: aa_close,  Next: aa_createedit,  Prev: aa_autoinit,  Up: Reference

A.5 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.


File: aalib.info,  Node: aa_createedit,  Next: aa_currentfont,  Prev: aa_close,  Up: Reference

A.6 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.


File: aalib.info,  Node: aa_currentfont,  Next: aa_defparams,  Prev: aa_createedit,  Up: Reference

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


File: aalib.info,  Node: aa_defparams,  Next: aa_defrenderparams,  Prev: aa_currentfont,  Up: Reference

A.8 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.


File: aalib.info,  Node: aa_defrenderparams,  Next: aa_displayrecommended,  Prev: aa_defparams,  Up: Reference

A.9 aa_defrenderparams
======================


     #include <aalib.h>

     extern struct aa_renderparams aa_defrenderparams;

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

Default rendering parameters. Passed to aa_render function familly.


File: aalib.info,  Node: aa_displayrecommended,  Next: aa_dithernames,  Prev: aa_defrenderparams,  Up: Reference

A.10 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.


File: aalib.info,  Node: aa_dithernames,  Next: aa_drivers,  Prev: aa_displayrecommended,  Up: Reference

A.11 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.


File: aalib.info,  Node: aa_drivers,  Next: aa_editkey,  Prev: aa_dithernames,  Up: Reference

A.12 aa_drivers
===============


     #include <aalib.h>

     extern const struct aa_driver *const aa_drivers[];

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

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


File: aalib.info,  Node: aa_editkey,  Next: aa_edit,  Prev: aa_drivers,  Up: Reference

A.13 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.


File: aalib.info,  Node: aa_edit,  Next: aa_fastrender,  Prev: aa_editkey,  Up: Reference

A.14 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.


File: aalib.info,  Node: aa_fastrender,  Next: aa_fonts,  Prev: aa_edit,  Up: Reference

A.15 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.


File: aalib.info,  Node: aa_fonts,  Next: aa_formats,  Prev: aa_fastrender,  Up: Reference

A.16 aa_fonts
=============


     #include <aalib.h>

     extern const struct aa_font *aa_fonts[];

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

Null-terminated array of available fonts.


File: aalib.info,  Node: aa_formats,  Next: aa_getevent,  Prev: aa_fonts,  Up: Reference

A.17 aa_formats
===============


     #include <aalib.h>

     extern const struct aa_format *const aa_formats[];

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

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


File: aalib.info,  Node: aa_getevent,  Next: aa_getkey,  Prev: aa_formats,  Up: Reference

A.18 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.


File: aalib.info,  Node: aa_getkey,  Next: aa_getmouse,  Prev: aa_getevent,  Up: Reference

A.19 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.


File: aalib.info,  Node: aa_getmouse,  Next: aa_gotoxy,  Prev: aa_getkey,  Up: Reference

A.20 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.


File: aalib.info,  Node: aa_gotoxy,  Next: aa_help,  Prev: aa_getmouse,  Up: Reference

A.21 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.


File: aalib.info,  Node: aa_help,  Next: aa_hidecursor,  Prev: aa_gotoxy,  Up: Reference

A.22 aa_help
============


     #include <aalib.h>

     extern const char *const aa_help;

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

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


File: aalib.info,  Node: aa_hidecursor,  Next: aa_hidemouse,  Prev: aa_help,  Up: Reference

A.23 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.


File: aalib.info,  Node: aa_hidemouse,  Next: aa_image,  Prev: aa_hidecursor,  Up: Reference

A.24 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.


File: aalib.info,  Node: aa_image,  Next: aa_imgheight,  Prev: aa_hidemouse,  Up: Reference

A.25 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.


File: aalib.info,  Node: aa_imgheight,  Next: aa_imgwidth,  Prev: aa_image,  Up: Reference

A.26 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.


File: aalib.info,  Node: aa_imgwidth,  Next: aa_initkbd,  Prev: aa_imgheight,  Up: Reference

A.27 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.


File: aalib.info,  Node: aa_initkbd,  Next: aa_initmouse,  Prev: aa_imgwidth,  Up: Reference

A.28 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.


File: aalib.info,  Node: aa_initmouse,  Next: aa_init,  Prev: aa_initkbd,  Up: Reference

A.29 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.


File: aalib.info,  Node: aa_init,  Next: aa_kbddrivers,  Prev: aa_initmouse,  Up: Reference

A.30 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.


File: aalib.info,  Node: aa_kbddrivers,  Next: aa_kbdrecommended,  Prev: aa_init,  Up: Reference

A.31 aa_kbddrivers
==================


     #include <aalib.h>

     extern const struct aa_kbddriver *const aa_kbddrivers[];

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

NULL-terminated array of keyboard drivers available in AA_lib.


File: aalib.info,  Node: aa_kbdrecommended,  Next: aa_mmheight,  Prev: aa_kbddrivers,  Up: Reference

A.32 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.


File: aalib.info,  Node: aa_mmheight,  Next: aa_mmwidth,  Prev: aa_kbdrecommended,  Up: Reference

A.33 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.


File: aalib.info,  Node: aa_mmwidth,  Next: aa_mousedrivers,  Prev: aa_mmheight,  Up: Reference

A.34 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.


File: aalib.info,  Node: aa_mousedrivers,  Next: aa_mouserecommended,  Prev: aa_mmwidth,  Up: Reference

A.35 aa_mousedrivers
====================


     #include <aalib.h>

     extern const struct aa_mousedriver *const aa_mousedrivers[];

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

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


File: aalib.info,  Node: aa_mouserecommended,  Next: aa_parseoptions,  Prev: aa_mousedrivers,  Up: Reference

A.36 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.


File: aalib.info,  Node: aa_parseoptions,  Next: aa_printf,  Prev: aa_mouserecommended,  Up: Reference

A.37 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.


File: aalib.info,  Node: aa_printf,  Next: aa_putpixel,  Prev: aa_parseoptions,  Up: Reference

A.38 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.


File: aalib.info,  Node: aa_putpixel,  Next: aa_puts,  Prev: aa_printf,  Up: Reference

A.39 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.


File: aalib.info,  Node: aa_puts,  Next: aa_recommendhidisplay,  Prev: aa_putpixel,  Up: Reference

A.40 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.


File: aalib.info,  Node: aa_recommendhidisplay,  Next: aa_recommendhikbd,  Prev: aa_puts,  Up: Reference

A.41 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.


File: aalib.info,  Node: aa_recommendhikbd,  Next: aa_recommendhimouse,  Prev: aa_recommendhidisplay,  Up: Reference

A.42 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.


File: aalib.info,  Node: aa_recommendhimouse,  Next: aa_recommendhi,  Prev: aa_recommendhikbd,  Up: Reference

A.43 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.


File: aalib.info,  Node: aa_recommendhi,  Next: aa_recommendlowdisplay,  Prev: aa_recommendhimouse,  Up: Reference

A.44 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.


File: aalib.info,  Node: aa_recommendlowdisplay,  Next: aa_recommendlowkbd,  Prev: aa_recommendhi,  Up: Reference

A.45 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.


File: aalib.info,  Node: aa_recommendlowkbd,  Next: aa_recommendlowmouse,  Prev: aa_recommendlowdisplay,  Up: Reference

A.46 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.


File: aalib.info,  Node: aa_recommendlowmouse,  Next: aa_recommendlow,  Prev: aa_recommendlowkbd,  Up: Reference

A.47 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.


File: aalib.info,  Node: aa_recommendlow,  Next: aa_registerfont,  Prev: aa_recommendlowmouse,  Up: Reference

A.48 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.


File: aalib.info,  Node: aa_registerfont,  Next: aa_render,  Prev: aa_recommendlow,  Up: Reference

A.49 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.


File: aalib.info,  Node: aa_render,  Next: aa_resizehandler,  Prev: aa_registerfont,  Up: Reference

A.50 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.


File: aalib.info,  Node: aa_resizehandler,  Next: aa_resize,  Prev: aa_render,  Up: Reference

A.51 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.


File: aalib.info,  Node: aa_resize,  Next: aa_scrheight,  Prev: aa_resizehandler,  Up: Reference

A.52 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.


File: aalib.info,  Node: aa_scrheight,  Next: aa_scrwidth,  Prev: aa_resize,  Up: Reference

A.53 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.


File: aalib.info,  Node: aa_scrwidth,  Next: aa_setfont,  Prev: aa_scrheight,  Up: Reference

A.54 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.


File: aalib.info,  Node: aa_setfont,  Next: aa_setsupported,  Prev: aa_scrwidth,  Up: Reference

A.55 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.


File: aalib.info,  Node: aa_setsupported,  Next: aa_showcursor,  Prev: aa_setfont,  Up: Reference

A.56 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.


File: aalib.info,  Node: aa_showcursor,  Next: aa_showmouse,  Prev: aa_setsupported,  Up: Reference

A.57 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.


File: aalib.info,  Node: aa_showmouse,  Next: aa_text,  Prev: aa_showcursor,  Up: Reference

A.58 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.


File: aalib.info,  Node: aa_text,  Next: aa_uninitkbd,  Prev: aa_showmouse,  Up: Reference

A.59 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.


File: aalib.info,  Node: aa_uninitkbd,  Next: aa_uninitmouse,  Prev: aa_text,  Up: Reference

A.60 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.


File: aalib.info,  Node: aa_uninitmouse,  Next: mem_d,  Prev: aa_uninitkbd,  Up: Reference

A.61 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.


File: aalib.info,  Node: mem_d,  Next: save_d,  Prev: aa_uninitmouse,  Up: Reference

A.62 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.


File: aalib.info,  Node: save_d,  Prev: mem_d,  Up: Reference

A.63 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.


File: aalib.info,  Node: Index,  Prev: Reference,  Up: Top

Index of functions, variables, types and constants
**************************************************

[index]
* Menu:

* AA_ALL:                                Specifying hardware parameters.
                                                              (line  26)
* aa_ansi_format:                        Initialization for image saving.
                                                              (line  79)
* aa_attr:                               Flushing.            (line  12)
* aa_attrs:                              aa_attrs.            (line   3)
* aa_autoinit <1>:                       Initialization as a normal graphics library.
                                                              (line  13)
* aa_autoinit:                           aa_autoinit.         (line   3)
* aa_autoinitkbd <1>:                    aa_autoinitkbd.      (line   3)
* aa_autoinitkbd:                        Initialization of keyboard.
                                                              (line  10)
* aa_autoinitmouse <1>:                  Mouse.               (line   6)
* aa_autoinitmouse:                      aa_autoinitmouse.    (line   3)
* AA_BOLD:                               Flushing.            (line  25)
* AA_BOLD_MASK:                          Specifying hardware parameters.
                                                              (line  26)
* AA_BOLDFONT:                           Flushing.            (line  25)
* AA_BOLDFONT_MASK:                      Specifying hardware parameters.
                                                              (line  26)
* aa_close <1>:                          aa_close.            (line   3)
* aa_close:                              Initialization.      (line  21)
* aa_context:                            Initialization.      (line   9)
* aa_createedit <1>:                     aa_createedit.       (line   3)
* aa_createedit:                         Other functions.     (line  33)
* aa_currentfont:                        aa_currentfont.      (line   3)
* aa_defparams <1>:                      Specifying hardware parameters.
                                                              (line   9)
* aa_defparams:                          aa_defparams.        (line   3)
* aa_defrenderparams <1>:                aa_defrenderparams.  (line   3)
* aa_defrenderparams:                    Rendering.           (line  36)
* AA_DIM:                                Flushing.            (line  25)
* AA_DIM_MASK:                           Specifying hardware parameters.
                                                              (line  26)
* aa_displayrecomended:                  Recommending drivers.
                                                              (line   9)
* aa_displayrecommended:                 aa_displayrecommended.
                                                              (line   3)
* aa_dithernames:                        aa_dithernames.      (line   3)
* aa_drivers:                            aa_drivers.          (line   3)
* aa_edit <1>:                           aa_edit.             (line   3)
* aa_edit:                               Other functions.     (line  27)
* aa_editkey <1>:                        aa_editkey.          (line   3)
* aa_editkey:                            Other functions.     (line  33)
* AA_EIGHT:                              Specifying hardware parameters.
                                                              (line  26)
* AA_EXTENDED:                           Specifying hardware parameters.
                                                              (line  26)
* aa_fastrender <1>:                     Rendering.           (line   9)
* aa_fastrender:                         aa_fastrender.       (line   3)
* aa_flush:                              Flushing.            (line  12)
* aa_fonts:                              aa_fonts.            (line   3)
* aa_format:                             Initialization for image saving.
                                                              (line  32)
* aa_formats:                            aa_formats.          (line   3)
* aa_getevent <1>:                       Getting events.      (line   8)
* aa_getevent:                           aa_getevent.         (line   3)
* aa_getkey <1>:                         Getting events.      (line   8)
* aa_getkey:                             aa_getkey.           (line   3)
* aa_getmouse <1>:                       Mouse.               (line   6)
* aa_getmouse:                           aa_getmouse.         (line   3)
* aa_getrenderparams:                    Other functions.     (line   6)
* aa_gotoxy <1>:                         aa_gotoxy.           (line   3)
* aa_gotoxy:                             Flushing.            (line  56)
* aa_hardware_params:                    Specifying hardware parameters.
                                                              (line   9)
* aa_hardwareparams:                     Specifying hardware parameters.
                                                              (line   9)
* aa_help <1>:                           aa_help.             (line   3)
* aa_help:                               Parsing of command line options.
                                                              (line  60)
* aa_hidecursor <1>:                     Flushing.            (line  56)
* aa_hidecursor:                         aa_hidecursor.       (line   3)
* aa_hidemouse <1>:                      Mouse.               (line   6)
* aa_hidemouse:                          aa_hidemouse.        (line   3)
* aa_hp2_format:                         Initialization for image saving.
                                                              (line  79)
* aa_hp_format:                          Initialization for image saving.
                                                              (line  79)
* aa_html_alt_format:                    Initialization for image saving.
                                                              (line  79)
* aa_html_format:                        Initialization for image saving.
                                                              (line  79)
* aa_image <1>:                          Drawing image.       (line   6)
* aa_image:                              aa_image.            (line   3)
* aa_imgheight <1>:                      aa_imgheight.        (line   3)
* aa_imgheight:                          Drawing image.       (line   6)
* aa_imgwidth <1>:                       Drawing image.       (line   6)
* aa_imgwidth:                           aa_imgwidth.         (line   3)
* aa_init <1>:                           aa_init.             (line   3)
* aa_init:                               Initialization.      (line   9)
* aa_initkbd <1>:                        aa_initkbd.          (line   3)
* aa_initkbd:                            Initialization of keyboard.
                                                              (line  10)
* aa_initmouse <1>:                      Mouse.               (line   6)
* aa_initmouse:                          aa_initmouse.        (line   3)
* aa_irc_format:                         Initialization for image saving.
                                                              (line  79)
* aa_kbddrivers:                         aa_kbddrivers.       (line   3)
* aa_kbdrecommended:                     aa_kbdrecommended.   (line   3)
* aa_mmheight <1>:                       Drawing image.       (line  33)
* aa_mmheight:                           aa_mmheight.         (line   3)
* aa_mmwidth <1>:                        aa_mmwidth.          (line   3)
* aa_mmwidth:                            Drawing image.       (line  33)
* aa_more_format:                        Initialization for image saving.
                                                              (line  79)
* AA_MOUSEALLMASK:                       Mouse.               (line   6)
* aa_mousedrivers:                       aa_mousedrivers.     (line   3)
* AA_MOUSEMOVEMASK:                      Mouse.               (line   6)
* AA_MOUSEPRESSMASK:                     Mouse.               (line   6)
* aa_mouserecommended:                   aa_mouserecommended. (line   3)
* aa_nhtml_format:                       Initialization for image saving.
                                                              (line  79)
* AA_NONE:                               Getting events.      (line   8)
* AA_NORMAL:                             Flushing.            (line  25)
* AA_NORMAL_MASK:                        Specifying hardware parameters.
                                                              (line  26)
* aa_palette:                            Drawing image.       (line  25)
* aa_parseoptions <1>:                   aa_parseoptions.     (line   3)
* aa_parseoptions:                       Parsing of command line options.
                                                              (line  15)
* AA_PRESSEDMOVEMAKS:                    Mouse.               (line   6)
* aa_printf:                             aa_printf.           (line   3)
* aa_putpixel <1>:                       aa_putpixel.         (line   3)
* aa_putpixel:                           Drawing image.       (line   6)
* aa_puts <1>:                           aa_puts.             (line   3)
* aa_puts:                               Flushing.            (line  49)
* aa_recomendhidisplay:                  Recommending drivers.
                                                              (line   9)
* aa_recomendhikbd:                      Initialization of keyboard.
                                                              (line  22)
* aa_recomendhimouse:                    Mouse.               (line   6)
* aa_recomendlowdisplay:                 Recommending drivers.
                                                              (line   9)
* aa_recomendlowkbd:                     Initialization of keyboard.
                                                              (line  22)
* aa_recomendlowmouse:                   Mouse.               (line   6)
* aa_recommendhi:                        aa_recommendhi.      (line   3)
* aa_recommendhidisplay:                 aa_recommendhidisplay.
                                                              (line   3)
* aa_recommendhikbd:                     aa_recommendhikbd.   (line   3)
* aa_recommendhimouse:                   aa_recommendhimouse. (line   3)
* aa_recommendlow:                       aa_recommendlow.     (line   3)
* aa_recommendlowdisplay:                aa_recommendlowdisplay.
                                                              (line   3)
* aa_recommendlowkbd:                    aa_recommendlowkbd.  (line   3)
* aa_recommendlowmouse:                  aa_recommendlowmouse.
                                                              (line   3)
* aa_registerfont <1>:                   Other functions.     (line  12)
* aa_registerfont:                       aa_registerfont.     (line   3)
* AA_RELEASE:                            Getting events.      (line   8)
* aa_render <1>:                         Rendering.           (line   9)
* aa_render:                             aa_render.           (line   3)
* aa_renderpalette:                      Rendering.           (line   9)
* aa_renderparams:                       Rendering.           (line  36)
* aa_resize:                             Resizing.            (line   6)
* AA_RESIZE:                             Resizing.            (line   6)
* aa_resize:                             aa_resize.           (line   3)
* aa_resizehandler <1>:                  Resizing.            (line   6)
* aa_resizehandler:                      aa_resizehandler.    (line   3)
* AA_REVERSE:                            Flushing.            (line  25)
* AA_REVERSE_MASK:                       Specifying hardware parameters.
                                                              (line  26)
* aa_savedata:                           Initialization for image saving.
                                                              (line   9)
* aa_scrheight:                          aa_scrheight.        (line   3)
* aa_scrwidth:                           aa_scrwidth.         (line   3)
* AA_SENDRELEASE:                        Initialization of keyboard.
                                                              (line  10)
* aa_setfont <1>:                        aa_setfont.          (line   3)
* aa_setfont:                            Other functions.     (line  23)
* aa_setpalette:                         Drawing image.       (line  25)
* aa_setsupported <1>:                   aa_setsupported.     (line   3)
* aa_setsupported:                       Other functions.     (line  18)
* aa_showcursor <1>:                     aa_showcursor.       (line   3)
* aa_showcursor:                         Flushing.            (line  56)
* aa_showmouse <1>:                      Mouse.               (line   6)
* aa_showmouse:                          aa_showmouse.        (line   3)
* AA_SPECIAL:                            Flushing.            (line  25)
* aa_text <1>:                           aa_text.             (line   3)
* aa_text:                               Flushing.            (line  12)
* aa_text_format:                        Initialization for image saving.
                                                              (line  79)
* aa_uninitkbd <1>:                      aa_uninitkbd.        (line   3)
* aa_uninitkbd:                          Initialization of keyboard.
                                                              (line  22)
* aa_uninitmouse <1>:                    aa_uninitmouse.      (line   3)
* aa_uninitmouse:                        Mouse.               (line   6)
* aa_zephyr_format:                      Initialization for image saving.
                                                              (line  79)
* cursormode:                            Designing new driver.
                                                              (line 190)
* flags:                                 Designing new driver.
                                                              (line 136)
* flush:                                 Designing new driver.
                                                              (line 105)
* font14:                                Specifying hardware parameters.
                                                              (line  22)
* font16:                                Specifying hardware parameters.
                                                              (line  22)
* font8:                                 Specifying hardware parameters.
                                                              (line  22)
* font9:                                 Specifying hardware parameters.
                                                              (line  22)
* fontgl:                                Specifying hardware parameters.
                                                              (line  22)
* fontlinux:                             Specifying hardware parameters.
                                                              (line  22)
* fontX13:                               Specifying hardware parameters.
                                                              (line  22)
* fontX13B:                              Specifying hardware parameters.
                                                              (line  22)
* fontX16:                               Specifying hardware parameters.
                                                              (line  22)
* getkey:                                Designing new driver.
                                                              (line 153)
* getmouse:                              Designing new driver.
                                                              (line 185)
* getsize:                               Designing new driver.
                                                              (line  81)
* gotoxy:                                Designing new driver.
                                                              (line 101)
* init:                                  Designing new driver.
                                                              (line 141)
* mem_d <1>:                             Initialization as an ascii art renderer.
                                                              (line  11)
* mem_d:                                 mem_d.               (line   3)
* name:                                  Designing new driver.
                                                              (line 133)
* print:                                 Designing new driver.
                                                              (line  98)
* save_d <1>:                            save_d.              (line   3)
* save_d:                                Initialization for image saving.
                                                              (line   6)
* setattr:                               Designing new driver.
                                                              (line  95)
* shortname:                             Designing new driver.
                                                              (line  32)
* uninit:                                Designing new driver.
                                                              (line 150)



Tag Table:
Node: Top409
Node: Overview5986
Node: Why?6204
Node: What?6619
Node: History7245
Node: AA-Project8544
Node: Skeleton9646
Node: Initialization11666
Node: Initialization as a normal graphics library12972
Node: Easy initialization of AA-lib14045
Node: Parsing of command line options15150
Node: How does the autodetection work19620
Node: Recommending drivers20842
Node: Initialization as an ascii art renderer22650
Node: Initialization for image saving23189
Node: Specifying hardware parameters26785
Node: Drawing image29240
Node: Rendering31265
Node: Flushing33819
Node: Keyboard35962
Node: Initialization of keyboard36353
Node: Getting events37354
Node: Mouse38329
Node: Resizing39515
Node: Other functions40756
Node: Designing new driver42300
Node: Reference50503
Node: aa_attrs55273
Node: aa_autoinitkbd55810
Node: aa_autoinitmouse56752
Node: aa_autoinit57585
Node: aa_close58348
Node: aa_createedit58742
Node: aa_currentfont59774
Node: aa_defparams60196
Node: aa_defrenderparams60539
Node: aa_displayrecommended60876
Node: aa_dithernames61272
Node: aa_drivers61614
Node: aa_editkey61914
Node: aa_edit62347
Node: aa_fastrender63163
Node: aa_fonts64180
Node: aa_formats64444
Node: aa_getevent64737
Node: aa_getkey65558
Node: aa_getmouse66289
Node: aa_gotoxy67034
Node: aa_help67611
Node: aa_hidecursor67878
Node: aa_hidemouse68278
Node: aa_image68645
Node: aa_imgheight69243
Node: aa_imgwidth69613
Node: aa_initkbd69981
Node: aa_initmouse70834
Node: aa_init71670
Node: aa_kbddrivers72790
Node: aa_kbdrecommended73107
Node: aa_mmheight73479
Node: aa_mmwidth73857
Node: aa_mousedrivers74229
Node: aa_mouserecommended74558
Node: aa_parseoptions74944
Node: aa_printf76522
Node: aa_putpixel78082
Node: aa_puts78652
Node: aa_recommendhidisplay80135
Node: aa_recommendhikbd80646
Node: aa_recommendhimouse81158
Node: aa_recommendhi81666
Node: aa_recommendlowdisplay82339
Node: aa_recommendlowkbd82853
Node: aa_recommendlowmouse83362
Node: aa_recommendlow83867
Node: aa_registerfont84529
Node: aa_render84983
Node: aa_resizehandler86283
Node: aa_resize86821
Node: aa_scrheight87391
Node: aa_scrwidth87765
Node: aa_setfont88136
Node: aa_setsupported88649
Node: aa_showcursor89345
Node: aa_showmouse89757
Node: aa_text90123
Node: aa_uninitkbd90691
Node: aa_uninitmouse91142
Node: mem_d91594
Node: save_d92001
Node: Index92370

End Tag Table