\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

@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.0
@set DATE       Mar 2, 1997

@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@@paru.cas.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.0
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 ?
* 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.
* Index::		Index of functions, types, macros and constants
@end menu


@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
creat 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, Initialization, 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@@horac.ta.jcu.cz}. 

All programs covered under AA-project can be obtained at @code{ftp://ftp.ta.jcu.cz://pub/aa}.

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


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node Initialization, Drawing image , AA-Project, Top
@chapter Initialization
It is possible to initialize AA-lib in various modes.
The main initialization is done by function
@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. 

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

This function also closes the context and uninitializes current driver.
@ifinfo

Three different levels can be initialized:
@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

@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



If you want to initilialize AA-lib as a graphics library it should look like:

@example
#include <stdio.h>
#include <aalib.h>
aa_context *context;
void main(void)
@{
  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). However it is
not a common situation you should check a possible fail.

@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}. @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. (aa_defparams in previous
example). It should contain information about screen size, attributes etc@dots{}
You may also pass NULL to use defaults (aa_defparams variable). The second
argument is set of parameters for rendering. 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. 

@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 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 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 three 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


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

Field @code{name} contains a filename (without extension) and @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_HTML_ESCAPED
                                  AA_C_ESCAPED
                                  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}*/
@};
@end example

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

@findex aa_html_format
@example
struct aa_format aa_html_format =
@{
      79, 25,
      0, 0,
      AA_HTML_ESCAPED,
      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*/
      @{ "%c", "%c", "%c", "%c", "%c", @},
      @{"", "", "<B>", "", "<B>" @},
      @{"", "", "</B>", "", "</B>" @},
@};
@end example
@findex aa_html_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_ansi_format}, @code{aa_text_format},
@code{aa_more_format}, @code{aa_hp_format}, @code{aa_hp2_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 (send `hem to us, you'll be in credits! ;). 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 just by calling
@code{aa_text(context)} or @code{aa_attrs(context)} macros. They can be also
accesed "more" directly (not just via rendering functions). You can fool AA-lib
to display a plain text too. The function used for this purpose have similiar 
format as @code{aa_image(context)} buffer except the fact that they have 
different dimensions (@code{aa_scrwidth(context)} and @code{aa_scrheight(context)}).

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

@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, Index, 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{}.
 
@node    Index,     , Other functions, Top
@c        node-name,    next, previous,        up
@unnumbered Index of functions, variables, types and constants

@printindex fn

@contents
@bye