Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 config-
       ured 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 joy-
       dev = 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 cali-
       brate 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_STD-
       OUT 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 pre-
       processor 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  de-
       vices  upon  a VC switch	s.t. several applications can share joysticks.
       Unfortunately this does not work	during	joystick  calibration.	There-
       fore,  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  ver-
       sion  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,	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  de-
       tail.

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 prop-
       erly.  (This might also be a linux device driver	issue).	Anyway,	is us-
       ing 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 joy-
       stick).

       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 cali-
       brate 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),  joy-
       stick_close(3),	  joystick_update(3),	joystick_sethandler(3),	  joy-
       stick_setdefaulthandler(3), joystick_getnumaxes(3), joystick_getnumbut-
       tons(3),	  joystick_getaxis(3),	 joystick_getbutton(3),	 joystick_but-
       ton1(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.

Svgalib	1.3.0			 14 April 1998		      joystick_init(3)

NAME | SYNOPSIS | DESCRIPTION | GENERAL CONCEPT | CAVEATS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=joystick_init&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help