Class GorgonGamingDevice

Provides state for gaming device data from a physical gaming device.

Inheritance

object

GorgonGamingDevice

Implements

IGorgonGamingDevice

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Gorgon.Input

Assembly: Gorgon.Input.dll

Syntax

public abstract class GorgonGamingDevice : IGorgonGamingDevice, IDisposable

Remarks

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).

Constructors

| Edit this page View Source

GorgonGamingDevice(IGorgonGamingDeviceInfo)

Initializes a new instance of the GorgonGamingDevice class.

Declaration

protected GorgonGamingDevice(IGorgonGamingDeviceInfo deviceInfo)

Parameters

Type	Name	Description
IGorgonGamingDeviceInfo	deviceInfo	Information about the specific gaming device to use.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `deviceInfo` parameter is null.

Properties

| Edit this page View Source

Axis

Property to return the list of axes available to this gaming device.

Declaration

public 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;
}

| Edit this page View Source

Button

Property to return a list of button states.

Declaration

public 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.

| Edit this page View Source

Info

Property to return information about the gaming device.

Declaration

public IGorgonGamingDeviceInfo Info { get; }

Property Value

Type	Description
IGorgonGamingDeviceInfo

| Edit this page View Source

IsAcquired

Property to set or return whether the device is acquired or not.

Declaration

public 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.

| Edit this page View Source

IsConnected

Property to return whether the gaming device is connected or not.

Declaration

public abstract 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.

| Edit this page View Source

POV

Property to return the point of view value for discrete or continuous bearings.

Declaration

public 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.

| Edit this page View Source

POVDirection

Property to return the current direction for the point-of-view hat.

Declaration

public 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 Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public virtual void Dispose()

Remarks

Some gaming devices use native resources to communicate with the physical device. Because of this, it is necessary to call this method to ensure those resources are freed.

For implementors of a GorgonGamingDeviceDriver, this method should be overridden to free up any native resources required by the device. If the device does not use any native resources, then it is safe to leave this method alone.

| Edit this page View Source

OnAcquire(bool)

Function to acquire a gaming device.

Declaration

protected abstract bool OnAcquire(bool acquireState)

Parameters

Type	Name	Description
bool	acquireState	true to acquire the device, false to unacquire it.

Returns

Type	Description
bool	true if the device was acquired successfully, false if not.

Remarks

Implementors of a GorgonGamingDeviceDriver should implement this on the concrete GorgonGamingDevice, even if the device does not use acquisition (in such a case, always return true from this method).

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 check after it regains foreground focus to see whether the device is acquired or not. For a winforms application this can be achieved with the Activated event. When that happens, set this property to true.

Note that some devices from other input providers (like XInput) will always be in an acquired state. Regardless, it is best to check this flag when the application becomes active.

| Edit this page View Source

OnGetData()

Function to retrieve data from the provider of the physical device.

Declaration

protected abstract void OnGetData()

Remarks

Implementors of a GorgonGamingDeviceDriver plug in must implement this and format their data to populate the values of this object with correct state information.

| Edit this page View Source

OnVibrate(int, int)

Function to perform vibration on the gaming device, if supported.

Declaration

protected virtual void OnVibrate(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.

Implementors of a GorgonGamingDeviceDriver plug in should ensure that devices that support vibration implement this method. Otherwise, if the device does not support the functionality then this method can be left alone.

| Edit this page View Source

Poll()

Function to read the gaming device state.

Declaration

public 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.

| Edit this page View Source

Reset()

Function to reset the various gaming device axis, button and POV states to default values.

Declaration

public virtual void Reset()

| Edit this page View Source

Vibrate(int, int)

Function to perform vibration on the gaming device, if supported.

Declaration

public 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.

Implements

IGorgonGamingDevice

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)