Skip to content

Commit 5fd02b7

Browse files
morganbrKarl-Bridge-Microsoft
morganbr
authored and
Karl-Bridge-Microsoft
committed
Merged PR 21089: Document WGI DMA APIs
Documents all of the APIs added to Windows.Gaming.Input for DMA compliance
2 parents dd9f7fb + e26552a commit 5fd02b7

46 files changed

Lines changed: 1323 additions & 10 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎windows.gaming.input.custom/gipgamecontrollerprovider.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public class GipGameControllerProvider : Windows.Gaming.Input.Custom.IGameContro
1010
# Windows.Gaming.Input.Custom.GipGameControllerProvider
1111

1212
## -description
13-
Represents a physical game controller connected to the system using GIP.SYS (for Xbox One accesories).
13+
Represents a physical game controller connected to the system using GIP.SYS.
1414

1515
## -remarks
1616

‎windows.gaming.input.custom/xusbgamecontrollerprovider.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public class XusbGameControllerProvider : Windows.Gaming.Input.Custom.IGameContr
1010
# Windows.Gaming.Input.Custom.XusbGameControllerProvider
1111

1212
## -description
13-
Represents the physical game controller devices connected to the system using XUSB22.SYS (for Xbox 360 accessories).
13+
Represents the physical game controller devices connected to the system using XUSB22.SYS.
1414

1515
## -remarks
1616

‎windows.gaming.input.preview/code/csharp/CopilotSample.cs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
public void CopilotSample(GipGameControllerProvider pilotProvider,
2+
GipGameControllerProvider copilotProvider)
3+
{
4+
// Establish a copilot pairing for the given pilot and copilot providers
5+
string pilotId = GameControllerProviderInfo.GetProviderId(pilotProvider);
6+
string copilotId = GameControllerProviderInfo.GetProviderId(copilotProvider);
7+
User user = User.GetDefault();
8+
LegacyGipGameControllerProvider.PairPilotToCopilot(user, pilotId,
9+
copilotId);
10+
11+
// Read copilot properties
12+
LegacyGipGameControllerProvider.IsPilot(user, pilotId); // Returns copilotId
13+
LegacyGipGameControllerProvider.IsPilot(user, copilotId); // Returns null
14+
LegacyGipGameControllerProvider.IsCopilot(user, pilotId); // Returns null
15+
LegacyGipGameControllerProvider.IsCopilot(user, copilotId); // Returns pilotId
16+
17+
// Removes the pairing for both controllers
18+
LegacyGipGameControllerProvider.ClearPairing(user, pilotId);
19+
// Also removes the pairing for both controllers (unnecessary since the pairing was already removed)
20+
LegacyGipGameControllerProvider.ClearPairing(user, copilotId);
21+
}

‎windows.gaming.input.preview/code/csharp/EnumerateControllerPropertiesSample.cs‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
public void EnumerateControllerProperties()
2+
{
3+
foreach (Gamepad gamepad in Gamepad.Gamepads)
4+
{
5+
// Create the provider
6+
LegacyGipGameControllerProvider legacyGipGameControllerProvider =
7+
LegacyGipGameControllerProvider.FromGameController(gamepad);
8+
if (legacyGipGameControllerProvider == null)
9+
{
10+
// Not every gamepad is a legacy GIP game controller, continue enumerating
11+
continue;
12+
}
13+
14+
// Check properties
15+
GameControllerBatteryChargingState chargeState =
16+
legacyGipGameControllerProvider.BatteryChargingState;
17+
GameControllerBatteryKind batteryKind =
18+
legacyGipGameControllerProvider.BatteryKind;
19+
GameControllerBatteryLevel batteryLevel =
20+
legacyGipGameControllerProvider.BatteryLevel;
21+
bool isOldFirmwareCorrupted =
22+
legacyGipGameControllerProvider.IsFirmwareCorrupted;
23+
bool isNewFirmwareCorrupted =
24+
legacyGipGameControllerProvider.GetDeviceFirmwareCorruptionState()
25+
!= GameControllerFirmwareCorruptReason.NotCorrupt;
26+
bool isSynthetic = legacyGipGameControllerProvider.IsSyntheticDevice;
27+
byte[] extendedDeviceInfo = legacyGipGameControllerProvider.GetExtendedDeviceInfo();
28+
29+
// Check for a particular GIP interface
30+
bool supportsSomeCustomInterface =
31+
legacyGipGameControllerProvider.IsInterfaceSupported(
32+
new Guid(
33+
0xaaaaaaaa, 0xbbbb, 0xcccc, 0xe, 0xf, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6));
34+
35+
IReadOnlyList<string> preferredTypes =
36+
legacyGipGameControllerProvider.PreferredTypes;
37+
bool isGamepad = preferredTypes.Contains("Windows.Xbox.Input.Gamepad");
38+
bool isHeadset = preferredTypes.Contains("Windows.Xbox.Input.Headset");
39+
40+
// Change the LED to half brightness
41+
legacyGipGameControllerProvider.SetHomeLedIntensity(50);
42+
}
43+
}

