Mouse Input
The Xbox One Mouse API is designed for exclusive apps that need precision control. You’ll feel right at home if you are familiar with the Universal Windows Platform (UWP) CoreWindow mouse/cursor API, although the Xbox version is slightly different.
This topic contains the following sections:
Overview
The Xbox One Mouse API provides data about raw mouse movement and position, horizontal and vertical wheel motion, and cursor screen position. It supports up to five mouse buttons and allows you to use custom cursor glyphs. All standard USB mice are supported.
- The Xbox platform renders the mouse cursor at a constant 60 frames per second, which is not tied to the frame rate of your title. You may disable the system cursor and use a game-rendered one.
- No XRs have been introduced regarding mouse and keyboard support, but controller support is still required, backed by an XR.
- It is up to the title on how to display UI/UX, switch input, and maintain matchmaking fairness on Xbox One. The general recommendation is that players should be segregated by input device type where competitive balance is a concern.
Differences between the Xbox One Mouse API and UWP
The Xbox One Mouse API is contained mostly in the Windows.Input.Devices namespace. Although the Xbox API follows the UWP API as closely as possible, the following UWP features are not available in the Xbox One Mouse API:
- You cannot manually set the position of the pointer cursor.
- You cannot contain the pointer cursor to a specific area of the screen.
- The set of system cursors is limited.
- Custom cursors must be BI_RGB encoded.
Game Mode
The Xbox One Mouse API has a functionality called Game Mode, which is similar to Game Mode for UWP. Game Mode locks the pointer to a specific position if you subscribe to the MouseDevice.MouseMoved and MouseDevice.MouseWheelMoved events and hide the cursor by setting the CoreWindow.PointerPosition property to null. This mainly impacts the following scenarios:
- If your app draws a custom cursor and still needs to use the CoreWindow.PointerPosition values, you must subscribe to the MouseMoved events to prevent the cursor from being locked in place.
- If you want to lock the pointer in place, set the cursor to null and subscribe to the MouseMoved events.
Cross-VM calls
The following are cross-VM calls and should be treated as such:
Custom cursors
Setting a custom cursor is a particularly expensive cross-VM call and should not be done too frequently. This means that you can’t animate a cursor by setting a new custom cursor every frame.
The following additional programming guidelines apply to custom cursors:
- The bitmap component of the cursor’s device-independent bitmap (DIB) must be BI_RGB encoded. It doesn’t matter how you create your CUR file as long as it’s in the BI_RGB format. For information about creating and adding cursors in Microsoft Visual Studio, see https://blogs.msdn.microsoft.com/devfish/2012/08/01/customcursors-in-windows-8-csharp-metro-applications.
- Color table bitmaps (1bpp, 4bpp, 8bpp) support per-pixel alpha in the color table (RGBQUAD in BGRA format).
- 32bpp supports per-pixel alpha in BGRA format.
- 24bpp and 16bpp (555 format) support per-pixel transparency, but not partial alpha.
- Inverted backgrounds are not supported.
Input core1 utilization
Mouse input is partially processed on SRA core1 (ERA core6) to help maintain performance in high-load scenarios. If you are using mouse input, you can keep latency low by minimizing the load on core6.
Platform limitations
The following platform limitations apply to the Xbox One Mouse API:
- The default mouse cursor cannot render in high dynamic range (HDR), which can cause it to look dull on HDR-enabled displays. You can disable the system cursor and render a custom cursor if you need to mitigate this.
- The system cursor does not appear in game DVR recordings or Mixer broadcasts.
- Mouse navigation of the Xbox dashboard is not supported. In addition, mouse input isn’t supported on TCUI or other overlay menus.
- Mouse input is not supported in the Microsoft Edge web browser or on the Dashboard.
- Sensitivity of the system cursor can only be changed via Settings option. You can display a tooltip or toast that informs players of this.
In this section
How to: Determine Whether a Mouse is Connected
Explains how to programmatically determine whether a mouse device is currently connected to an Xbox One console.
How to: Show or Hide the Mouse Cursor
Explains how to show or hide the mouse cursor on Xbox One.
How to: Process Mouse Input Events
Explains how to process input events from a mouse device.
How to: Poll for Mouse Input
Explains how to poll for input from a mouse device.
See also
Input Overview
Input Technologies and Devices Overviews
Keyboard
Keyboard Overview
Reference
MouseDevice Class