OpenGLEAN
OpenGLEAN User Support
Home page | Introduction | Documentation | Files | Examples | Proposals | Authors | Links


OpenGLEAN Device Support Development
Summary | CVS | (discussion via home page) | (contact via home page) | (suggestion box) | License | Todo | Bugs

Joystick Access
[OpenGLEAN API Reference]

Collaboration diagram for Joystick Access:


Functions

float glutGetJoystickCenter (int ident, int axis)
float glutGetJoystickDeadBand (int ident, int axis)
float glutGetJoystickMaxRange (int ident, int axis)
float glutGetJoystickMinRange (int ident, int axis)
int glutGetJoystickNotWorking (int ident)
int glutGetJoystickNumAxes (int ident)
int glutGetJoystickNumButtons (int ident)
float glutGetJoystickSaturation (int ident, int axis)
int glutJoystickDetect (void)
void glutJoystickInit (void)
void glutJoystickOpen (int ident)
float glutJoystickReadAxis (int ident, int axis)
int glutJoystickReadButtons (int ident)
void glutJoystickShutdown (void)
void glutSetJoystickCenter (int ident, int axis, float nval)
void glutSetJoystickDeadBand (int ident, int axis, float db)
void glutSetJoystickMaxRange (int ident, int axis, float nval)
void glutSetJoystickMinRange (int ident, int axis, float nval)
void glutSetJoystickSaturation (int ident, int axis, float st)

Detailed Description

Todo:
Generally for many joystick functions: Need to add checks on the ident and axis numbers to be sure that they are in-range.

The old GLUT API for joysticks used timer-based pseudo-events. But ultimately, GLUT would poll the hardware for joystick events. A preferable API would perhaps have been to define functions to allow the application to poll the joystick, and let the application use GLUT timers scheduling the pseudo events, if timer-based checks are desired.

freeglut defined, but did not originally implement an extended API for pollinng the hardware. The definition was informal, in the form of stubbed out functions at the bottom of joystick.c. In 2004, John Fay re-implemented the freeglut joystick support, and added support for these stubbed functions.

OpenGLEAN inherited both of these API forms indirectly through OpenGLUT. OpenGLEAN had intended to expose and support these functions in a separate joystick-only library. In response to what seemed a consensus amongst freeglut developers to move forward with exporting that API, OpenGLEAN opted to expose the same API in order to avoid a compatibilit gap. After a month or two of discussion, but before any release from freeglut with this feature, OpenGLEAN finally added the functions---and literally on the same day, the freeglut project leader turned freeglut away from exporting the API.

On the one hand, this has resulted in OpenGLEAN adding under-designed features that freeglut seemed to want to include. On the other hand, now that freeglut is backing away from their API extension, and gleandev in a very experimental state, gleandev has revised the joystick API substantially.

The old GLUT API is still available in the OpenGLEAN core library as of this writing---and will remain so up through OpenGLEAN 1.0. But a more flexible API is now provided in gleandev.

The new API is two-pronged: One side is a revised set of functions (due to be renamed to avoid historic conflict with freeglut); these form a small constellation of joystick-related functions. The other side is a gleandevGet*() suite of functions, after the style of glGet*(), and likewise a gleandevSet*(). The latter part is more in keeping with OpenGL and the GLUT approach, so will probably be used in preference to the former---though a way to read multiple joystick axes at once (and perhaps support for arrays for reading multiple joystick buttons, rather than bitmasks) may be added.

See the Deprecated API Features section.

Function Documentation

float glutGetJoystickCenter (  int  ident,
int  axis
) 
 

Retrieves the joystick's nominal at-rest position.

Parameters:
ident The joystick of interest.
axis The axis of interest.
Because joysticks are not terribly consistent devices, it is desirable to callibrate for the joystick's actual at-rest position. This function helps you do that.

Note:
axes is not checked, and axes should have for at least glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutSetJoystickCenter(), glutGetJoystickDeadBand()

float glutGetJoystickDeadBand (  int  ident,
int  axis
) 
 

Returns the joystick's "dead band".

