1joystick_init(3) Svgalib User Manual joystick_init(3)
2
6 joystick_init - open a joystick
7
9 #include <vgajoystick.h>
10 typedef void (*__joystick_output) (const char *msg);
11 int joystick_init(int joydev, __joystick_output jo);
13
16 This function opens a joystick device. A negative value is returned on
17 failure, otherwise the joystick was initialized. svgalib(7) supports
18 several joysticks. The corresponding device node names can be config‐
19 ured in libvga.config(5).
20 The joydev parameter indicates which joystick is to be initialized. As
22 of this writing svgalib support up to four joysticks joydev = 0 to joy‐
23 dev = 3, although I'm not aware of hardware and kernel drivers which
24 handle more than joysticks 0 and 1.
25 It is strongly encouraged that your program allows the user to cali‐
27 brate the joystick. This is controlled by the jo parameter. If it is
28 NULL, no calibration is performed. Otherwise, calibration is performed
29 and instructions are printed to the user by calling the user supplied
30 jo function. It is the responsibility of this function to print the NUL
31 and NL terminated message pointed to by msg to the user. The message
32 might contain embedded NL characters and will not extend 256 characters
33 including the terminating NUL.
34 Usually an fputs(msg, stdout); followed by fflush(stdout); will do, but
36 for your convenience you can perform the same by passing JOY_CALIB_STD‐
37 OUT for jo. gl_printf(3) is well suited for this job as well. However,
38 it needs some font setup first, so we do not provide a special pre‐
39 processor constant.
40 It is valid to initialize an already initialized joystick. This allows
42 you to recalibrate the joystick at any time. The module supports older
43 version 0.* as well as newer version 1.* joystick device protocols.
44
47 The joystick module is basically independent from the rest of svgalib.
48 You can easily use it in text mode only (but why would you do that?).
49 If used in a graphics mode, however, it will release the joystick
50 devices upon a VC switch s.t. several applications can share joysticks.
51 Unfortunately this does not work during joystick calibration. There‐
52 fore, you should lock the VC with vga_lockvc(3) while calibrating in
53 graphics mode.
54 Also, when using joysticks in textmode only, svgalib won't detect VC
56 switches and joysticks cannot be shared among applications.
57 joystick_close(3) releases opened joysticks.
59 joystick_update(3) queries the joysticks for position changes. Note
61 that you must busy wait for joystick events. At least the older ver‐
62 sion 0.* joystick devices do not allow to sleep and get informed about
63 new joystick events. Basically, this is a PC hardware issue in the
64 first place. Therefore, vga_waitevent(3) does not know about joysticks.
65 To use it, you must make it timeout after a few ms and actively query
66 the joystick for updates.
67 By default a handler deals with the joystick events. joy‐
69 stick_getaxis(3) and joystick_getbutton(3) plus several convenience
70 macros joystick_button1|2|3|4, joystick_getb1|2|3|4, joystick_x|y|z,
71 and joystick_getx|y|z allow to query the current status of the joystick
72 (as it was determined during the last joystick_update() call).
73 The functions joystick_getnumaxes(3) and joystick_getnumbuttons(3)
75 query the number of axes and buttons of a joystick.
76 Finally, you can (un)register an own handler for the joystick events
78 with joystick_sethandler(3) and joystick_setdefaulthandler(3)
79 The simple text demo joytest(6) and the more complex graphical
81 mjoytest(6) demo show the use of the joystick package in some more
82 detail.
83
86 This function is only available in ELF versions of svgalib. Due to
87 backwards compatibility issues it cannot be used with shared a.out
88 libs.
89 Certain game ports seem to be unable to detect missing joysticks prop‐
91 erly. (This might also be a linux device driver issue). Anyway, is
92 using the joystick interface, allow a user of your application to spec‐
93 ify the number of joysticks to be used as well as to bail out the joy‐
94 stick calibration (when he is not able to press a button on a missing
95 joystick).
96 Usually <Ctrl>-C works, but you should not rely too much on it, as it
98 can be disabled. As a general guideline, maybe try to open and cali‐
99 brate joysticks while still in textmode. <Ctrl>-C will usually still
100 work then. If this succeeds, you may assume a joystick is there for any
101 following recalibrations in graphics mode.
102
105 svgalib(7), vgagl(7), libvga.config(5), joytest(6), mjoytest(6), joy‐
106 stick_close(3), joystick_update(3), joystick_sethandler(3), joy‐
107 stick_setdefaulthandler(3), joystick_getnumaxes(3), joystick_getnumbut‐
108 tons(3), joystick_getaxis(3), joystick_getbutton(3), joystick_but‐
109 ton1(3), joystick_getb1(3), joystick_x(3), joystick_getx(3).
110
113 The svgalib joystick handler was mostly done by Daniel Engstr\"om
114 <daniel.engstrom@riksnett.no>. Multiple joystick, VC switching support
115 and code to glue it into svgalib by Michael Weller <eowmob@exp-
116 math.uni-essen.de>. Part of the code is based on code from C. Smith and
117 Vojtech Pavlik.
118Svgalib 1.3.0 14 April 1998 joystick_init(3)