Man

Command Section
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 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
       <[email protected]>.  Multiple joystick, VC switching support
       and code to glue it into svgalib by Michael Weller <[email protected]
       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)
Command Section