You are here: GameWorks Library > Core SDK > GSA > Using GSA

Using GSA

GFE Settings API 1.0.2

struct NvGsaApplication
#include <NvGsa.h

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 Members

const 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.

struct NvGsaEnumRange
#include <NvGsa.h>

Structure containing the valid values for an enum option.

Public Members

const wchar_t ** enums — Array of strings that will contain all the enum names.
uint32_t numEnums — Number of strings in the array.

struct NvGsaNamedOption
#include <NvGsa.h>

Structure containing value and range info for a named option.

Public Members

const 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.

struct NvGsaNumericRange 
#include <NvGsa.h>

Structure containing the valid range of numeric (int or float) value.

Public Members

NvGsaValue 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}.

struct NvGsaResolution
#include <NvGsa.h>

Structure containing display resolution data.

Public Members

uint32_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 NvGsaValue
#include <NvGsa.h>

Union of option values.

Public Members

int32_t asInt — int value
float asFloat — float value
const wchar_t * asEnum — string enum value
bool asBool — bool value

struct NvGsaVariant 
#include <NvGsa.h>

Structure for passing a dynamically typed option value.

Public Members

NvGsaDataType 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

struct NvGsaVersion
#include <NvGsa.h>

Contains the library version number.

Public Members

uint32_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 — Latest Perforce revision of the codebase used for this build.
uint32_t build — Build number of the same revision. Typically 0.

file NvGsa.h
#include <NvFoundation.h>
#include <stdbool.h>

The GFE Settings API C/C++ header.

Defines

GFSDK_GSA_EXPORTS

Typedefs

typedef uint32_t NvGsaSaveFlags — Flags containing NvGsaSaveFlagValues bitflags.

Enums

NvGsaStatus 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 options 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.

Functions

GFSDK_GSA_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS void GFSDK_GSA_ReleaseVariant(NvGsaVariant * variant)

Releases a memory used by a variant that was returned by the library.

Parameters

variant — Variant to be released.

GFSDK_GSA_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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_EXPORTS 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.

Variables

const NvGsaVersion NvGsaCurrentVersion — Contains the current library version number.