Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Gets an instance of the IGameInput interface.
Syntax
HRESULT GameInputCreate(
IGameInput** gameInput
);
Parameters
gameInput _COM_Outptr_
Type: IGameInput**
An instance of the underlying per-process singleton returned by the call.
Return value
Type: HRESULT
Function result.
Remarks
The GameInputCreate function is a Nano-COM factory for getting or creating instances of GameInput. The resulting interface is backed by a per-process singleton that is created the first time this function is called. Therefore, the first call to this function can take a short time to return — short enough that it is generally safe to call from a UI thread, but not from time-sensitive contexts such as a game loop. Subsequent calls to this function from the same process merely add another reference to the underlying singleton and return quickly.
As only one version of GameInput is available on the system at a time, the set of supported interfaces may vary depending on the version of GameInput installed. As GameInput is backwards-compatible, new releases will continue to support old interfaces even as new features are being added.
Applications should call the GameInputCreate function once during startup and retain the IGameInput object reference until the application is ready to shut down. This is true even for Universal Windows Platform (UWP) apps responding to process lifetime management (PLM) suspend events because the cost of reinitializing the GameInput singleton (when the app resumes) typically outweighs the benefits of freeing a small amount of memory in the application.
Relationship to GameInputInitialize
GameInputCreate returns the IGameInput interface of the API version that matches the GameInput header you include. Starting with v3, it's an inline function that calls GameInputInitialize with that version's IID. To create a specific API version, call GameInputInitialize directly.
In v0, GameInputCreate is exported by GameInput.lib. The GameInput.lib in the Microsoft.GameInput NuGet package exports GameInputInitialize instead of GameInputCreate. If your v0 code links that library, call GameInputInitialize with the v0 IID. For an example, see GameInputInitialize.
All versions of GameInputCreate and GameInputInitialize return interfaces on the same per-process singleton. To get another API version of an object that you already have, call QueryInterface on it. For more information, see Using multiple GameInput API versions in one application.
Requirements
Header: GameInput.h
Library: GameInput.lib (v0 only; in v3 and later, GameInputCreate is an inline function in the header)
See also
GameInputInitialize
Advanced GameInput topics
Overview of GameInput
GameInput
Version History
| Version | Changes |
|---|---|
| v3 | Implemented as an inline function that calls GameInputInitialize. |
| v1 | Implemented as an inline function that creates the legacy object and calls QueryInterface for the versioned IGameInput interface. |
| v0 | Introduced. |