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.