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.