\input texinfo   @c -*-texinfo-*-

@c Use A4 paper - If you don't like that, remove the following 3 lines.
@iftex
@afourpaper
@end iftex
@setfilename aalib.info
@settitle An ascii-art library
@dircategory Libraries
@direntry
* AA-lib: (aalib).              An ASCII-art graphics library
@end direntry



@ifinfo
@copyright{} 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.

@end ifinfo

@c %**end of header

@set VERSION    1.4
@set DATE       Apr 17, 2001

@titlepage

@title AA-lib @value{VERSION}
@subtitle An ascii-art library
@subtitle API-DESCRIPTION

@author Jan Hubi@v cka & Kamil Toman
@tex
Dukelsk\'ych bojovn\'\i ku 1944 
@end tex
@*
390 03 T@'abor @*
Czech Republic

Email: @code{hubicka@@freesoft.cz}

@value{DATE}

@page
@vskip 0pt plus 1filll
@tex
{
\font\btt=cmtt12\space scaled\magstep 4
\btt
\centerline{ \ \ \ \ \ dT8\ \ 8Tb\ \ \ \ \ }\br\medskip
\centerline{ \ \ \ \ dT\ 8\ \ 8\ Tb\ \ \ \ }\br\medskip
\centerline{ \ \ \ dT\ \ 8\ \ 8\ \ Tb\ \ \ }\br\medskip
\centerline{ <PROJECT><PROJECT>}\br\medskip
\centerline{ \ dT\ \ \ \ 8\ \ 8\ \ \ \ Tb\ }\br\medskip
\centerline{ dT@ \ \ \ \ 8\ \ 8\ \ \ \ \ Tb}\br\medskip
}
@end tex
@vskip 0pt plus 1filll

@copyright{} 1997 @tex Jan Hubi\v cka \& Kamil Toman
@end tex

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.

@end titlepage

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node   Top,    Overview,       (dir),  (dir)

@ifinfo
@top AA-lib @value{VERSION}
@flushright 1.2
An ascii-art library
API DESCRIPTION
@value{DATE}
@end flushright
@end ifinfo


@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
@end menu

@ifinfo
@example

                                                            
                         .,.  _.    .                       
                      .%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>
@end example
@end ifinfo
		

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Overview, AA-Project, Top, Top

@chapter Overview
@menu
* Why?::		Why such library?
* What?::		What does this software do then?
* History::		How this all started?
@end menu

@node Why?, What?, Overview, Overview
@section Why such library?
I vote for simplicity. There are many problems of various kinds with video
cards, low frequency monitors, crashing graphical apps@dots{} 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!

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node What?, History, Why?, Overview
@comment  node-name,  next,      previous,  up
@section 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! 

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node History, , What?, Overview
@section 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 @dots{}

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node AA-Project, Skeleton, Overview, Top
@chapter AA-Project
@ifinfo
@center @ @ @ @ @ dT8@ @ 8Tb@ @ @ @ @ @*
@center @ @ @ @ dT@ 8@ @ 8@ Tb@ @ @ @ @*
@center @ @ @ dT@ @ 8@ @ 8@ @ Tb@ @ @ @*
@center <PROJECT><PROJECT>@*
@center @ dT@ @ @ @ 8@ @ 8@ @ @ @ Tb@ @*
@center dT@ @ @ @ @ 8@ @ 8@ @ @ @ @ Tb@*


@end ifinfo
@tex
%{
%\tt
%\centerline{ \ \ \ \ \ dT8\ \ 8Tb\ \ \ \ \ }\br
%\centerline{ \ \ \ \ dT\ 8\ \ 8\ Tb\ \ \ \ }\br
%\centerline{ \ \ \ dT\ \ 8\ \ 8\ \ Tb\ \ \ }\br
%\centerline{ <PROJECT><PROJECT>}\br
%\centerline{ \ dT\ \ \ \ 8\ \ 8\ \ \ \ Tb\ }\br
%\centerline{ dT@ \ \ \ \ 8\ \ 8\ \ \ \ \ Tb}\br
%}
@end tex


Three goals of AA-Project:

@enumerate
@item
Port all important software (like Doom, Second Reality, X windows etc..) 
on AA-lib.
@item
Port AA-lib on all available platforms (mainly ZX-Spectrum and Sharp).
@item
Force IBM to start manufacturing MDA cards again.
@end enumerate


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: @code{aa-project-discuss@@lists.sourceforge.net}. 

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

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Skeleton, Initialization , AA-Project, Top
@chapter AA-lib program skeleton

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

