On the PC, the NVAPI provides you the ability to query and manipulate the way that 3D Vision Automatic works on behalf of your application; along with allowing you access to important internal variables.
NVAPI is available for PC developers on Windows in both 32 and 64-bit flavors.
Calls are guaranteed to be safe (in that they will not crash) even when made without NVIDIA drivers installed. For example if a user has another vendor's hardware installed, calls will simply return an error code instead of crashing or misbehaving.
Despite this, it is good practice to check the return codes, particularly if NVAPI is being relied on for application-critical functionality. Doing so allows a fallback path to be selected.
The public version of NVAPI is available at http://developer.nvidia.com/nvapi.
In order to provide the best possible stereoscopic experience for developers, NVIDIA has released all of the stereoscopic functions in the public version of NVAPI. However, there is an NDA version of NVAPI that may be available for your project with the appropriate paperwork in place. Contact NVIDIA Developer Support for more information.
Using NVAPI in your project is a straightforward process, and is described in this section.
NVAPI should be statically linked with your PC builds. The included static libraries are shims that will handle dynamic loading of the nvapi.dll (which is shipped as part of the NVIDIA driver). The shim will handle several cases for you automatically; for example, when NVAPI is unavailable or when you've linked against a newer version of NVAPI than your user has installed on their system.
Include nvapi.h from your header files as normal, and then link against the appropriate 32- or 64-bit flavor of the library depending on your build configuration.
| Note: At this time NVAPI should not be dynamically loaded, and does not currently support dynamic unloading. |
To initialize NVAPI, call the function NvAPI_Initialize. You can determine whether NVAPI was correctly initialized or not by checking the return code, although you may still safely make calls to other NVAPI functions even if the library failed to load.
Stereoscopic functions are categorized in two axes: Getters and Setters, and functions that take a Stereoscopic Handle and those that do not. The way that a function is categorized determines when it is valid to make calls against that function. Note that making a call when it is invalid to do so may lead to undefined behavior. For simplicity's sake, Table 1 provides the matrix that is used to determine when you may make a call:
Table 1. Determining When to Make a Call
| Getter | Setter | |
StereoHandle Parameter | After device creation | After device creation |
No StereoHandle Parameter | Anytime | Before device creation |
At the time of this writing, this is the list of functions that must be called prior to Direct3D device creation:
NvAPI_Stereo_CreateConfigurationProfileRegistryKey NvAPI_Stereo_DeleteConfigurationProfileRegistryKey NvAPI_Stereo_SetConfigurationProfileValue NvAPI_Stereo_DeleteConfigurationProfileValue NvAPI_Stereo_Disable NvAPI_Stereo_Enable In order for an application to retain user settings from run to run (for example, the separation and convergence values), an application needs only to call NvAPI_Stereo_CreateConfigurationProfileRegistryKey prior to device creation.
NVIDIA® GameWorks™ Documentation Rev. 1.0.220830 ©2014-2022. NVIDIA Corporation and affiliates. All Rights Reserved.