NAME
Controls Assignment SDK
COPYRIGHT
The Logitech Controls Assignment SDK, including all accompanying documentation, is protected by intellectual property laws. All rights not expressly granted by Logitech are reserved.
PURPOSE
The Controls Assignment SDK enables developers to easily and
quickly create a bulletproof solution for assigning any controls
of any game controller to any functionality in their PC game. The
wrapper also enables to directly calculate combined values for
pairs of game actions so the developer can directly feed the
values into his game.
The wrapper is an addition to Microsoft's DirectInput and XInput
and supports both.
See the following files to get started:
- readme.txt: tells you how to get started.
- Doc/SampleInGameImplementation.cpp: shows line by line how to
use the Controls Assignment SDK's interface to implement
control assignment in your game.
- Samples/ControlsAssignmentSDKDemo: VS2005 sample project that demonstrates
control assignment.
Just compile, run and plug in up to 4 DirectX or XInput
compatible game controllers (steering wheel, joystick,
gamepad, etc.).
NOTES
The Controls Assignment SDK uses the Logitech Controller Input
Wrapper (included in the package), which provides a simple
interface to:
- support both DirectInput and XInput hot plug/unplug
- integrate DInput and Xinput support seamlessly
- get controller positional information as well as general
info such as friendly name, VID, PID, connection status based
on various parameters such as controller type,manufacturer,
and model name, and whether it supports force feedback/rumble.
- get hooks to add force feedback or rumble (DirectInput
device interface and XInput ID).
For more details see Microsoft's DirectInput and XInput
documentation.
AUTHOR
Christophe Juncker (cj@wingmanteam.com)
NAME
ControlsAssignment(ControllerInput* controllerInput, LONG axesDInputRangeMin, LONG axesDInputRangeMax) -- Does necessary initialization.
INPUTS
controllerInput: handle to instance of Controller Input SDK. axesDInputRangeMin: minimum value to be used by DirectInput for axes. Should be -32768 to be consistent with XInput. axesDInputRangeMax: maximum value to be used by DirectInput for axes. Should b 32767 to be consistent with XInput.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT AddGameAction(INT gameActionID) -- Add a game action (such as for example Turn Left, or Shoot).
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
NOTES
Every game action needs to be added during initialization.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT StartCheckingForInput(INT gameActionID) -- This needs to be called to indicate that the game action is now in the state where it is checking for a control to be moved.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT StopCheckingForInput(INT gameActionID) -- Stop checking for input. If it is necessary to stop checking for input without having assigned a control, call this function.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsCheckingForInput(INT gameActionID) -- Indicates whether the wrapper is currently in the state where it is checking for a control to be moved.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
TRUE if the wrapper is currently checking for controller movement. FALSE otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsGameActionAssigned(INT gameActionID) -- Indicates whether the game action has a control assigned to it.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
TRUE if the corresponding game action has a control assigned. FALSE otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
FLOAT GetValue(INT gameActionID) -- Returns current value of the game action (0.0 or 1.0 for buttons and POVs, 0.0 to 1.0 or -1.0 to 0.0 for axes).
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
Current value of the game action if a control is assigned to it. 0.0 otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
FLOAT GetCombinedValue(INT gameAction1ID, INT gameAction2ID, BOOL reverseFlag) -- Returns a value that is the combination of 2 game actions. For example if giving it Turn Left and Turn Right, the return value will be the combination of those two actions. If the reverseFlag is set, the return value will be inverted.
INPUTS
gameAction1ID: identification number of the first game action. gameAction2ID: identification number of the second game action. reverseFlag: indicates whether output should be inverted.
RETURN VALUE
Combined value of 2 game actions.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
LPCTSTR GetControlName(INT gameActionID) -- Get name of the control assigned to the current game action.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
Name of the control assigned to the current game action.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT Update() -- Updates all axes, buttons and POVs inside the wrapper. Calculates their normalized values depending on the minimum and maximum output of DirectInput or default values for XInput. If an action is currently in the special state where it checks for controller movement, this function assigns a control to the game action and leaves the special state. Use IsGameActionAssigned() to check if the wrapper still is in the special state or not. If another game action had the same control assigned, it gets reset.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
SEE ALSO
IsGameActionAssigned(INT.gameActionID) SampleInGameImplementation.cpp to see an example.
NAME
HRESULT Reset(INT gameActionID) -- Resets a game action.
INPUTS
gameActionID: identification number of the game action.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT AssignActionToControl(INT gameActionID, ControlAssignment& controlAssignment) -- Do initial assignment between game actions and controls.
INPUTS
gameActionID: identification number of the game action. controlAssignment: assigned control info such as controller number, type, control type, axis, button and POV.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
NOTES
A game will typically read a config file to find out which control is assigned to which game action, and then call this function.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT GetAssignedActionInfo(ControlAssignment& controlAssignment, INT gameActionID) -- Get game action and corresponding control info.
INPUTS
gameActionID: identification number of the game action. controlAssignment: assigned control info such as controller number, type, control type, axis, button and POV.
RETURN VALUE
S_OK if the wrapper successfully entered the control checking state. E_FAIL otherwise.
NOTES
A game can use the resulting info to write to a config file in order to save user controller settings.
SEE ALSO
SampleInGameImplementation.cpp to see an example.