NAME
Logitech Controller Input SDK
COPYRIGHT
The Logitech Controller Input SDK, including all accompanying documentation, is protected by intellectual property laws. All rights not expressly granted by Logitech are reserved.
PURPOSE
The Logitech Controller Input SDK's purpose is to create a
paradigm shift. Today users must have their controller(s) plugged
in when launching a PC game, and if they forget, they have to know
to exit the game, plug in the controller, and start again.
The Controller Input SDK enables users to hot plug/unplug
any controllers at any time, mimicking the user-friendly behavior
of consoles.
The SDK provides a simple interface for:
- support of both DirectInput and XInput hot plug/unplug.
- seamless integration of a total of 4 DInput and XInput
controllers.
- getting 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.
- getting hooks to add force feedback or rumble (DirectInput
device interface and XInput ID).
EXAMPLE
Build and run the sample program to see some of the code usage, or run ControllerInputSDKDemo.exe to quickly see what it can do.
AUTHOR
Christophe Juncker (cj@wingmanteam.com)
NAME
ControllerInput(HWND hwnd, BOOL ignoreXInputControllers) -- does necessary initialization.
INPUTS
hwnd - game window handle used to initialize DirectInput. ignoreXInputControllers - if set to TRUE, XInput controllers will be ignored alltogether.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
VOID Update() -- update controller status (connected or disconnected) and read each controller's positional information.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
DIJOYSTATE2* GetStateDInput(INT index) -- get a DirectInput controller's positional information.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
DIJOYSTATE2 pointer to the most recent information obtained through Update() if successful. NULL otherwise.
SEE ALSO
Update() SampleInGameImplementation.cpp to see an example.
NAME
XINPUT_STATE* GetStateXInput(INT index) -- get a XInput controller's positional information.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
XINPUT_STATE pointer to the most recent information obtained through Update() if successful. NULL otherwise.
SEE ALSO
Update() SampleInGameImplementation.cpp to see an example.
NAME
LPCTSTR GetFriendlyProductName(INT index) -- get the friendly name of a controller (as found in the USB Device Descriptor).
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
String containing friendly name if successful. Empy string otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsConnected(INT index) -- check if specified game controller is currently connected.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
TRUE if connected. FALSE otherwise.
SEE ALSO
IsConnected(INT.index,DeviceType.deviceType) IsConnected(INT.index,ManufacturerName.manufacturerName) IsConnected(INT.index,ModelName.modelName) SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsConnected(INT index, DeviceType deviceType) -- check if specified game controller is currently connected.
INPUTS
index - index of the controller (between 0 and
LG_MAX_CONTROLLERS).
deviceType - type of the device. Possible types are:
- LG_DEVICE_TYPE_WHEEL
- LG_DEVICE_TYPE_JOYSTICK
- DEVICE_TYPE_GAMEPAD
- LG_DEVICE_TYPE_OTHER
RETURN VALUE
TRUE if device is connected. FALSE otherwise.
SEE ALSO
IsConnected(INT.index) IsConnected(INT.index,ManufacturerName.manufacturerName) IsConnected(INT.index,ModelName.modelName) SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsConnected(INT index, ManufacturerName manufacturerName) -- check if specified game controller is currently connected.
INPUTS
index - index of the controller (between 0 and
LG_MAX_CONTROLLERS).
manufacturerName - name of the manufacturer of the device. Possible
names are:
- LG_MANUFACTURER_LOGITECH
- LG_MANUFACTURER_MICROSOFT
- LG_MANUFACTURER_OTHER
RETURN VALUE
TRUE if device is connected. FALSE otherwise.
SEE ALSO
IsConnected(INT.index) IsConnected(INT.index,DeviceType.deviceType) IsConnected(INT.index,ModelName.modelName) SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsConnected(INT index, ModelName modelName) -- check if specified game controller is currently connected.
INPUTS
index - index of the controller (between 0 and
LG_MAX_CONTROLLERS).
modelName - model name of the device. Possible names are:
- LG_MODEL_G27
- LG_MODEL_DRIVING_FORCE_GT
- LG_MODEL_G25
- LG_MODEL_MOMO_RACING
- LG_MODEL_MOMO_FORCE
- LG_MODEL_DRIVING_FORCE_PRO
- LG_MODEL_DRIVING_FORCE
- LG_MODEL_NASCAR_RACING_WHEEL
- LG_MODEL_FORMULA_FORCE
- LG_MODEL_FORMULA_FORCE_GP
- LG_MODEL_FORCE_3D_PRO
- LG_MODEL_EXTREME_3D_PRO
- LG_MODEL_FREEDOM_24
- LG_MODEL_ATTACK_3
- LG_MODEL_FORCE_3D
- LG_MODEL_STRIKE_FORCE_3D
- LG_MODEL_G940_JOYSTICK
- LG_MODEL_G940_THROTTLE
- LG_MODEL_G940_PEDALS
- LG_MODEL_RUMBLEPAD
- LG_MODEL_RUMBLEPAD_2
- LG_MODEL_CORDLESS_RUMBLEPAD_2
- LG_MODEL_CORDLESS_GAMEPAD
- LG_MODEL_DUAL_ACTION_GAMEPAD
- LG_MODEL_PRECISION_GAMEPAD_2
- LG_MODEL_CHILLSTREAM
RETURN VALUE
TRUE if device is connected. FALSE otherwise.
SEE ALSO
IsConnected(INT.index) IsConnected(INT.index,DeviceType.deviceType) IsConnected(INT.index,ManufacturerName.manufacturerName) SampleInGameImplementation.cpp to see an example.
NAME
BOOL IsXInputDevice(INT index) -- check if the controller is a XInput device or a DirectInput device.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
TRUE if controller is a XInput device. FALSE otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
BOOL HasForceFeedback(INT index) -- check if the controller can do force feedback or rumble.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
TRUE if controller is force feedback/rumble capable. FALSE otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
DWORD GetVendorID(INT index) -- Get controller's Vendor ID.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
Vendor ID if successful. 0 otherwise.
SEE ALSO
GetProductID(INT.index) SampleInGameImplementation.cpp to see an example.
NAME
DWORD GetProductID(INT index) -- Get controller's Product ID.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
Product ID if successful. 0 otherwise.
SEE ALSO
GetVendorID(INT.index) SampleInGameImplementation.cpp to see an example.
NAME
LPDIRECTINPUTDEVICE8 GetDeviceHandle(INT index) -- Get handle to controller's corresponding DirectInput device. This handle can be used to do force feedback.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
Device handle if successful. NULL otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
INT GetDeviceXinputID(INT index) -- Get ID of XInput controller. This ID can be used as the dwUserIndex parameter to use any of the XInput functions.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
XInput ID if successful ( 0 to 3). LG_XINPUT_ID_NONE otherwise.
SEE ALSO
SampleInGameImplementation.cpp to see an example.
NAME
HRESULT GenerateNonLinearValues(int index, int nonLinCoeff) -- Generate non-linear values for the game controller's axis.
FUNCTION
Gaming wheels/joysticks/game pads have very different behavior from real steering wheels. The reason for single-turn wheels is that they only do up to three quarters of a turn lock to lock, compared to about 3 turns for a real car. This directly affects the steering ratio (15:1 to 20:1 for a real car, but only 4:1 for a gaming wheel!). Joysticks and game pads have a much shorter range of movement than a real steering wheel as well. Because of this very short steering ratio or short range, the gaming wheel/joystick/game pad will feel highly sensitive which may make game play very difficult. Especially it may be difficult to drive in a straight line at speed (tendency to swerve back and forth). One way to get around this problem is to use a sensitivity curve. This is a curve that defines the sensitivity of the game controller depending on speed. This type of curve is usually used for game pads to make up for their low physical range. The result of applying such a curve is that at high speed the car's wheels will physically turn less than if the car is moving very slowly. For example the car's wheels may turn 60 degrees lock to lock at low speed but only 10 degrees lock to lock at higher speeds. If you calculate the resulting steering ratio for 10 degrees lock to lock you find that if you use a steering wheel that turns 180 degrees lock to lock the ratio is equal to 180/10 = 18, which corresponds to a real car's steering ratio. If the sensitivity curve has been implemented for the wheel/joystick, adding a non-linear curve probably is not necessary. But you may find that even after applying a sensitivity curve, the car still feels a little twitchy on a straight line when driving fast. This may be because in your game you need more than 10 degrees lock to lock even at high speeds. Or maybe the car is moving at very high speeds where even a normal steering ratio is not good enough to eliminate high sensitivity. The best way at this point is to add a non-linear curve on top of the sensitivity curve. The effect of the non-linear curve with positive nonLinCoeff is that around center position the wheel/joystick will be less sensitive. Yet at locked position left or right the car's wheels will turn the same amount of degrees as without the non-linear response curve. Therefore the car will become more controllable on a straight line and game-play will be improved. There can sometimes be cases where the wheel does not feel sensitive enough. In that case it is possible to add a non-linear curve with the inverse effect (makes the steering more sensitive around center position) by using negative values for nonLinCoeff. This method lets you define a non-linearity coefficient which will determine how strongly non-linear the curve will be. When running the method it will generate a mapping table in the form of an array. For each of the 1024 entries in this array there will be a corresponding non-linear value which can be used as the wheel/joystick's axis position instead of the original value. See Sample_In-game_Implementation.cs for an example.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS). nonLinCoeff - value representing how much non-linearity should be applied. Range is -100 to 100. 0 = linear curve, 100 = maximum non-linear curve with less sensitivity around center, -100 = maximum non-linearity with more sensitivity around center position.
SEE ALSO
GetNonLinearValue(INT.index,INT.inputValue) SampleInGameImplementation.cpp to see an example.
NAME
INT GetNonLinearValue(INT index, INT inputValue) -- Get a non-linear value from a table previously generated. This can be used for the response of a steering wheel.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS). inputValue - value between LG_DINPUT_RANGE_MIN and LG_DINPUT_RANGE_MAX corresponding to original value of an axis.
RETURN VALUE
Value between LG_DINPUT_RANGE_MIN and LG_DINPUT_RANGE_MAX corresponding to the level of non-linearity previously set with GenerateNonLinearValues(...).
SEE ALSO
GenerateNonLinearValues(INT.index,INT.nonLinCoeff) SampleInGameImplementation.cpp to see an example.
NAME
BOOL ButtonIsPressed(CONST INT index, CONST INT buttonOrMask) -- check if the button is currently pressed.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS). buttonOrMask - button number between 0 and 127 for DInput, one of the following bitmasks for XInput: XINPUT_GAMEPAD_DPAD_UP, XINPUT_GAMEPAD_DPAD_DOWN, XINPUT_GAMEPAD_DPAD_LEFT, XINPUT_GAMEPAD_DPAD_RIGHT, XINPUT_GAMEPAD_START, XINPUT_GAMEPAD_BACK, XINPUT_GAMEPAD_LEFT_THUMB, XINPUT_GAMEPAD_RIGHT_THUMB, XINPUT_GAMEPAD_LEFT_SHOULDER, XINPUT_GAMEPAD_RIGHT_SHOULDER, XINPUT_GAMEPAD_A, XINPUT_GAMEPAD_B, XINPUT_GAMEPAD_X, XINPUT_GAMEPAD_Y
RETURN VALUE
TRUE if buttons is currently pressed. FALSE otherwise.
SEE ALSO
ButtonTriggered(INT.index,INT.buttonOrMask) ButtonReleased(INT.index,INT.buttonOrMask) SampleInGameImplementation.cpp to see an example.
NAME
BOOL ButtonTriggered(CONST INT index, CONST INT buttonOrMask) -- check if the button has been triggered.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS). buttonOrMask - button number between 0 and 127 for DInput, one of the following bitmasks for XInput: XINPUT_GAMEPAD_DPAD_UP, XINPUT_GAMEPAD_DPAD_DOWN, XINPUT_GAMEPAD_DPAD_LEFT, XINPUT_GAMEPAD_DPAD_RIGHT, XINPUT_GAMEPAD_START, XINPUT_GAMEPAD_BACK, XINPUT_GAMEPAD_LEFT_THUMB, XINPUT_GAMEPAD_RIGHT_THUMB, XINPUT_GAMEPAD_LEFT_SHOULDER, XINPUT_GAMEPAD_RIGHT_SHOULDER, XINPUT_GAMEPAD_A, XINPUT_GAMEPAD_B, XINPUT_GAMEPAD_X, XINPUT_GAMEPAD_Y
RETURN VALUE
TRUE if button was triggered. FALSE otherwise.
SEE ALSO
ButtonIsPressed(INT.index,INT.buttonOrMask) ButtonReleased(INT.index,INT.buttonOrMask) SampleInGameImplementation.cpp to see an example.
NAME
BOOL ButtonReleased(CONST INT index, CONST INT buttonOrMask) -- check if the button has been released.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS). buttonOrMask - button number between 0 and 127 for DInput, one of the following bitmasks for XInput: XINPUT_GAMEPAD_DPAD_UP, XINPUT_GAMEPAD_DPAD_DOWN, XINPUT_GAMEPAD_DPAD_LEFT, XINPUT_GAMEPAD_DPAD_RIGHT, XINPUT_GAMEPAD_START, XINPUT_GAMEPAD_BACK, XINPUT_GAMEPAD_LEFT_THUMB, XINPUT_GAMEPAD_RIGHT_THUMB, XINPUT_GAMEPAD_LEFT_SHOULDER, XINPUT_GAMEPAD_RIGHT_SHOULDER, XINPUT_GAMEPAD_A, XINPUT_GAMEPAD_B, XINPUT_GAMEPAD_X, XINPUT_GAMEPAD_Y
RETURN VALUE
TRUE if button was released. FALSE otherwise.
SEE ALSO
ButtonIsPressed(INT.index,INT.buttonOrMask) ButtonTriggered(INT.index,INT.buttonOrMask) SampleInGameImplementation.cpp to see an example.
NAME
INT GetNumberFFAxesDInput(INT index) -- find out how many force feedback axes the controller has.
INPUTS
index - index of the controller (between 0 and LG_MAX_CONTROLLERS).
RETURN VALUE
Number of FF axes.