Parameters:
ident The joystick in which we are interested.
axis The interesting axis of the joystick.
My understanding of joystick hardware is limited, but apparently there is a region near the center where we want to consider the joystick "stationary", even if it is reading slightly off-center. This is to accomodate imperfections in joysticks.

See also:
glutSetJoystickDeadBand()

float glutGetJoystickMaxRange (  int  ident,
int  axis
) 
 

Get the joystick's maximum range.

Parameters:
ident The joystick in which we are interested.
axis The axis of interest.
Using this function allows your application to calibrate the joystick's maximum range.

Note:
axes is not checked, and axes should have space for at least glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutGetJoysticksaturation()

float glutGetJoystickMinRange (  int  ident,
int  axis
) 
 

Get the joystick's maximum range.

Parameters:
ident The joystick in which we are interested.
axis The axis of interest.
Using this function allows your application to calibrate the joystick's maximum range.

Note:
axes is not checked, and axes should have space for at least glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutGetJoysticksaturation()

int glutGetJoystickNotWorking (  int  ident  ) 
 

Returns 0 if the joystick is working.

Parameters:
ident The joystick that we are interested in.
OpenGLEAN provides a joytick API extension which allows you to directly poll the joysticks.

glutGetJoystickNotWorking() returns 0 if the joystick is working, and non-zero if it is not working. If it is not working, no indication of why it fails will be provided. If a joystick transitions from working to noot working, there is no way to detect it except by querying again.

Note:
Actually returns an opaque integer error-code. A return of 0 apparently means "no error". The possible non-zero codes are undocumented. Probably should return !!error, or (better still) the function should have been called glutGetJoystickWorking() and returned !error. Or...best of all: Add a glutGet() or glutDeviceGet() for it.

int glutGetJoystickNumAxes (  int  ident  ) 
 

Returns the number proportional axes on a joystick.

Parameters:
ident The joystick that we want.
OpenGLEAN provides a joystick API extension which allows you to directly poll the joysticks.

glutGetJoystickNumAxes() queries the OpenGLEAN API for informaation about the number of axes on a given joystick.

See also:
glutGetJoystickNumButtons()

int glutGetJoystickNumButtons (  int  ident  ) 
 

Returns the number of boolean buttons on a joystick.

Parameters:
ident The joystick that we want.
OpenGLEAN provides a joystick API extension which allows you to directly poll the joysticks.

glutGetJoystickNumButtons() queries the OpenGLEAN API for informaation about the number of buttons on a given joystick.

See also:
glutGetJoystickNumAxes()

float glutGetJoystickSaturation (  int  ident,
int  axis
) 
 

Get the joystick's saturation.

Parameters:
ident The joystick in which we are interested.
axis The interesting axis of the joystick.
Using this function allows your application to query the joystick's saturation.

See also:
glutSetJoystickSaturation()

int glutJoystickDetect (  void   ) 
 

Returns 0 if there are no joysticks.

Through this function you can probe to see if there are one or more detectable joysticks that OpenGLEAN can talk to.

Note:
Probably should return the number of joysticks.

Here is the call graph for this function:

void glutJoystickInit (  void   ) 
 

Initializes the joystick portion of gleandev.

This function is used to set up the joystick access. The current behavior is to just call glutJoystickOpen() twice; once with each of the joystick descriptors of 0 and 1.

You are presently encouraged to call this function to initialize the joystick support. More likely in the future you will be expected to explicitly open joysticks and record the resulting identifiers.

Todo:
If there is any library-wide initializion to do, it should be in a function that is not joystick-specific. Library-wide initialization should not be presuming exactly 2 joysticks. So this function should probably vanish, though in practice it is presently required.

Here is the call graph for this function:

void glutJoystickOpen (  int  ident  ) 
 

Opens a joystick by identifier number.

Parameters:
ident OpenGLEAN follows the general GLUT practice of using opaque integer handles, modeled after UNIX file descriptors, for tagging objects such as windows and joysticks.
Perhaps a bit shortsightedly, glutJoystickOpen() has the caller request the specific joystick descriptor, rather than receiving it from the API.

