joystick_init(3) Svgalib User Manual joystick_init(3)
NAME
joystick_init - open a joystick
SYNOPSIS#include<vgajoystick.h>typedefvoid(*__joystick_output)(constchar*msg);intjoystick_init(intjoydev,__joystick_outputjo);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.
GENERALCONCEPT
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.
SEEALSOsvgalib(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