Provided by: libsvga1-dev_1.4.3-31_i386 bug

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.