Important NVAPI Concepts

This section explains the following NVAPI concepts and principles:

• NvAPI Handles
  
• Structure Versions Must be Initialized
  
• Use a Static Link with Applications
  

NvAPI Handles

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

Structure Versions Must be Initialized

Each structure contains a version field which the caller must initialize so that the API library can track the version that is used by the calling application.
Each structure also has an associated NvAPI macro that you can use to initialize the version field. For example, the macro for structure NV_XXX is NV_XXX_VER. Initialize the version field as follows:

NV_XXX.version = NV_XXX_VER;

Use a Static Link with Applications

NvAPI cannot be dynamically linked to applications. You must create a static link to the library and then call NvAPI_Initialize(), which loads nvapi.dll dynamically.
If the NVIDIA drivers are not installed on the system or nvapi.dll is not present when the application calls NvAPI_Initialize(), the call just returns an error. The application will still load.