1joystick_init(3)              Svgalib User Manual             joystick_init(3)
2
3
4

NAME

6       joystick_init - open a joystick
7

SYNOPSIS

9       #include <vgajoystick.h>
10       typedef void (*__joystick_output) (const char *msg);
11
12       int joystick_init(int joydev, __joystick_output jo);
13
14

DESCRIPTION

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
21       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
26       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
35       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
41       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
45

GENERAL CONCEPT

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
55       Also, when using joysticks in textmode only, svgalib  won't  detect  VC
56       switches and joysticks cannot be shared among applications.
57
58       joystick_close(3) releases opened joysticks.
59
60       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
68       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
74       The   functions  joystick_getnumaxes(3)  and  joystick_getnumbuttons(3)
75       query the number of axes and buttons of a joystick.
76
77       Finally, you can (un)register an own handler for  the  joystick  events
78       with joystick_sethandler(3) and joystick_setdefaulthandler(3)
79
80       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
84

CAVEATS

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
90       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
97       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
103

SEE ALSO

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
111

AUTHOR

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.
118
119
120
121Svgalib 1.3.0                    14 April 1998                joystick_init(3)
Impressum