Joystick interface tutorial

Transcription

1 Joystick interface tutorial Using the JSAPI through ʻCʼ 1 Example usage in C (using callbacks) 3 Using JSAPI through Java 4 Example usage in Java (using callbacks) 5 Calibrating the joystick 6 Using the joystick API (JSAPI) is a relatively simple process. It places few constraints on the developer, and provides access to the x and y translational axes, the z rotational axis, and the first slider element of a USB joystick. The JSAPI is written such that, should more elements be desired, only the JSAPI code need be modified; the user code would only need to be updated if they desired to use the new features. Using the JSAPI through ʻCʼ Any program that makes use of the JSAPI must be sure to include the js_api.h. This file contains the function prototypes for all public functions of the JSAPI and it provides full documentation on what each function does. Please notice that all JSAPI functions are prefixed with the characters js in order to provide a semblance of namespace for pure C programming. Next, before making use of any of the fun features of the JSAPI, a program must be sure to first call jsopen(). This function initializes the backend of the JSAPI. The jsopen() function requires the name of a joystick to open. A program has two choices for that name: it can pass a name that was retrieved from the jsgetjoysticknames() function, or it can take its chances and pass NULL to the function, at which point the jsopen() function will open the first joystick that it finds. The problem with this, is that the underlying library may confuse non-joystick devices for joysticks (e.g. a keyboard). The jsopen() (and possibly the jsgetjoysticknames()) function must be called before any of the other functions provided by the JSAPI. If it is not, the behavior of those other functions is undefined. For interrupt driven functionality, it is recommended to call jsregistercallback() followed by jsmain() or jsmainnonblocking(). The jsregistercallback() function registers a callback function with the JSAPI that will be called whenever the JSAPI polls the joystick device. This callback function must be of the JS_CALLBACK type: a function pointer to a function taking a JoystickInputs struct as its parameter (JoystickInputs is defined in js_api.h). Page 1 of 6

2 The jsmain... functions initiate and run the event loop used by the JSAPI to perform polling events. One of these functions must be called before device polling can take place. The difference between jsmain() and jsmainnonblocking() is simple: the jsmain() function runs the JSAPI main event loop without ever returning (a call to jsmain() effectively blocks forever), while a call to jsmainnonblocking() runs the main loop in a separate thread and returns control to the caller almost immediately. An example program that uses callbacks follows. It simply prints out the received joystick values to stdout. It also registers a signal handler to catch the interrupt signal so that the program can call the jsclose() function, which closes the JSAPI nicely, and helps ensure the stability of the operating system. It does not ask the user which joystick to open, instead acting naively. The JSAPI provides greater functionality than shown or described here (such as non-interrupt driven polling and the ability to change the polling interval), and the js_api.h file should be consulted for full documentation. Page 2 of 6

3 Example usage in C (using callbacks) #include js_api.h #include <stdio.h> #include <unistd.h> #include <stdlib.h> void signalhandler( int sig ) { printf( "Interrupted\n" ); jsclose(); _exit( 1 ); void callback( JoystickInputs inputs ) { // Simply print out all of the input values. printf( "X: % 4d\tY: % 4d\tZ: % 4dS: % 4d\n", inputs.x_trans, inputs.y_trans, inputs.z_rot, inputs.slider_0 ); int main( int argc, char **argv ) { signal( SIGINT, signalhandler ); // This program will take its chances. A good program would call // // char **names = jsgetjoysticknames(); // // ask the user to which joystick to use, and then call jsopen( names[i] ); jsopen( NULL ); // Register the callback. jsregistercallback( callback ); // Start and enter the main joystick event loop. This function will never // return. jsmain(); Page 3 of 6

4 Using JSAPI through Java Use of the JSAPI through Java is extremely similar to C. The main difference is in how callbacks are setup. An example program that makes use of the JSAPI is included in the code repository at code/js_api/swig/test/testopengl.java. To setup JSAPI callbacks in Java, an object implementing the JSCallbackInterface must be passed to the JSAPI. This is done through the joysticksetcallback() function. This process is equivalent to calling the jsregistercallback() function in C. Once the joysticksetcallback() function has been called, the object passed to it will have its joystickcallback() function called whenever the joystick state updates. An example class (JavaJSAPICallback) is provided with the repository that implements the JSCallbackInterface and provides additional functionality, allowing multiple objects to behave as callbacks. Though it s recommended, it is not required for this class to be used. The JSCallbackInterface.java file should be consulted for the use of the JoystickInputs class. The JoystickInputs class is automatically generated by the SWIG tool to wrap around the JoystickInputs struct defined in js_api.h. The SWIG tool creates getter and setter functions for the struct, which changes its interface just a little bit. This ends up meaning that, if we say that obj is an object of type JoystickInputs, instead of accessing its x_trans field using obj.x_trans, we use obj.getx_trans(). An example program that uses callbacks follows. Page 4 of 6

5 Example usage in Java (using callbacks) public class JavaTest implements JSCallbackInterface { public JavaTest() { // This is the callback function that will be called every time the // joystick state updates. public void joystickcallback( JoystickInputs inputs ) { System.out.println( X: + inputs.getx_trans() + + Y: + inputs.gety_trans() + + Z: + inputs.getz_rot() + + S: + inputs.getslider_0() ); public static void main( String args[] ) { // The JSAPI library must be loaded. try { System.loadLibrary( js_api ); catch (UnsatisfiedLinkError e) { // If the library failed to load (because either the JSAPI library // could not be found, or one of its dependencies could not be found), // then print an error and exit. System.err.println( e ); System.exit( 1 ); JavaTest callback_obj = new JavaTest(); // The JavaJSAPICallback object will be the one that is _actually_ // registered with the JSAPI. This isn t necessary, especially in this // simple example, but it demonstrates the use of JavaJSAPICallback. JavaJSAPICallback callbacks = new JavaJSAPICallback(); callbacks.register( callback_obj ); // We use the naive approach of opening the first joystick found (which // may not actually be a joystick) in order to keep the example concise. JSAPI.jsOpen( null ); JSAPI.joystickSetCallback( callbacks ); JSAPI.jsMain(); Page 5 of 6

6 Calibrating the joystick When first used, the joystick may not be calibrated properly. This could mean anything from values are off-center to the x-axis is mapped to the z-axis and vice versa. The first step in fixing this should be to run any calibration program the operating system may have (e.g. jscal in linux). Next, within the program using the JSAPI, the jsstartcalibration() and jsstopcalibration() functions should be used. The JSAPI is only capable of calibrating a single axis at a time. This is due to the possibility that axis mappings have been swapped. Because of this limitation, the calibration process should involve several pairs of calls to jsstartcalibration() and jsstopcalibration(). Calling jsstartcalibration() will halt the use of the callback function temporarily until a corresponding call to jsstopcalibration() occurs. For an example of how to perform joystick calibration in C, see the thread_main.c test program at code/js_api/ in the P09201 repository. For an example of how to perform calibration in Java, see the TestOpenGL.java test program at code/js_api/swig/test in the P09201 repository. Page 6 of 6