‎windows.gaming.input.preview/code/csharp/HeadsetManagementSample.cs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
public void SetupHeadset(IGameControllerProvider headsetProvider)
2+
{
3+
LegacyGipGameControllerProvider legacyGipGameControllerProvider =
4+
LegacyGipGameControllerProvider.FromGameControllerProvider(headsetProvider);
5+
6+
// Reset the device
7+
legacyGipGameControllerProvider.ExecuteCommand(DeviceCommand.Reset);
8+
9+
// Check the smart mute level
10+
byte[] smartMuteBuffer =
11+
legacyGipGameControllerProvider.GetHeadsetOperation(HeadsetOperation.SmartMute);
12+
HeadsetLevel smartMuteValue = (HeadsetLevel)smartMuteBuffer[0];
13+
14+
// Set bass boost to 3db
15+
byte[] bassBuffer = BitConverter.GetBytes((UInt32)3);
16+
legacyGipGameControllerProvider.SetHeadsetOperation(HeadsetOperation.BassBoostGain,
17+
bassBuffer);
18+
}

‎windows.gaming.input.preview/code/csharp/RemapButtonsSample.cs‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
void RemapButtons(IGameController controller, IGameControllerProvider controllerProvider)
2+
{
3+
LegacyGipGameControllerProvider legacyGipGameControllerProvider =
4+
LegacyGipGameControllerProvider.FromGameControllerProvider(controllerProvider);
5+
6+
// Retrieve all current remappings set for standard controllers
7+
IReadOnlyDictionary<RemappingButtonCategory, object> currentMappings =
8+
legacyGipGameControllerProvider.GetStandardControllerButtonRemapping(
9+
controller.User, false);
10+
11+
// Swap two of the buttons
12+
Dictionary<RemappingButtonCategory, object> remaps =
13+
new Dictionary<RemappingButtonCategory, object>();
14+
15+
// Duplicates are not allowed. Swap two of the buttons
16+
UInt64 currentButtonMappings =
17+
(UInt64)currentMappings[RemappingButtonCategory.ButtonSettings];
18+
19+
// Isolate the buttons we want to remap
20+
UInt64 lastButton = (currentButtonMappings & 0xf000000000000000);
21+
UInt64 secondLastButton = currentButtonMappings & 0x0f00000000000000;
22+
23+
// Swap their positions
24+
UInt64 newMapping = (lastButton >> 4) | (secondLastButton << 4);
25+
26+
// Recombine with the original mappings
27+
UInt64 newButtonMappings = (currentButtonMappings & 0x00ffffffffffffff) | newMapping;
28+
29+
// Add the new button remappings to the mapping dictionary
30+
remaps.Add(RemappingButtonCategory.ButtonSettings, newButtonMappings);
31+
32+
// Update controller mapping
33+
legacyGipGameControllerProvider.SetStandardControllerButtonRemapping(
34+
controller.User, false, newButtonMappings);
35+
}