@example
#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;
@}
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization, Drawing image , Skeleton, Top
@chapter Initialization
It is possible to initialize AA-lib in various modes.
The main initialization is done by following @code{aa_init}

@findex aa_init
@findex aa_context
@example
aa_context *aa_init(struct aa_driver *@var{driver}, 
                    struct aa_hardware_params *@var{defparams}, 
                    void *@var{driverdata})
@end example

This function prepares @code{aa_context *} type variable used by all AA-lib 
functions. The @var{driver} parameter specifies hardware driver to initialize,
@var{defparams} parameters of hardware you require and @var{driverdata} is
used to pass implementation dependent extra information to the hardware
driver.

To undo all actions done by @code{aa_init} function, call @code{aa_close}:

@findex aa_close
@example
aa_close(aa_context *@var{context})
@end example

This function frees allocated memory for @code{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.

@ifinfo
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::
@end menu
@end ifinfo

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization as a normal graphics library, Initialization as an ascii art renderer, Initialization, Initialization
@comment  node-name,  next,      previous,  up
@section 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 
@code{aa_autoinit} function:

@findex aa_autoinit
@example
aa_context *aa_autoinit(struct aa_hardware_params *@var{params})
@end example

This function initializes the hardware driver and returns @code{aa_context}
structure used by other functions.  @code{NULL} is returned on failure.
Parameter @var{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::
@end menu





@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Easy initialization of AA-lib,Parsing of command line options,Initialization as a normal graphics library,Initialization as a normal graphics library
@comment  node-name,  next,      previous,  up
@subsection Easy initialization of AA-lib



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

@example
#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);
@}
@end example

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.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Parsing of command line options,How does the autodetection work,Easy initialization of AA-lib,Initialization as a normal graphics library
@comment  node-name,  next,      previous,  up
@subsection 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 @code{aa_parseoptions} that uses @code{argc/argv}
variables and parses options for AA-lib. The options for AA-lib are removed
during parsing from @code{argc/argv} so call to aa_parseoptions can preceede
the normal command line options parsing code done by your program.
@code{aa_help} variable contains help about options parsed by @code{aa_parseoptions}. 

@findex aa_parseoptions
@example
int aa_parseoptions(aa_hardwareparams *@var{p}, 
                    aa_renderparams *@var{r}, 
                    int *@var{argc}, char **@var{argv});
@end example

First parameter is used for AA-lib initialization. It specifies the hardware parameters
you require and is altered by @code{aa_parseoptions}. It is expected that your
program will define his prefered parameters first, call @code{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 @code{aa_defparams}
variable in both places (here and as passed to @code{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: @code{1} if OK or @code{0} on error. 

The function returns 1 on sucess and 0 on failure.

@example
#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);
@}
@end example

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

@page
@findex aa_help
Variable @code{aa_help} contains help string similiar to this one:
@example
  -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)
@end example
@tex
\vskip 0pt plus 1filll
@end tex
@page

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node How does the autodetection work,Recommending drivers,Parsing of command line options, Initialization as a normal graphics library
@comment  node-name,  next,      previous,  up
@subsection How does the autodetection work

To fully understand customizing of @code{aa_autoinit} you have to know (at least
something) how does the autodetection work.

All hardware drivers are stored in @code{aa_drivers} array --- array of
pointers to drivers terminated by @code{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
@code{aa_displayrecomended} list. It's a double linked list of strings that are
interpreted as names of drivers. These drivers are tested before
@code{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.


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Recommending drivers,,How does the autodetection work, Initialization as a normal graphics library

@comment  node-name,  next,      previous,  up
@subsection Recommending drivers

Manipulation with recomended drivers (@code{aa_displayrecomended} list) can
be done using macros:

@findex aa_recomendhidisplay
@findex aa_recomendlowdisplay
@findex aa_displayrecomended
@example
aa_recomendhidisplay(@var{name})
aa_recomendlowdisplay(@var{name})
@end example

@code{aa_displayrecomended} is a cyclic list. You can easily add drivers
to the begining (using @code{aa_recomendhidisplay(name)}) or to the end
using @code{aa_recomendlowdisplay(name)}.
In other words @code{aa_recomendhidisplay} inserts with "high priority".
(at the beggining of the list). The check for duplicity is performed. 
Despite @code{aa_recomendhidisplay(name)},
that moves an existing display to the begining, function
@code{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 @code{curses}
keyboard when @code{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 @code{stdin} keyboard driver instead of @code{X11} 
recomended by @code{X11} driver. 

The following piece of code:

@example
aa_recomendhidisplay ("testa1");
aa_recomendlowdisplay("teste1");
aa_recomendhidisplay ("testa2");
aa_recomendlowdisplay("teste2");
aa_recomendlowdisplay("teste1");
aa_recomendhidisplay ("teste1");
@end example

will produce the following list:

@example
teste1, testa2, testa1, teste1 teste2
@end example

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.


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization as an ascii art renderer, Initialization for image saving, Initialization as a normal graphics library, Initialization
@comment  node-name,  next,      previous,  up
@section 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 @code{mem_d} and it's initialization should look like this:


@findex mem_d
@example
 context = aa_init(@var{mem_d},&@var{aa_defparams},NULL);
@end example


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization for image saving,Specifying hardware parameters , Initialization as an ascii art renderer, Initialization
@comment  node-name,  next,      previous,  up
@section Initialization for image saving
@findex save_d

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

@findex aa_savedata
@example
struct aa_savedata @{
      char *name;
      struct aa_format *format;
      FILE *file;
@};
@end example

Field @code{name} contains a filename (without extension).
If you wish to specify file descriptor, you might want to use field
@code{file} instead. Set @code{name} to @code{NULL} in this cases.
Note that then file will not be closed automatically. In @code{name} you
should use following tags:
@table @samp
@item %x
X coordinate of page, if pages enabled otherwise none
@item %y
Y coordinate of page, if pages enabled otherwise none
@item %c
Coordinates in format: @code{_%x_%y}, if pages enabled otherwise none
@item %e
Default extension (like @code{.html})
@end table
@code{Format} is a pointer to @code{aa_format} structure (format information):

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

Conversions is array of strings in format: character, replacement, terminated
by @code{NULL}.

Following code is an example of @code{HTML} format description:

@findex aa_html_format
@example
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
@};
@end example
@findex aa_html_format
@findex aa_html_alt_format
@findex aa_irc_format
@findex aa_zephyr_format
@findex aa_nhtml_format
@findex aa_more_format
@findex aa_ansi_format
@findex aa_hp_format
@findex aa_hp2_format
@findex aa_text_format

Usually you don't need to worry about filling in this large structure since
the formats are already defined: @code{aa_nhtml_format},
@code{aa_html_format}, @code{aa_html_alt_format}, @code{aa_ansi_format}, 
@code{aa_text_format}, @code{aa_more_format}, @code{aa_hp_format}, 
@code{aa_hp2_format}, @code{aa_zephyr_format}, @code{aa_irc_format}.
All formats are collected in @code{aa_formats} array. It is array of
pointers to @code{aa_format} terminated by @code{NULL}

All additional new formats are welcomed.


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Specifying hardware parameters,,Initialization for image saving, Initialization
@comment  node-name,  next,      previous,  up
@section Specifying hardware parameters

In previous examples we used @code{aa_defparams} without description. This
variable says to AA-lib what hardware do you expect. 

@findex aa_hardwareparams
@findex aa_hardware_params
@findex aa_defparams
@example
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;
@};
@end example

Filed @code{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.
@findex font8
@findex fontgl
@findex font14
@findex font9
@findex font16
@findex fontlinux
@findex fontX13
@findex fontX13B
@findex fontX16
Following fonts are available: @code{font8}, @code{font14}, @code{font16}, @code{font9}, @code{fontline}, @code{fontgl}, @code{fontX13}, @code{fontX16}, @code{fontX13B}. 
If you specify @code{NULL} as an argument @code{font16} is used.

Integer @code{supported} contains a mask. Following masks are available:
@findex AA_NORMAL_MASK
@findex AA_DIM_MASK
@findex AA_BOLD_MASK
@findex AA_BOLDFONT_MASK
@findex AA_REVERSE_MASK
@findex AA_EXTENDED
@findex AA_ALL
@findex AA_EIGHT
@code{AA_NORMAL_MASK}, @code{AA_DIM_MASK},
@code{AA_BOLD_MASK}, @code{AA_BOLDFONT_MASK}, @code{AA_REVERSE_MASK}.

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

Other fields are used to specify the display size. If your program
requires a fixed size of the display you should set @code{width},@code{height}
fields (otherwise expect problems ;).
You can also adjust how tolerant AA-lib should be. Minimum is set by
@code{minwidth/minheight}, maximum is set by @code{maxwidth/maxheight}.
Then you can set @code{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 @code{recwidth/recheight}. Note that 
@code{minwidth/minheight} and @code{maxwidth/maxheight} still have an effect 
even if @code{width/height} is zero. 

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

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



@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Drawing image, Rendering , Initialization, Top
@chapter How to draw an image?

@findex aa_imgwidth
@findex aa_imgheight
@findex aa_putpixel
@findex aa_image
AA-lib emulates video-ram so it looks just like a plain memory. It contains
@code{aa_imgheight (context)} lines of @code{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 @code{aa_image(context)} macro.

Note that width and height of videoram differ from physical width/height of
a device (stored in @code{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
@code{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:

@findex aa_setpalette
@findex aa_palette
@example
aa_setpalette(@var{palette}, @var{index}, @var{red}, @var{green}, @var{blue})
@end example

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:

@example
palette[index]=value;
@end example

@findex aa_mmwidth
@findex aa_mmheight
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 @code{aa_mmwidth(context)} and @code{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 !

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Rendering, Flushing, Drawing image, Top
@chapter Rendering of image into ascii-art

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

@findex aa_fastrender
@findex aa_render
@findex aa_renderpalette
@example
void aa_fastrender(aa_context *@var{c}, int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
void aa_render(aa_context * @var{c}, aa_renderparams *@var{p}, 
                      int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2});
void aa_renderpalette(aa_context *@var{c}, aa_palette @var{table},
                      aa_renderparams *@var{p}, 
                      int @var{x1}, int @var{y1}, int @var{x2}, int @var{y2}); 
@end example

@code{x1}, @code{y1}, @code{x2}, @code{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@dots{}@code{aa_scrwidth(context)} or 0@dots{}@code{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 @code{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:

@example
aa_fastrender(context, 0, 0, aa_scrwidth(context), aa_scrheight(context));
@end example

Function @code{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 @code{p}. 
This parameter allows a control of its advanced features. It's a pointer 
to the following structure:

@findex aa_renderparams
@findex aa_defrenderparams
@example
struct aa_renderparams @{
    int bright, contrast;
    float gamma;
    int dither;
    int inversion;
    int randomval;
@};
@end example

Values @code{bright}, @code{contrast}, @code{gamma} let you control the quality 
of the output image. Brightness of range 0@dots{}255 and contrast 0@dots{}127;
dither can be set to one of the following values:
@table @samp
@item AA_NONE
disables dithering
@item AA_ERROR_DISTRIB
enables error distribution dithering
@item AA_FLOYD_S
enables floyd-steinberg dithering
@end table

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 @code{aa_renderpalette} is similiar to @code{aa_render}. The only
difference is that it lets you specify the palette.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Flushing, Keyboard , Rendering, Top
@chapter 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:).

@findex aa_flush
@findex aa_text
@findex aa_attr
@example
void aa_flush(aa_context *@var{c});
@end example

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
@code{aa_text(context)} or @code{aa_attrs(context)} macros. 

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

The @code{aa_attrs} return pointer to array representing additional attribute
for each character.
@findex AA_NORMAL
@findex AA_DIM
@findex AA_BOLD
@findex AA_BOLDFONT
@findex AA_REVERSE
@findex AA_SPECIAL
Attribute buffer can contain following values:
@table @samp
@item AA_NORMAL
for normal characters
@item AA_BOLD
for bold (double bright) characters
@item AA_DIM
for dim (half bright) characters
@item AA_BOLDFONT
for characters displayed using bold font
@item AA_REVERSE
for reversed characters
@item 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.
@end table

For more comfortable output you may use:

@findex aa_puts
@example
void aa_puts(aa_context *@var{c}, int @var{x}, int @var{y}, int @var{attr}, char *@var{s});
int aa_printf(aa_context *@var{c}, int @var{x}, int @var{y}, int @var{attr}, char *@var{fmt}, ...);
@end example

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

@findex aa_gotoxy
@findex aa_hidecursor
@findex aa_showcursor
@example
void aa_gotoxy(aa_context *@var{c}, int @var{x}, int @var{y});
@end example

Some drivers can also support cursor hiding:
@code{aa_hidecursor} or @code{aa_showcursor} functions.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Keyboard, Mouse, Flushing, Top
@chapter 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@dots{}wait till
the next version).


@menu
* Initialization of keyboard::
* Getting events::
@end menu

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization of keyboard, Getting events, Keyboard, Keyboard
@section 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:

@findex aa_autoinitkbd
@findex aa_initkbd
@findex AA_SENDRELEASE
@example
int aa_autoinitkbd(struct aa_context *@var{context}, int @var{mode});
int aa_initkbd(struct aa_context *@var{context}, 
               struct aa_kbddriver *@var{drv}, int @var{mode});
@end example

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:

@findex aa_recomendhikbd
@findex aa_recomendlowkbd
@findex aa_uninitkbd
@example
aa_recomendhikbd(@var{name});
aa_recomendlowkbd(@var{name});
@end example

Close context or use

@example
void aa_uninitkbd(struct aa_context *@var{context});
@end example

to uninitialize a keyboard driver.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Getting events, , Initialization of keyboard, Keyboard
@section Getting events

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

@findex aa_getevent
@findex aa_getkey
@findex AA_NONE
@findex AA_RELEASE
@example
int aa_getevent(aa_context *@var{c}, int @var{wait});
@end example

if @var{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:

@enumerate
@item
ascii code of pressed key (value is lower than 255)
@item
one of the following special keys: AA_UP, AA_DOWN, AA_LEFT, AA_RIGHT,
AA_BACKSPACE, AA_ESC
@item
value higher or equal to AA_UNKNOWN but lower than AA_RELEASE means unknown
key.
@item
two special events AA_MOUSE and AA_RESIZE (will be explained later)
@item
higher value than AA_RELEASE means released key. To get keycode use:
@code{value &= ~AA_RELEASE}.

@end enumerate

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

@example
int aa_getkey(aa_context *@var{c}, int @var{wait});
@end example
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Mouse, Resizing , Keyboard, Top
@chapter Mouse

@findex aa_autoinitmouse
@findex aa_initmouse
@findex AA_MOUSEMOVEMASK
@findex AA_MOUSEPRESSMASK
@findex AA_PRESSEDMOVEMAKS
@findex AA_MOUSEALLMASK
@findex aa_recomendhimouse
@findex aa_recomendlowmouse
@findex aa_uninitmouse
@findex aa_getmouse
@findex aa_hidemouse
@findex aa_showmouse
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 @code{aa_getevent}
function. Then the mouse possition can be obtained using:

@example
void aa_getmouse(aa_context *@var{c}, int *@var{x}, int *@var{y}, int *@var{b});
@end example

@code{X} and @code{y} are reported in screen coordinates (not image ones).
@code{B} contains state of buttons (AA_BUTTON1, AA_BUTTON2, AA_BUTTON3).

@example
void aa_hidemouse(aa_context *@var{c});
void aa_showmouse(aa_context *@var{c});
@end example

This functions should be used to hide/show mouse cursor.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Resizing, Other functions, Mouse, Top
@chapter Resizing of display

@findex AA_RESIZE
@findex aa_resize
@findex aa_resizehandler
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

@example
int aa_resize(aa_context *@var{c});
@end example

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 @code{aa_getkey}
the catch of AA_RESIZE is more complicated and you should use the resize handler.

@example
void aa_resizehandler(aa_context *@var{c}, void (*@var{handler}) (aa_context *));
@end example

Then the resize handler is called by @code{aa_getevent} or @code{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:

@example
aa_resizehandler(aa_context *@var{c}, (void *)aa_resize);
@end example

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

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Other functions, Designing new driver, Resizing, Top
@chapter Other functions

@findex aa_getrenderparams
@example
aa_renderparams *aa_getrenderparams(void);
@end example

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.

@findex aa_registerfont
@example
int aa_registerfont(struct aa_font *@var{f});
@end example

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

@findex aa_setsupported
@example
void aa_setsupported(aa_context *@var{c}, int @var{supported});
@end example

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

@findex aa_setfont
@example
void aa_setfont(aa_context *@var{c}, struct aa_font *@var{font});
@end example

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

@findex aa_edit
@example
void aa_edit(aa_context *@var{c}, int @var{x}, int @var{y}, int @var{size}, char *@var{s}, int @var{maxsize});
@end example

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

@findex aa_createedit
@findex aa_editkey
@example
struct aa_edit *aa_createedit(aa_context *@var{c}, int @var{x}, int @var{y}, 
                              int @var{size}, char *@var{s}, int @var{maxsize});
void aa_editkey(struct aa_edit *@var{e}, int @var{c});
@end example

Event handled version of an editor. @code{aa_createedit} fills in the struct
@code{aa_edit} for the input line and @code{aa_editkey} processes an event for
editor. Can be used by some "user friendly (huh:)" aplications@dots{}.
 
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Designing new driver, Reference, Other functions, Top
@chapter 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.

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

@example
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);
@};
@end example

@deffn Text shortname
@var{Shortname} is an string that contain short name of your driver. Short
name is expected to be one word name like ``@code{linux}''.
@end deffn

@deffn Text name
@var{Name} is an string that contain full name of your driver. It should
contain version etc. like ``@code{Linux console driver version 1.0}''
@end deffn

@deffn 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 @code{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. @xref{Initialization for image saving}.
Just first two fields are used (@code{font} and @code{supported}).
@var{Font} is pointer to font structure used by hardware. This field should be filed
at runtime (see @code{aalinux.c} for example), set statically to one of
aalib's fonts or set to @code{NULL} if hardware does not allow detection of
font (such as text terminals). @var{Supported} is mask of all atributes supported by
your hardware ( @code{AA_NORMAL_MASK}, @code{AA_DIM_MASK}, @code{AA_BOLD_MASK},
@code{AA_BOLDFONT_MASK}, @code{AA_REVERSE_MASK}) and rage of useable
characters (by default just standard ASCII characters are used) use @code{AA_EXTENDED}
if your driver supports all characters (0-255).
@code{AA_ALL} should be used if your driver displays characters instead of
blanks (cr, tab etc..), @code{AA_EIGHT} lets AAlib use characters greater than
128.
@code{Mmwidth} and @code{mmheight} fields should be also set if
is possible to determine physical size of screen/window.
@ref{Specifying hardware parameters}

Last parameter should be used to define pointer that will be later set to
@code{driverdata} field of @code{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 @code{aa_close} if it is non-NULL.

This function should also recomend best available keyboard and mouse drivers.
@xref{How does the autodetection work}.
@end deffn

@deffn Function uninit
This functin uninitializes driver and frees all resources used by it.
@end deffn

@deffn Function getsize
This function returns width and height of screen in characters.
@end deffn

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 @var{print} field is set to @code{NULL} AAlib will call
just flush and expect that driver will update screen automatically
from internal buffers. When both @var{print} and @var{flush} are
non@code{NULL} AAlib will first use @var{print}/@var{setattr}/@var{gotoxy}
to update screen and then call @var{flush}. Note that in case @var{print} is
@code{NULL}, @var{setattr} should be also @code{NULL} but @code{gotoxy} needs
to be non@code{NULL} since it is used to sed hardware cursor.

@deffn Function setattr
Set current attributes
@end deffn

@deffn Function print
Print text at current cursor possition using current attrubutes
@end deffn

@deffn Function gotoxy
Change cursor possition (coordinated begins by 0,0 in top left corner)
@end deffn

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

@deffn Function cursormode
This function is used to enable/disable cursor. 1 means enable, 0 disable.
Should be set to @code{NULL} if your hardware don't support this.
@end deffn

@subsection Keyboard driver
This driver is defined by structure:
@example
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);
@};
@end example
@deffn String shortname
@end deffn
@deffn String name
This fields have similiar as in display drivers.
@end deffn

@deffn Integer flags
This field informs about extensions supported by driver. Currently should be
set to @code{AA_SENDRELEASE} in case driver should inform about key releases
too.
@end deffn

@deffn Function init
Similiar functionality as in display drivers. @var{mode} should be set to 0
or @code{AA_SENDRELEASE} in case application wants to be informed about
key releases too. Note that driver should send releases even @var{mode} is 0.

This function should also recomend best available mouse driver.
@xref{How does the autodetection work}.
@end deffn

@deffn Function uninit
Uninitializes driver
@end deffn

@deffn 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 @code{AA_NONE} of no event is
pending. Function returns also key releases --- like normal keys masked by
@code{AA_RELEASE}. It also recognizes some special keys. @xref{Getting
events}. It should also cooperate with mouse driver and return @code{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.
@end deffn

@subsection Mouse driver
This driver is defined by structure:
@example
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);
@};
@end example

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

@deffn Function getmouse
This function returns coordinates of cursor and mask of buttons (@code{AA_BUTTON1}, @code{AA_BUTTON2}, @code{AA_BUTTON3}). Coordinates are same as for @code{gotoxy} call.
@end deffn

@deffn Function cursormode
This function is used to show/disable mouse cursor.
Should be set to @code{NULL} if not supported.
@end deffn

@include reference.texinfo

@node    Index,     , Reference, Top
@c        node-name,    next, previous,        up
@unnumbered Index of functions, variables, types and constants

@printindex fn

@iftex
@page
@example

                                                                      
                     ,     ._j'.~S@@?_. .  .                           
                        ..!`,`   ' :7x!, .,                           
                      _,`'     ,'': "``~~~~:"\,)., _                  
                  ._yV' ~      ,'.'.,,     ,``~7"\/.,,                
                \_K"~        ., ,.:.',  ,   :':...:..                 
              _~I",        . .:':::`'. ...,:\:::::;.~k,  .            
             . ~,         , :':':.:;. ..:2:z:g\j;j:;:.5t_             
           .(.:.,.,.,, ,, ,'..:':j\::,.:jgaaKKp22r:j::.,~ ,           
          .:::::::::..... ,.:j:::::\:::\jKQQgjq52yj::j::,,:,,         
       (=Cj\\j\jj:j::;:::::_z:jj::j":j:oxQ@@@@x2k2jj5\:::'''.::,        
       _QQQqzj22\:\2jj:21K55?"""::::::'@{"q25ozj\:\;::;:`, ',~:_`      
       ($zpjQzgzqgzj2jo2:::::.:'...''':::jj:::t;":::~:::.:.:;:@{,      
        [QQ@@g@@zQK2j:jj::::..'''',,,,,,,`::::':::::,.,..':.::j::2\     
        [@@@@@@QQ@@QQQ::jj::.....',,,,,,, ,,'':,:.:.@{\\:::z\;:\:jja2@@@},    
        @@@@@@@@@@@@@@Q@@@@yjj::.:...''',,,,, ', ,,'::/:;;qgQzj:KQ\/j":jj2) 
       .@@@@@@@@@@@@@@@@@@@@$gn:::'..''',,, ,,,, ,, ,~:;_;~jKpqQaeq@@Qa2::;~""~
       [@@@@@@@@@@@@@@@@@@@@$@@p::....'', , , ,  ,, ,  ,~"j_ 7$@@@@@@Q~\@@@@@@$@@Qz `~  
        @@@@@@@@@@@@@@$zQ@@Yt:.:.-...'', , ,,, ,  ,  , ~~\,/"@@@@@@Q/@@@@@@pqp      
        @@@@@@@@@@@@h775::j2j\zzz__::.,..',,,,',,.... .:"\z:VVVVH@@B"~       
        =4@@@@@@$@@@}:::j"jjjjzQQ@@@@@@aj:j::....::::j2"::''~'~,   "q],        
        .:$@@@@k:":::::jYn:o@@$f:Cj2\:; ,  ,~"""L@@@{~":: ,    :j`.`       
         ::q@@Q\:::.:::::""""\""\:"::      ,.:.'           :j          
         !::q@@\::..:.:.:::::::":""":            ,         :; ,        
          `,."\::..:.:.:.:.::::""":',                    .`  @@@}        
              \::::.::-:..:-::@{":::'       ' ,           ,            
              .""::::::.:::::"":jj::.,, .  ,:,,,        ~             
              ::""::::::::::::"""::"::,,     ':,,       `             
               :""""::::@{"""""::::: .,      , ,'',,    ~              
                :""":::"""j:jjjjjj""~~~~~~~~~~'`,    ,                
         .__gy"~::":"":":":""::":"::.., ,     ,     , ~' _  ~@{_.      
   .....j=:', ,.:jj":"::::::::":::'` ' ,        ,  ,        ~.;..'. , 
'..:"""j:,   ,,."::"j""""::::::::',,             ,          .:'.:.:.' 
"":~:\"jj:, ,,'::j:::"\"\"@{"":":::,,,,      , ,,           ::'.:':' '-
     "\"jj\.,,.:"::::::""\""\""":"":"::...'',           .::...:.:`    
       "j:2a2::::"":::":""""""""@{@{""":::'',   ,       .:.:':.::`      
.::\":j:j\j2S@@Q\j:"":"::""""@{"""""""::',,          ..:::::.::''.:,':..
jjj@{\\j\@{:j:jo@@@@Qgj"\"""":""""""""::.',, ,, , , .:::::::.::'..::'..:.-
\"j"j::@{jj:\jjjK@@@@@@@@pzj@{@{\"j@{jj\"j:::..',, .,.::::::::::-.:.':: .'``` 
               ~<V@@$@@@@QQgj:"\"""@{"@{:::.:::j::"":::::~```              
@end example
@page
@example

                                 ._;                                  
                        ,   ' ,,..:....~)  .                          
                     _ +   ',,,''.:.::.....',~( ,                     
                   (     ,''''.'.-.:..:'',,,'''::::_.                 
                ,,, , ',''`''':-...:'..'.''''.','::"jY_               
              .+.'.,. ' , ..'....:'',,.`'',','.:::12gQzzJ.            
              :::::~`...'~`'.:::":::'.' '..''...:J5jzz$@@@@zQ]          
            _:j:":._:...::::.:::::.'..::''''',''`:~:q@@$@@@@@@Q_          
           .gQy1gjj:j::::::2\\":::::,','.,'','..;':~:qK@@@@qQh:,        
          .Q@@$gH@@Qzy2::jjjjj@{\j:"::'',  ~`'...',,,.:@{FzpK$@@y:\        
         .@@@@@@QQ@@@@@@QQQzzSn:j\""":::..',,',,,'.''  .'.;:of:n$I::_       
         [@@@@@@@@@@@@@@@@@@@@@@@@oyjjjjj::"::..',,,', , ,,'..,`.:~:::7\:;~       
         [@@@@@@@@@@@@@@@@q$KJ22j::::::..'',, ,  , , ',, , ,  , '`'~-,'!      
         [@@@@@@@@@@@@@@@@@@K""j::::::-..'', , , ,            , , , ',`,9      
         [@@@@@@@@@@@@@@QB:"::::::::...', ' ,     ,       ,      ,,',..      
         [@@@@@@@@@@$5\::::::::::...',,,,, ,, ,           , ',, ': :.      
         [@@@@@@Q@@h@{""::::::::...'',,, ,, ,  ,  , ,  , ,  :''..:::@{!     
         (@@@@@@@@@@j\@{::j:j:_::.'''',,,,,,,,....... ., ,  , ':,:':'3      
        .1@@@@@@@@hj"jjjqQ@@@@$VVV:::..:.,''':\y:"::..',, _,  '::''`.'      
         oYHH@@Qyzj5@{:zzgggzzzQQny:-...~'@{2sH@@$v":.:..'.:: `   ::      
         :::1QQz:y:\jHH@@g@@KQQ@@@@jo;:::(,,'::::'.:,::'`,:<`, ~:, 1      
         +:::@{j::j:::::j"jjoK$Z@@p::   3:,''....,,  ,  . ,  ,'` (      
         (:.:@{""L:::::::::::::"h:"',   ',,,,',,,, ,  .)  , ' , (      
          !::@{\:"L:::::::::::2n"j:., ,  ~)_',,,, , ,.! , , ,  ,       
           t::j@{""J\:zzzzzJ5:"j:::'    ,  '~~VV=V`, , , ,,   ,        
            (:jj\"":::::::-::"j\:::,,,,  ,, ,   , ,  , , .            
               Qj\""":::::::::"H2B\,, ', , ,, ,, , , ,, ,             
               (yj\""""::::::":::::::`  ,  , ,, , , , ,,,1            
                =g\j\":\"""""""::',':', , , , ,,, , ,, ,_Q_           
                 [2jjj\""@{\zggQ@@@@@@KL:::"~:'::', , , ,,,:jj)           
                  @@QQyjj"\:"jj\j::::.:..', , ',, ,,,,,,zy"!           
                  @@@@@@@@Qjj\@{\""::":""~::`, ,,, , ,,,` ,,@@@@             
                  @@@@@@@@@@@@Qj@{@{""":::.''' , ,   , , ', ,, q@@@@            
                  [@@@@@@oK@@@@g\@{\""::..'',, , ,, ,'', , , 1@@qq_          
                    @@@@jjjjq@@@@Qy:j:::::.,',.,`',, , , , .h::Hi,        
               ...Q@@@@@@j\:"jjoK@@@@@@@@Qy2::''',, ,  , , ,  J:::\jy.7)._   
           _.,:.:Q@@@@@@@@@@yj"\"\\joKqK$K\:'.',,, ,, , , ."'::::::;'.'.:7V
      ..(:::::jhz@@@@@@@@@@@@@@Qj\"@{\:jjjjj\::.',, , , , , :''':'":":z::::'..
  _.:.:::jzggQ@@@@@@@@@@@@@@@@@@@@@@ZZj\"@{j@{j"@{:::.',,,,,,,._::.':' : ::@{r:::Vj:\
 :,::::gQ@@@@@@@@@@@@@@@@q@@@@@@@@@@@@@@@@h1fjjj@{j\j:@{::.'',,..jJ\:zgz,::.''.1@}::::p:j
@end example
@end iftex
@contents
@bye