GNU Info
(aalib.info)Designing new driver
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.
Display driver
--------------
Display driver is the most significant driver (of course) so it is
recomended to implement it first. Its structure is as follows:
struct aa_driver {
char *shortname, *name;
int (*init) (struct aa_hardware_params *, void *, struct aa_hardware_params);
void (*uninit) (struct aa_context *);
void (*getsize) (struct aa_context *, int *, int *);
void (*setattr) (struct aa_context *, int);
void (*print) (struct aa_context *, char *);
void (*gotoxy) (struct aa_context *,
int, int);
void (*flush) (struct aa_context *);
void (*cursormode) (struct
aa_context *, int);
};
- Text: shortname
SHORTNAME is an string that contain short name of your driver.
Short name is expected to be one word name like "`linux'".
- Text: name
NAME is an string that contain full name of your driver. It should
contain version etc. like "`Linux console driver version 1.0'"
- Function: init
This function is expected to initialize driver. It returns 0 if
failed or 1 if driver is initialized. Note that driver can't
produce any garbage when failed since AAlib will try to initialize
other driver. First parameter specifies hardware parameters that
user expect. Structure contain mask of attributes and recomended
size. Mechanizm of handling sizes is described in section. Second
parameter is pointer to user data that should be passed by
application. It is `NULL' by default. Last is pointer to
hardware_params structure, where driver will put parameters of
initialized device. This structure holds information about
atributes and parameters supported by your driver. Note:
Initialization for image saving. Just first two fields are used
(`font' and `supported'). FONT is pointer to font structure used
by hardware. This field should be filed at runtime (see
`aalinux.c' for example), set statically to one of aalib's fonts
or set to `NULL' if hardware does not allow detection of font
(such as text terminals). SUPPORTED is mask of all atributes
supported by your hardware ( `AA_NORMAL_MASK', `AA_DIM_MASK',
`AA_BOLD_MASK', `AA_BOLDFONT_MASK', `AA_REVERSE_MASK') and rage of
useable characters (by default just standard ASCII characters are
used) use `AA_EXTENDED' if your driver supports all characters
(0-255). `AA_ALL' should be used if your driver displays
characters instead of blanks (cr, tab etc..), `AA_EIGHT' lets
AAlib use characters greater than 128. `Mmwidth' and `mmheight'
fields should be also set if is possible to determine physical
size of screen/window. Note: Specifying hardware parameters
Last parameter should be used to define pointer that will be later
set to `driverdata' field of `aa_context'. If driver needs some
additional data, it should alloc driverdata structure, that will
hold this data. AAlib will automatically free this pointer at
`aa_close' if it is non-NULL.
This function should also recomend best available keyboard and
mouse drivers. Note: How does the autodetection work.
- Function: uninit
This functin uninitializes driver and frees all resources used by
it.
- Function: getsize
This function returns width and height of screen in characters.
There is two alternate ways to implement screen output. First way is
commonly used by text libraries - print/gotoxy/setattr mechanizm.
Second one is flush. Flush should be fast function that display AAlibs
internal buffer to screen. This way is preffered. In case PRINT field
is set to `NULL' AAlib will call just flush and expect that driver will
update screen automatically from internal buffers. When both PRINT and
FLUSH are non`NULL' AAlib will first use PRINT/SETATTR/GOTOXY to update
screen and then call FLUSH. Note that in case PRINT is `NULL', SETATTR
should be also `NULL' but `gotoxy' needs to be non`NULL' since it is
used to sed hardware cursor.
- Function: setattr
Set current attributes
- Function: print
Print text at current cursor possition using current attrubutes
- Function: gotoxy
Change cursor possition (coordinated begins by 0,0 in top left
corner)
- Function: flush
Flush current screen to output. In case you use AAlibs internal
buffers to update screen (not PRINT) mechanizm get pointer to text
and attribute buffer using `aa_text' and `aa_attr' functions.
Buffers are formated into "normal" videoram - starting in top left
corner and continue like english text. Attribute buffer should
contain `AA_NORMAL', `AA_BOLD', `AA_BOLDFONT', `AA_DIM',
`AA_REVERSE' and `AA_SPECIAL' values.
- Function: cursormode
This function is used to enable/disable cursor. 1 means enable, 0
disable. Should be set to `NULL' if your hardware don't support
this.
Keyboard driver
---------------
This driver is defined by structure:
struct aa_kbddriver {
char *shortname, *name;
int flags;
int (*init) (struct aa_context *, int mode);
void (*uninit) (struct aa_context *);
int (*getkey) (struct aa_context *, int);
};
- String: shortname
- String: name
This fields have similiar as in display drivers.
- Integer: flags
This field informs about extensions supported by driver. Currently
should be set to `AA_SENDRELEASE' in case driver should inform
about key releases too.
- Function: init
Similiar functionality as in display drivers. MODE should be set
to 0 or `AA_SENDRELEASE' in case application wants to be informed
about key releases too. Note that driver should send releases even
MODE is 0.
This function should also recomend best available mouse driver.
Note: How does the autodetection work.
- Function: uninit
Uninitializes driver
- Function: getkey
This funtion return key. Second parameters is set to 1 if function
is expected to wait for key or 0 if is expected to return
`AA_NONE' of no event is pending. Function returns also key
releases -- like normal keys masked by `AA_RELEASE'. It also
recognizes some special keys. Note: Getting events. It should
also cooperate with mouse driver and return `AA_MOUSE' if mouse
event is pending. Second way is to ignore wait parameters and
never wait for key when mouse driver is enabled. This way is not
recomended for multitasking enviroments.
Mouse driver
------------
This driver is defined by structure:
struct aa_mousedriver {
char *shortname, *name;
int flags;
int (*init) (struct aa_context *, int mode);
void (*uninit) (struct aa_context *);
void (*getmouse) (struct aa_context *, int *x, int *y, int *buttons);
void (*cursormode) (struct aa_context *,int);
};
First five fields has very similiar meaning to ones in keyboard
driver. `flags' is set to all events driver should report about:
`AA_MOUSEMOVEMASK', `AA_MOUSEPRESSMASK' and `AA_PRESSEDMOVEMAKS'. All
of them are colected into `AA_MOUSEALLMASK'. If driver has
showcursor/hidecursor functionality set also flag `AA_HIDECURSOR'. MODE
parameter to INIT function should be set to mask of events application
wants to know about, like in FLAGS.
- Function: getmouse
This function returns coordinates of cursor and mask of buttons
(`AA_BUTTON1', `AA_BUTTON2', `AA_BUTTON3'). Coordinates are same
as for `gotoxy' call.
- Function: cursormode
This function is used to show/disable mouse cursor. Should be set
to `NULL' if not supported.
automatically generated by info2www version 1.2.2.9