‎windows.gaming.input.preview/devicecommand.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
-api-id: T:Windows.Gaming.Input.Preview.DeviceCommand
3+
-api-type: winrt enum
4+
---
5+
6+
<!-- Enumeration syntax
7+
public enum Windows.Gaming.Input.Preview.DeviceCommand : int
8+
-->
9+
10+
# DeviceCommand
11+
12+
## -description
13+
14+
Commands that can be executed on a GIP headset.
15+
16+
## -enum-fields
17+
18+
### -field Reset:0
19+
20+
Resets the headset.
21+
22+
## -remarks
23+
24+
> [!CAUTION]
25+
> To avoid damaging devices, the headset control APIs should only be used with hardware you have developed.
26+
27+
## -examples
28+
29+
:::code language="csharp" source="code/csharp/HeadsetManagementSample.cs":::
30+
31+
## -see-also

‎windows.gaming.input.preview/gamecontrollerbatterychargingstate.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
-api-id: T:Windows.Gaming.Input.Preview.GameControllerBatteryChargingState
3+
-api-type: winrt enum
4+
---
5+
6+
<!-- Enumeration syntax
7+
public enum Windows.Gaming.Input.Preview.GameControllerBatteryChargingState : int
8+
-->
9+
10+
# GameControllerBatteryChargingState
11+
12+
## -description
13+
14+
Battery charging state of the controller.
15+
16+
## -enum-fields
17+
18+
### -field Unknown:0
19+
20+
The battery charging state is unknown.
21+
22+
### -field Inactive:1
23+
24+
The battery is not charging.
25+
26+
### -field Active:2
27+
28+
The battery is charging.
29+
30+
### -field Error:3
31+
32+
The controller has reported a charging error.
33+
34+
## -remarks
35+
36+
## -examples
37+
38+
:::code language="csharp" source="code/csharp/HeadsetManagementSample.cs":::

‎windows.gaming.input.preview/gamecontrollerbatterykind.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
-api-id: T:Windows.Gaming.Input.Preview.GameControllerBatteryKind
3+
-api-type: winrt enum
4+
---
5+
6+
<!-- Enumeration syntax
7+
public enum Windows.Gaming.Input.Preview.GameControllerBatteryKind : int
8+
-->
9+
10+
# GameControllerBatteryKind
11+
12+
## -description
13+
14+
The kind of battery in the controller.
15+
16+
## -enum-fields
17+
18+
### -field Unknown:0
19+
20+
The kind of battery is unknown.
21+
22+
### -field None:1
23+
24+
The controller does not have a battery.
25+
26+
### -field Standard:2
27+
28+
The controller has a non-rechargeable battery.
29+
30+
### -field Rechargeable:3
31+
32+
The controller has a rechargeable battery.
33+
34+
## -remarks
35+
36+
## -examples
37+
38+
:::code language="csharp" source="code/csharp/HeadsetManagementSample.cs":::

‎windows.gaming.input.preview/gamecontrollerbatterylevel.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
-api-id: T:Windows.Gaming.Input.Preview.GameControllerBatteryLevel
3+
-api-type: winrt enum
4+
---
5+
6+
<!-- Enumeration syntax
7+
public enum Windows.Gaming.Input.Preview.GameControllerBatteryLevel : int
8+
-->
9+
10+
# GameControllerBatteryLevel
11+
12+
## -description
13+
14+
The amount of battery remaining in the controller.
15+
16+
## -enum-fields
17+
18+
### -field Unknown:0
19+
20+
The battery level is unknown.
21+
22+
### -field Critical:1
23+
24+
The battery level is very low.
25+
26+
### -field Low:2
27+
28+
The battery level is low.
29+
30+
### -field Medium:3
31+
32+
The battery is partly charged.
33+
34+
### -field Full:4
35+
36+
The battery is fully charged.
37+
38+
## -remarks
39+
40+
## -examples
41+
42+
:::code language="csharp" source="code/csharp/HeadsetManagementSample.cs":::

0 commit comments

Comments
 (0)