joystick_init(3)       Svgalib User Manual       joystick_init(3)

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  initial-
       ized.   svgalib(7)  supports several joysticks. The corre-
       sponding device node  names  can  be  configured  in  lib-
       vga(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 joy-
       sticks 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 func-
       tion. 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,  how-
       ever,  it  will  release  the  joystick  devices upon a VC
       switch s.t.  several  applications  can  share  joysticks.
       Unfortunately  this does not work during joystick calibra-
       tion. 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.  joy-
       stick_getaxis(3)  and  joystick_getbutton(3)  plus several
       convenience    macros     joystick_button1|2|3|4,     joy-
       stick_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_getnum-
       buttons(3) query the number of axes and buttons of a  joy-
       stick.

       Finally,  you can (un)register an own handler for the joy-
       stick events with joystick_sethandler(3) and joystick_set-
       defaulthandler(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 fol-
       lowing recalibrations in graphics mode.

SEE ALSO
       svgalib(7),   vgagl(7),   libvga(5),    joytest(6),
       mjoytest(6),  joystick_close(3),  joystick_update(3), joy-
       stick_sethandler(3),  joystick_setdefaulthandler(3),  joy-
       stick_getnumaxes(3),    joystick_getnumbuttons(3),    joy-
       stick_getaxis(3),   joystick_getbutton(3),   joystick_but-
       ton1(3),     joystick_getb1(3),     joystick_x(3),    joy-
       stick_getx(3).

AUTHOR
       The svgalib joystick handler was  mostly  done  by  Daniel
       Engstr\"om  <daniel.engstrom@riksnett.no>.   Multiple joy-
       stick, 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                         1