Game Control Plus API
This page gives an overview of the code needed to use this library in your sketch, you should watch the video guides to get the most out of this library. Although the API is very similar to proCONTROLL the real power comes from using configuration files to abstract the system dependant names, so easying the problems associated with distributing applications.
If you are not interested in distributing your application then you don't have to use a configuration file, instead use the device and input names returned by the OS directly. You can use the Pcp_ShowDevices example to find out the names. You can use these system dependant names alongside the any user defined names from a configuration file. The choice is yours.
Inside the Sketch
The first thing to do is declare some global varials e.g.
// This one is essential
ControlIO control;
// You will need some of the following depending on the sketch.
// A ControlDevice might be a joystick, gamepad, mouse etc.
ControlDevice device;
// A device will have some combination of buttons, hats and sliders
ControlButton button;
ControlHat hat
ControlSlider slider;
Before we do anything with the library we need to create the control object. So in the setup method after the call to size(...) add the following line.
control = ControlIO.getInstance(this);This will initialise the library by loading the system specific libraries and scanning for connected devices. If we want to use a device then we must discover the device name and the names of the inputs associated with it. You can use the Pcp_ShowDevices example to find out the names. Once we have the names we can get a handle on the device and interogate its inputs.
device = control.getDevice("Logitech Extreme 3D");If we are using a configuration file then we can ask the library to find a device that has the inputs named in the configuration file with -
Care must be taken when creating the configuration file because many devices use similar names for IO devices so a device might be chosen that is different from the one you expected. One strategy is to include an inut name that is unique to your device so others will be rejected. A second approach is to use a one-off filter so only certain device types are considered, for instance
device = control.filter(GCP.STICK).getDevice("Logitech Extreme 3D");will only consider devices reporting themselves as a joystick. Unfortunately not all devices report themselves as you would expect my Logitech Masters MX2 mouse identifies itself as a keybaord.
UNKNOWN |
MOUSE |
KEYBOARD |
FINGERSTICK |
GAMEPAD |
HEADTRACKER |
RUDDER |
STICK |
TRACKBALL |
TRACKPAD |
WHEEL |
|
These can be combined to give great control over which devices will be codsidered.
filter(??????) |
Devices considered matching |
|---|---|
GCP.KEYBOARD |
keyboards only |
GCP.KEYBOARD | GCP.MOUSE |
keyboards and mice only |
~GCP.STICK |
anything but joysticks |
~(GCP.GAMEPAD | GCP.MOUSE) |
anything but gamepads and mice |
Once we have got the device we can use it to get its inputs e.g.
button = device.getButton("0");
hat = device.getHat("pov");
slider = device.getSlider("x");Buttons are either pressed or not so this statement returns either true or false.
button.pressed();Hats have a number of values that we can retrieve depending on our needs.
hat.getPos();
hat.getX();
hat.getY();This returns zero if it is in the rest position otherwise it returns the value -
| Pos | X | Y | Direction hat is pushed |
|---|---|---|---|
| 1 | -0.707 | -0.707 | Up-left |
| 2 | 0 | -1 | Up |
| 3 | 0.707 | -0.707 | Up-right |
| 4 | 1 | 0 | Right |
| 5 | 0.707 | 0.707 | Down-right |
| 6 | 0 | 1 | Down |
| 7 | -0.707 | 0.707 | Down-left |
| 8 | -1 | 0 | Left |
Alternatively these methods return true if the hat is in the specified direction.
hat.left();
hat.right();
hat.up();
hat.down();Sliders generally return a floating point number in the range -1.0 to 1.0 inclusive.
slider.getValue();The X and Y hat values and the slider values and multiplied by 1.0 (defaualt multiplier) before returnint the value. You can change the multiplier and get the multiplier with -
// Pre multiply the value by 2 before returning it
slider.setMultiplier(2.0);
// Only affects X and Y value for hats
hat.setMultiplier(2.0);
// Get the multipllier value
slider.getMultiplier();
hat.getMultiplier();Sliders at rest should return a value of 0 (zero). As they are analog evices the actual value value is small but rarely zero. This behaviour may not be desirable in which case we can set a tolerance below which any value will be reported as zero.
// Any value in the range -0.1 to 0.1 will be returned as zero
slider.setTolerance(0.1);
// Get the tolerance
slider.getTolerance();This is just an overview for more detailed information see the reference included with the library.