Interface IGorgonGamingDevice
Provides state for gaming device data from a physical gaming device.
Inherited Members
Namespace: Gorgon.Input
Assembly: Gorgon.Input.dll
Syntax
public interface IGorgonGamingDevice : IDisposableRemarks
Gaming devices (such as a joystick or game pad) and provided via a driver system using the GorgonGamingDeviceDriver object. These drivers may be loaded via a plug in interface through the GorgonGamingDeviceDriverFactory object. Once a driver is loaded, it can be used to create an object of this type.
The gaming devices can support a variable number of axes, and this is reflected within the Axis property to make available only those axes which are supported by the device. For example, if the device supports a single horizontal axis and that axis is mapped to the secondary axis (XAxis2), then the Axis collection will only contain a member for the XAxis2 value. Likewise, if it supports many axes, then all of those axes will be made available. To determine which axes are supported, use the Contains(GamingDeviceAxis) method on the Info.AxisInfo property or the on the Axis property.
GorgonGamingDevice objects require that the device be polled via a call to the Poll() method. This will capture the latest state from the physical device and store it within this type for use by an application.
Some gaming devices (such as XInput controllers) offer special functionality like vibration. This object supports sending data to the physical device to activate the special functionality. If the device does not support the functionality, an exception is typically thrown. Use the Capabilities property to determine if these special functions are supported by the device before calling.
Implementors of a GorgonGamingDeviceDriver plug in must inherit this type in order to expose functionality from a native provider (e.g. XInput).
Properties
| Edit this page View SourceAxis
Property to return the list of axes available to this gaming device.
Declaration
GorgonGamingDeviceAxisList<IGorgonGamingDeviceAxis> Axis { get; }Property Value
| Type | Description |
|---|---|
| GorgonGamingDeviceAxisList<IGorgonGamingDeviceAxis> |
Remarks
This property is used to return the current position and dead zone for a given axis.
GorgonGamingDeviceDriver plug in implementors must set this value when device data is retrieved.
Examples
This example shows how to use this property to get the current gaming device X axis position:
IGorgonGamingDevice _device;
int _currentXPosition;
void SetupDevices()
{
// Do set up in here to retrieve a value for _device.
}
void UpdateJoystickPosition()
{
_device.Poll();
_currentXPosition = _device.Axis[GamingDeviceAxis.XAxis].Value;
}Button
Property to return a list of button states.
Declaration
GamingDeviceButtonState[] Button { get; }Property Value
| Type | Description |
|---|---|
| GamingDeviceButtonState[] |
Remarks
This will return a list of the available buttons on the gaming device and their corresponding state represented by a GamingDeviceButtonState enumeration.
GorgonGamingDeviceDriver plug in implementors must set this value when device data is retrieved.
Info
Property to return information about the gaming device.
Declaration
IGorgonGamingDeviceInfo Info { get; }Property Value
| Type | Description |
|---|---|
| IGorgonGamingDeviceInfo |
IsAcquired
Property to set or return whether the device is acquired or not.
Declaration
bool IsAcquired { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
Remarks
Set this value to true to acquire the device for the application, or false to unacquire it.
Some input providers, like Direct Input, have the concept of device acquisition. When a device is created it may not be usable until it has been acquired by the application. When a device is acquired, it will be made available for use by the application. However, in some circumstances, another application may have exclusive control over the device, and as such, acquisition is not possible.
A device may lose acquisition when the application goes into the background, and as such, the application will no longer receive information from the device. When this is the case, the application should immediately set this value to false during deactivation (during the WinForms Deactivate, or WPF System.Windows.Window.Deactivated events). When the application is activated (during the WinForms Activated, or WPF System.Windows.Window.Activated events), it should set this value to true in order to start capturing data again.
Note that some devices from other input providers (like XInput) will always be in an acquired state. Regardless, it is best to update this flag when the application becomes active or inactive.
IsConnected
Property to return whether the gaming device is connected or not.
Declaration
bool IsConnected { get; }Property Value
| Type | Description |
|---|---|
| bool |
Remarks
Gaming devices may be registered with the system, and appear in the enumeration list provided by EnumerateGamingDevices(bool), but they may not be physically connected to the system at the time of enumeration. Thus, we have this property to ensure that we know when a gaming device is connected to the system or not.
GorgonGamingDeviceDriver plug in implementors must ensure that this property will update itself when a gaming device is connected or disconnected.
POV
Property to return the point of view value for discrete or continuous bearings.
Declaration
float[] POV { get; }Property Value
| Type | Description |
|---|---|
| float[] |
Remarks
This will return a float value of -1.0f for center, or 0 to 359.9999f to indicate the direction, in degrees, of the POV hat.
GorgonGamingDeviceDriver plug in implementors must set this value when device data is retrieved.
POVDirection
Property to return the current direction for the point-of-view hat.
Declaration
IReadOnlyList<POVDirection> POVDirection { get; }Property Value
| Type | Description |
|---|---|
| IReadOnlyList<POVDirection> |
Remarks
If the gaming device does not support a point-of-view axis, then this value will always return Center.
Methods
| Edit this page View SourcePoll()
Function to read the gaming device state.
Declaration
void Poll()Remarks
This method is used to capture the current state of the gaming device. When the state is captured, its data is propagated to the properties for this object.
If this method is not called before checking state, that state will be invalid and/or out of date. Ensure that this method is called frequently to capture the most current state of the physical device.
Reset()
Function to reset the various gaming device axis, button and POV states to default values.
Declaration
void Reset()Vibrate(int, int)
Function to perform vibration on the gaming device, if supported.
Declaration
void Vibrate(int motorIndex, int value)Parameters
| Type | Name | Description |
|---|---|---|
| int | motorIndex | The index of the motor to start or stop. |
| int | value | The speed of the motor. |
Remarks
This will activate the vibration motor(s) in the gaming device. The motorIndex should be within the VibrationMotorRanges count, or else
an exception will be thrown.
To determine if the device supports vibration, check the Capabilities property for the SupportsVibration flag.