GFE Settings API 1.0.3
Structure containing information about a registered application.
The configuration file name and location will be as follows, with words in <> substituting the value of the specified field: <configPath>/GFXSettings.<executable>.xml
Public Membersconst wchar_t * displayName
Contains default application name.
const wchar_t * versionName
Contains application version information.
const wchar_t * installPath
Absolute path pointing to the directory where the game has been installed.
const wchar_t * configPath
Absolute path pointing to the location where the settings file will be stored and read from.
const wchar_t * executable
Executable name for this configuration. This allows to have multiple GFX config files.
const wchar_t * execCmd
Direct command line used to launch the game. This should be compatible with Steam, Origin, Uplay, etc.
Structure containing the valid values for an enum option.
Public Membersconst wchar_t ** enums
Array of strings that will contain all the enum names.
uint32_t numEnums
Number of strings in the array.
Structure containing value and range info for a named option.
Public Membersconst wchar_t * name
Name of the option. Universal, non-localized name.
NvGsaVariant value
Dynamically typed value of the option.
NvGsaNumericRange numRange
Valid range for numeric types (float and int).
NvGsaEnumRange enumRange
All possible values that an enum option can get; treated as strings.
Structure containing the valid range of numeric (int or float) value.
Public MembersNvGsaValue minValue
Minimum value allowed.
NvGsaValue maxValue
Maximum value allowed.
int32_t numSteps
determines the allowable values for an option given min/max numSteps == -1 range is [-inf, inf] numSteps == 0 range is continuous within [MinValue, MaxValue] numSteps > 0 assumes NumSteps uniform increments between min/max eg, if min = 0, max = 8, and NumSteps = 4, then our option can accept any value in the set {0, 2, 4, 6, 8}
Structure containing display resolution data.
Public Membersuint32_t width
Width of the screen in pixels.
uint32_t height
Height of the screen in pixels.
float refreshRate
Monitor refresh rate in Hz.
Union of option values.
Public Membersint32_t asInt
int value
float asFloat
float value
const wchar_t * asEnum
string enum value
bool asBool
bool value
Structure for passing a dynamically typed option value.
Public MembersNvGsaDataType type
type of the value field
int32_t asInt
int value
float asFloat
float value
const wchar_t * asEnum
string enum value
bool asBool
bool value
Contains the library version number.
Public Membersuint32_t major
Major version of the product, changed manually with every product release with a large new feature set.
uint32_t minor
Minor version of the product, changed manually with every minor product release containing some features.
uint32_t revision
Revision, changed manually with every revision for bug fixes.
uint32_t build
Build number of the same revision. Typically 0.
The GFE Settings API C/C++ header.
DefinesTypedefsGFSDK_GSA_API
Enumstypedef uint32_t NvGsaSaveFlags
Flags containing NvGsaSaveFlagValues bitflags.
FunctionsNvGsaStatus enum
Status codes that may be returned by functions in the library.
Values:
- NV_GSA_STATUS_OK = 0 -
Success. Request is completed.
- NV_GSA_STATUS_ERROR = -1 -
Generic error.
- NV_GSA_STATUS_FILENOTFOUND = -2 -
The config file cannot be found in the specified path.
- NV_GSA_STATUS_SDK_VERSION_MISMATCH = -3 -
Mismatch of dll vs header file+lib.
- NV_GSA_STATUS_INVALID_ARGUMENT = -4 -
Invalid argument (such as a null pointer).
- NV_GSA_STATUS_OPTION_NOT_FOUND = -20 -
The Named Option cannot be found.
- NV_GSA_STATUS_MULTIPLE_OPTIONS_FOUND = -21 -
Multiple optins with the same name found.
- NV_GSA_STATUS_OPTION_VALUE_OUTOFSTEP = -22 -
The data value provided doesn’t fit the step size.
- NV_GSA_STATUS_OPTION_VALUE_OUTOFRANGE = -23 -
The data value provided is outside the valid range.
- NV_GSA_STATUS_OPTION_FOUND = -24 -
The Named Option already exists.
- NV_GSA_STATUS_OPTION_VALUE_WRONG_TYPE = -25 -
The value destination structure has the wrong data type.
- NV_GSA_STATUS_DIRTY_OPTIONS_FOUND = -30 -
One or more options are dirty.
- NV_GSA_STATUS_SDK_NOT_INITIALIZED = -100 -
Trying to use without being initalized.
- NV_GSA_STATUS_SDK_ALREADY_INITIALIZED = -101 -
Trying to initialize more than once.
NvGsaDataType enum
Type of data in an associated NvGsaValue.
Values:
- NV_GSA_TYPE_INT = 0 -
32-bit integer type
- NV_GSA_TYPE_FLOAT = 1 -
32-bit floating point type
- NV_GSA_TYPE_ENUM = 2 -
string enumeration type
- NV_GSA_TYPE_BOOL = 3 -
boolean type
NvGsaSaveFlagValues enum
Flag values used by the GFSDK_GSA_SaveConfigFile function.
Values:
- NV_GSA_SAVE_ALL = 0 -
Save all options, including those that have not been registered by the application.
- NV_GSA_SAVE_SKIP_UNREGISTERED = 1 -
Skip saving unregistered options.
VariablesGFSDK_GSA_API NvGsaStatus GFSDK_GSA_InitializeSDK(const NvGsaApplication * appRegInfo, const NvGsaVersion * version)Initializes the SDK.
If the SDK has already been initialized, it will skip any work and return. If the SDK is not initialized, it will proceed with the initalization steps. First the supplied version will be checked against the dll internal version to avoid potential mismatchs and crashes due to incompatibility of dll’s and the version compiled in the application. Second the application data will be copied to the internal storage.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if appRegInfo or version is null; NV_GSA_STATUS_SDK_ALREADY_INITIALIZED if the library has already been initialized; NV_GSA_STATUS_VERSION_MISMATCH if the application was compiled against an incompatible version of the library; NV_GSA_STATUS_OK if initialization succeeded
- Parameters
- appRegInfo -
Pointer to an NvGsaApplication structure with information about the application initializing the library; should not be null
- version -
Pointer to an NvGsaVersion structure; the application should pass the address of the NvGsaCurrentVersion constant
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_ReleaseSDK()Releases the library and all resources allocated by the library.
Data is not saved or preserved when calling this function. If there are configuration changes that need to be saved, GFSDK_GSA_SaveConfigFile should be called before calling this function.
- Return
- NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OK if the library has been fully released
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_LoadConfigFile()Loads the GSA config file specified during library initialization.
Options should be registered by the application using GFSDK_GSA_RegisterOption before calling this function. Any options in the read from the configuration file that aren’t registered will be inaccessible to the application, and the GeForce Experience client will be responsible for cleaning up unregistered options from the file.
- Return
- NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_FILENOTFOUND if unable to find the settings file; NV_GSA_STATUS_ERROR if the file was unable to be parsed; NV_GSA_STATUS_OK if the file was loaded and options were updated
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_SaveConfigFile(NvGsaSaveFlags flags)Saves registered option values to the GSA config file specified during library initialization.
If the NV_GSA_SAVE_SKIP_UNREGISTERED flag is specified, only registered options will be saved to the GSA config file.
- Return
- NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_ERROR if the file could not be saved; NV_GSA_STATUS_OK if the file was successfully saved
- Parameters
- flags -
Set of NvGsaSaveFlagValues specifying how to save the file; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_RegisterOption(const NvGsaNamedOption * currentOption)Registers an option used by the application.
This function checks for duplicate options with the same name and type, but no verification of option bounds is performed. Duplicate options are skipped.
- Return
- NV_GSA_STATUS_ILLEGAL_ARGUMENT if currentOption is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OPTION_FOUND if the specified option is a duplicate; NV_GSA_STATUS_OK if the option was successfully registered
- Parameters
- currentOption -
Pointer to the option to register; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_RegisterResolutions(const NvGsaResolution * availableResolutions, uint32_t numResolutions)Registers resolutions available to the application.
This function should only been used when the application wants to restrict the set of available resolutions.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if availableResolutions is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OK if the available resolutions were successfully registered
- Parameters
- availableResolutions -
Array of NvGsaResolution structures that enumerate the available resolutions; should not be null
- numResolutions -
Number of elements in the availableResolutions array
GFSDK_GSA_API void GFSDK_GSA_ReleaseVariant(NvGsaVariant * variant)Releases memory used by a variant that was returned by the library.
- Parameters
- variant -
Variant to be released
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_GetOptionValue(NvGsaVariant * value, const wchar_t * name)Returns the current value of the specified registered option.
The returned value should be freed using GFSDK_GSA_ReleaseVariant when it is no longer needed.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if value or name is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OPTION_NOT_FOUND if a registered option with the specified name and type is not found; NV_GSA_STATUS_OK if option was found, and value returned
- Parameters
- value -
Address of NvGsaVariant that will be filled in with the value of the specified option; should not be null
- name -
Name of the option to retrieve; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_SetOptionValue(const NvGsaVariant * value, const wchar_t * name)Updates the current value of the specified registered option.
The current option value will be overwritten by the new one. Verification is done to ensure that the value provided has the correct type and is in the within the allowed range of the registered option.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if value or name is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OPTION_NOT_FOUND if a registered option with the specified name and type is not found; NV_GSA_STATUS_OPTION_VALUE_WRONG_TYPE if the registered option type does not match the specified option type; NV_GSA_VALUE_OUTOFRANGE if the value provided is outside the range specified at registration; NV_GSA_VALUE_OUTOFSTEP if the value provided does not match the step size specified at registration; NV_GSA_STATUS_OK if option was found, and value updated
- Parameters
- value -
Pointer to new value of option; should not be null
- name -
Name of the option to retrieve; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_GetResolution(NvGsaResolution * value)Returns the current resolution setting.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if value is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OK if the current resolution was retrieved successfully
- Parameters
- value -
Address of NvGsaResolution structure to be filled with information about the current resolution; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_SetResolution(const NvGsaResolution * value)Updates the current resolution value stored in the library.
If a range of valid resolutions has been specified, the input value will be validated against the range.
- Return
- NV_GSA_STATUS_INVALID_ARGUMENT if value is null; NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_OPTION_VALUE_OUTOFRANGE if the specified resolution is not available; NV_GSA_STATUS_OK if the current resolution was updated
- Parameters
- value -
Pointer to the new resolution; should not be null
GFSDK_GSA_API NvGsaStatus GFSDK_GSA_CheckForDirtyOptions()Checks if there are options that have changed from the values in the configuration file.
This function compares the application side registered options with their counterparts from the config file. If there are dirty options, it means that some values have changed and the config file might need updating. A use case of this function is to verify whether it is needed to re-save the config file or not when the user applys changes that are identical to the previous settings.
- Return
- NV_GSA_STATUS_SDK_NOT_INITIALIZED if the library has not been initialized with a call to GFSDK_GSA_InitializeSDK; NV_GSA_STATUS_DIRTY_OPTIONS_FOUND if one more options are dirty NV_GSA_STATUS_OK if there are no dirty options
GFSDK_GSA_API NvGsaVersion GFSDK_GSA_GetVersion()Returns the runtime SDK version of the library.
Note that the version returned may be different from NvGsaCurrentVersion, if the library dll being used has a different version than the SDK that the application was compiled agains.
- Return
- the runtime SDK version of the library.
const NvGsaVersion NvGsaCurrentVersion
Contains the current library version number.