Todo:
Probably should either dispense with the explicit open call, or else have the open call return the descriptor. Possibly allow the client to have some say over what kind of joystick is being sought, as with windows. (E.g., number of axes could be a client criteria. Or possibly the client could even prefer/require a USB joystick, letting the client first request USB sticks, then after opening all that it can, switch to unqualified joysticks.) Certainly, as long as the client is requesting the joystick by number, there needs to be a way to (a) find out how many joysticks are available and (b) indicate success/failure.

float glutJoystickReadAxis (  int  ident,
int  axis
) 
 

Read the corrected joystick axes data.

Parameters:
ident Joystick identifier.
axis The joystick axis of interest.
This function allows you to force gleandev to poll a selected joystick axes for information.

Todo:
Should provide a means to store the joystick data for all axes and require an explicit "nudge" to re-read the data. Re-reading all axes, correcting them, then throwing away all but one axis's worth of information seems silly. However, for now I'm willing to assume that there are no significant performance impacts. Then again, maybe oghJoystickRawRead() can be made to only read selected bits of info?

int glutJoystickReadButtons (  int  ident  ) 
 

Read the joystick button data.

Parameters:
ident Joystick identifier.
This function allows you to force gleandev to poll a selected joystick device for button information.

The returned value is a bit-mask, presently. Probably should be unsigned. Because of C's limitations, the exact number of buttons supported by this API depends upon your compiler.

Todo:
Should provide a means to store the joystick data for all axes and require an explicit "nudge" to re-read the data. Re-reading all axes, correcting them, then throwing away all but the button information seems silly. However, for now I'm willing to assume that there are no significant performance impacts. Then again, maybe oghJoystickRawRead() can be made to only read selected bits of info?

void glutJoystickShutdown (  void   ) 
 

Releases joystick resources.

gleandev may have set up some internal resources or received exclusive access to system resources. When you are done with gleandev, you should close it down properly. This function closes all gleandev joystick resources.

Todo:
Maybe instead just close inidividual joysticks? And/or have a global gleandevShutdown() that supports all devices?

void glutSetJoystickCenter (  int  ident,
int  axis,
float  nval
) 
 

Sets the joystick's nominal at-rest position.

Parameters:
ident The joystick of interest.
axis The axis of interest.
nval New value for the center position on the axis.
Because joysticks are not terribly consistent devices, it is desirable to callibrate for the joystick's actual at-rest position. This function helps you do that.

Note:
axes is not checked, and axes should have at least glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutGetJoystickCenter(), glutSetJoystickDeadBand()

void glutSetJoystickDeadBand (  int  ident,
int  axis,
float  db
) 
 

Set the joystick's deadband.

Parameters:
ident The joystick in which we are interested.
axis The interesting axis of the joystick.
db The new deadband setting.
Using this function allows your application to calibrate the joystick's deadband.

See also:
glutGetJoystickDeadBand()

void glutSetJoystickMaxRange (  int  ident,
int  axis,
float  nval
) 
 

Set the joystick's maximum range.

Parameters:
ident The joystick in which we are interested.
axis Which axis to callibrate.
nval The new maximum range value.
Using this function allows your application to calibrate the joystick's maximum range.

Note:
axes is not checked, and axes should have at least as glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutGetJoysticksaturation()

void glutSetJoystickMinRange (  int  ident,
int  axis,
float  nval
) 
 

Set the joystick's minimum range.

Parameters:
ident The joystick in which we are interested.
axis Which axis to callibrate.
nval The new minimum range value.
Using this function allows your application to calibrate the joystick's minimum range.

Note:
axes is not checked, and axes should have at least as glutGetJoystickNumAxes(ident) worth of float values.
See also:
glutGetJoystickMinRange(), glutSetJoystickMaxRange()

void glutSetJoystickSaturation (  int  ident,
int  axis,
float  st
) 
 

Set the joystick's saturation.

Parameters:
ident The joystick in which we are interested.
axis The interesting axis of the joystick.
st The new saturation setting.
Using this function allows your application to calibrate the joystick's saturation.

See also:
glutGetJoystickSaturation()




SourceForge.net Logo Supported in part by SourceForge.net.

Generated on Fri Sep 9 18:01:36 2005 for gleandev by doxygen 1.4.3
The OpenGLEAN project is hosted in part by SourceForge.