/*
* Copyright (c) 2002-2008 LWJGL Project
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* * Neither the name of 'LWJGL' nor the names of
* its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package org.lwjgl.input;
/**
* A game controller of some sort that will provide input. The controller
* presents buttons and axes. Buttons are either pressed or not pressed. Axis
* provide analogue values.
*
* @author Kevin Glass
*/
public interface Controller {
/**
* Get the name assigned to this controller.
*
* @return The name assigned to this controller
*/
String getName();
/**
* Get the index of this controller in the collection
*
* @return The index of this controller in the collection
*/
int getIndex();
/**
* Retrieve the number of buttons available on this controller
*
* @return The number of butotns available on this controller
*/
int getButtonCount();
/**
* Get the name of the specified button. Be warned, often this is
* as exciting as "Button X"
*
* @param index The index of the button whose name should be retrieved
* @return The name of the button requested
*/
String getButtonName(int index);
/**
* Check if a button is currently pressed
*
* @param index The button to check
* @return True if the button is currently pressed
*/
boolean isButtonPressed(int index);
/**
* Poll the controller for new data. This will also update
* events
*/
void poll();
/**
* Get the X-Axis value of the POV on this controller
*
* @return The X-Axis value of the POV on this controller
*/
float getPovX();
/**
* Get the Y-Axis value of the POV on this controller
*
* @return The Y-Axis value of the POV on this controller
*/
float getPovY();
/**
* Get the dead zone for a specified axis
*
* @param index The index of the axis for which to retrieve the dead zone
* @return The dead zone for the specified axis
*/
float getDeadZone(int index);
/**
* Set the dead zone for the specified axis
*
* @param index The index of hte axis for which to set the dead zone
* @param zone The dead zone to use for the specified axis
*/
void setDeadZone(int index,float zone);
/**
* Retrieve the number of axes available on this controller.
*
* @return The number of axes available on this controller.
*/
int getAxisCount();
/**
* Get the name that's given to the specified axis
*
* @param index The index of the axis whose name should be retrieved
* @return The name of the specified axis.
*/
String getAxisName(int index);
/**
* Retrieve the value thats currently available on a specified axis. The
* value will always be between 1.0 and -1.0 and will calibrate as values
* are passed read. It may be useful to get the player to wiggle the joystick
* from side to side to get the calibration right.
*
* @param index The index of axis to be read
* @return The value from the specified axis.
*/
float getAxisValue(int index);
/**
* Get the value from the X axis if there is one. If no X axis is
* defined a zero value will be returned.
*
* @return The value from the X axis
*/
float getXAxisValue();
/**
* Get the dead zone for the X axis.
*
* @return The dead zone for the X axis
*/
float getXAxisDeadZone();
/**
* Set the dead zone for the X axis
*
* @param zone The dead zone to use for the X axis
*/
void setXAxisDeadZone(float zone);
/**
* Get the value from the Y axis if there is one. If no Y axis is
* defined a zero value will be returned.
*
* @return The value from the Y axis
*/
float getYAxisValue();
/**
* Get the dead zone for the Y axis.
*
* @return The dead zone for the Y axis
*/
float getYAxisDeadZone();
/**
* Set the dead zone for the Y axis
*
* @param zone The dead zone to use for the Y axis
*/
void setYAxisDeadZone(float zone);
/**
* Get the value from the Z axis if there is one. If no Z axis is
* defined a zero value will be returned.
*
* @return The value from the Z axis
*/
float getZAxisValue();
/**
* Get the dead zone for the Z axis.
*
* @return The dead zone for the Z axis
*/
float getZAxisDeadZone();
/**
* Set the dead zone for the Z axis
*
* @param zone The dead zone to use for the Z axis
*/
void setZAxisDeadZone(float zone);
/**
* Get the value from the RX axis if there is one. If no RX axis is
* defined a zero value will be returned.
*
* @return The value from the RX axis
*/
float getRXAxisValue();
/**
* Get the dead zone for the RX axis.
*
* @return The dead zone for the RX axis
*/
float getRXAxisDeadZone();
/**
* Set the dead zone for the RX axis
*
* @param zone The dead zone to use for the RX axis
*/
void setRXAxisDeadZone(float zone);
/**
* Get the value from the RY axis if there is one. If no RY axis is
* defined a zero value will be returned.
*
* @return The value from the RY axis
*/
float getRYAxisValue();
/**
* Get the dead zone for the RY axis.
*
* @return The dead zone for the RY axis
*/
float getRYAxisDeadZone();
/**
* Set the dead zone for the RY axis
*
* @param zone The dead zone to use for the RY axis
*/
void setRYAxisDeadZone(float zone);
/**
* Get the value from the RZ axis if there is one. If no RZ axis is
* defined a zero value will be returned.
*
* @return The value from the RZ axis
*/
float getRZAxisValue();
/**
* Get the dead zone for the RZ axis.
*
* @return The dead zone for the RZ axis
*/
float getRZAxisDeadZone();
/**
* Set the dead zone for the RZ axis
*
* @param zone The dead zone to use for the RZ axis
*/
void setRZAxisDeadZone(float zone);
/** Returns the number of rumblers this controller supports */
int getRumblerCount();
/** Returns the name of the specified rumbler
*
* @param index The rumbler index
*/
String getRumblerName(int index);
/** Sets the vibration strength of the specified rumbler
*
* @param index The index of the rumbler
* @param strength The strength to vibrate at
*/
void setRumblerStrength(int index, float strength);
}