Go to the previous, next section.

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

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. See section 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. section 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. See section 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 nonNULL 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 nonNULL 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

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} 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. See section 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. See section 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

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.

Go to the previous, next section.