NvAPI handles are retrieved from various calls and passed to other calls in NvAPI. These are meant to be opaque types, and do not necessarily correspond to specific indices, HDCs, or display indices.
Most handles remain valid until a display re-configuration such as a display mode set, or a GPU reconfiguration such as going into or out of SLI modes. If NvAPI returns NVAPI_HANDLE_INVALIDATED, the application should discard all handles and re-enumerate them.
The following is a description of key NvAPI handles and identifiers:
- Physical GPU handle: NvPhysicalGpuHandle is a reference to a physical GPU. Each GPU in a multi-GPU board will have its own handle. GPUs are assigned a handle even if they are not in use by the OS.
- Logical GPU handle: NvLogicalGpuHandle is a reference to one or more physical GPUs acting as a single logical device. A single GPU will have a single logical GPU handle and a single physical GPU handle. Two GPUs acting in an SLI configuration will have a single logical GPU handle and two physical GPU handles.
- NVIDIA display handle: NVIDIA display handles map one-to-one to the GDI handles for the attached displays in the Windows Display Properties Settings page. NvDisplayHandles reflect only the displays that the OS is aware of. Therefore, there is only one NvDisplayHandle for displays in Clone or Span mode, but there are two in Dualview mode. Some APIs use NvUnAttachedDisplayHandle for GDI dsplays that are not attached.
- GPU output: GPU output IDs are identifiers for the GPU outputs that drive display devices. The GPU output might or might not be connected to a display, or be active. Each output is identified by a bit setting within a 32-bit unsigned integer. A GPU output mask consists of a 32-bit integer with several bits set, identifying more than one output from the same physical GPU.
The following figures illustrate these four identifiers used by NvAPI under various GPU configurations.
NvAPI Handles–Dualview, Clone and Spanning Modes
NvAPI Handles–SLI Mode
NvAPI Handles–Two GPUs Under Dualview
