NAME

       joystick_init - open a joystick

SYNOPSIS

       #include <vgajoystick.h>
       typedef void (*__joystick_output) (const char *msg);

       int joystick_init(int joydev, __joystick_output jo);

DESCRIPTION

       This  function  opens  a joystick device. A negative value is returned on failure, otherwise the joystick
       was initialized.  svgalib(7) supports several joysticks. The  corresponding  device  node  names  can  be
       configured in libvga.config(5).

       The joydev parameter indicates which joystick is to be initialized. As of this writing svgalib support up
       to  four  joysticks joydev = 0 to joydev = 3, although I'm not aware of hardware and kernel drivers which
       handle more than joysticks 0 and 1.

       It is strongly encouraged that your program allows the user to calibrate the joystick. This is controlled
       by the jo parameter. If it is NULL, no calibration is performed. Otherwise, calibration is performed  and
       instructions  are  printed to the user by calling the user supplied jo function. It is the responsibility
       of this function to print the NUL and NL terminated message pointed to by msg to the  user.  The  message
       might contain embedded NL characters and will not extend 256 characters including the terminating NUL.

       Usually  an  fputs(msg,  stdout);  followed  by fflush(stdout); will do, but for your convenience you can
       perform the same by passing JOY_CALIB_STDOUT for jo.  gl_printf(3) is well suited for this job  as  well.
       However, it needs some font setup first, so we do not provide a special preprocessor constant.

       It is valid to initialize an already initialized joystick. This allows you to recalibrate the joystick at
       any time. The module supports older version 0.* as well as newer version 1.* joystick device protocols.

GENERAL CONCEPT

       The joystick module is basically independent from the rest of svgalib. You can easily use it in text mode
       only  (but  why  would  you  do that?). If used in a graphics mode, however, it will release the joystick
       devices upon a VC switch s.t. several applications can share joysticks. Unfortunately this does not  work
       during  joystick  calibration.  Therefore, you should lock the VC with vga_lockvc(3) while calibrating in
       graphics mode.

       Also, when using joysticks in textmode only, svgalib won't detect VC switches  and  joysticks  cannot  be
       shared among applications.

       joystick_close(3) releases opened joysticks.

       joystick_update(3)  queries the joysticks for position changes. Note that you must busy wait for joystick
       events.  At least the older version 0.* joystick devices do not allow to sleep and get informed about new
       joystick events. Basically, this is a PC hardware issue in the first place.  Therefore,  vga_waitevent(3)
       does  not know about joysticks. To use it, you must make it timeout after a few ms and actively query the
       joystick for updates.

       By default a handler deals with the joystick events.  joystick_getaxis(3) and joystick_getbutton(3)  plus
       several    convenience   macros   joystick_button1|2|3|4,   joystick_getb1|2|3|4,   joystick_x|y|z,   and
       joystick_getx|y|z allow to query the current status of the joystick (as it was determined during the last
       joystick_update() call).

       The functions joystick_getnumaxes(3) and joystick_getnumbuttons(3) query the number of axes  and  buttons
       of a joystick.

       Finally,  you  can  (un)register  an  own handler for the joystick events with joystick_sethandler(3) and
       joystick_setdefaulthandler(3)

       The simple text demo joytest(6) and the more complex graphical mjoytest(6)  demo  show  the  use  of  the
       joystick package in some more detail.

CAVEATS

       This  function  is  only  available  in ELF versions of svgalib. Due to backwards compatibility issues it
       cannot be used with shared a.out libs.

       Certain game ports seem to be unable to detect missing joysticks properly.  (This might also be  a  linux
       device  driver  issue).  Anyway,  is  using  the  joystick interface, allow a user of your application to
       specify the number of joysticks to be used as well as to bail out the joystick calibration  (when  he  is
       not able to press a button on a missing joystick).

       Usually  <Ctrl>-C  works,  but  you  should  not rely too much on it, as it can be disabled. As a general
       guideline, maybe try to open and calibrate joysticks while still in textmode. <Ctrl>-C will usually still
       work then. If this succeeds, you may assume a joystick is  there  for  any  following  recalibrations  in
       graphics mode.

SEE ALSO

       svgalib(7),  vgagl(7),  libvga.config(5), joytest(6), mjoytest(6), joystick_close(3), joystick_update(3),
       joystick_sethandler(3), joystick_setdefaulthandler(3), joystick_getnumaxes(3), joystick_getnumbuttons(3),
       joystick_getaxis(3),  joystick_getbutton(3),   joystick_button1(3),   joystick_getb1(3),   joystick_x(3),
       joystick_getx(3).

AUTHOR

       The  svgalib  joystick  handler  was  mostly  done  by  Daniel  Engstr\"om <daniel.engstrom@riksnett.no>.
       Multiple joystick, VC switching support and code to glue it into svgalib by Michael  Weller  <eowmob@exp-
       math.uni-essen.de>. Part of the code is based on code from C. Smith and Vojtech Pavlik.

Svgalib 1.3.0                                     14 April 1998                                 joystick_init(3)