General API functions

API for initialization, cleanup, HDR display modes and Crossfire GPU count. More...

Classes
struct	AGSConfiguration
	The configuration options that can be passed in to agsInitialize. More...
struct	AGSGPUInfo
	The top level GPU information returned from agsInitialize. More...
struct	AGSDisplaySettings
	The struct to specify the display settings to the driver. More...

Typedefs
typedef void *(__stdcall *	AGS_ALLOC_CALLBACK) (size_t allocationSize)
	AGS user defined allocation prototype.
typedef void(__stdcall *	AGS_FREE_CALLBACK) (void *allocationPtr)
	AGS user defined free prototype.
typedef struct AGSConfiguration	AGSConfiguration
	The configuration options that can be passed in to agsInitialize.
typedef struct AGSGPUInfo	AGSGPUInfo
	The top level GPU information returned from agsInitialize.
typedef struct AGSDisplaySettings	AGSDisplaySettings
	The struct to specify the display settings to the driver.
typedef enum AGSDriverVersionResult	AGSDriverVersionResult
	The result returned from agsCheckDriverVersion.

Enumerations
enum	AGSDriverVersionResult { AGS_SOFTWAREVERSIONCHECK_OK, AGS_SOFTWAREVERSIONCHECK_OLDER, AGS_SOFTWAREVERSIONCHECK_UNDEFINED }
	The result returned from agsCheckDriverVersion. More...

Functions
AMD_AGS_API AGSDriverVersionResult	agsCheckDriverVersion (const char *radeonSoftwareVersionReported, unsigned int radeonSoftwareVersionRequired)
	Helper function to check the installed software version against the required software version. More...
AMD_AGS_API int	agsGetVersionNumber ()
	Function to return the AGS version number. More...
AMD_AGS_API AGSReturnCode	agsInitialize (int agsVersion, const AGSConfiguration *config, AGSContext **context, AGSGPUInfo *gpuInfo)
	Function used to initialize the AGS library. More...
AMD_AGS_API AGSReturnCode	agsDeInitialize (AGSContext *context)
	Function used to clean up the AGS library. More...
AMD_AGS_API AGSReturnCode	agsSetDisplayMode (AGSContext *context, int deviceIndex, int displayIndex, const AGSDisplaySettings *settings)
	Function used to set a specific display into HDR mode. More...

Detailed Description

API for initialization, cleanup, HDR display modes and Crossfire GPU count.

Enumeration Type Documentation

AGSDriverVersionResult

enum AGSDriverVersionResult

The result returned from agsCheckDriverVersion.

Enumerator
AGS_SOFTWAREVERSIONCHECK_OK	The reported Radeon Software Version is newer or the same as the required version.
AGS_SOFTWAREVERSIONCHECK_OLDER	The reported Radeon Software Version is older than the required version.
AGS_SOFTWAREVERSIONCHECK_UNDEFINED	The check could not determine as result. This could be because it is a private or custom driver or just invalid arguments.

Function Documentation

agsCheckDriverVersion()

AMD_AGS_API AGSDriverVersionResult agsCheckDriverVersion	(	const char *	radeonSoftwareVersionReported,
		unsigned int	radeonSoftwareVersionRequired
	)

Helper function to check the installed software version against the required software version.

Parameters

[in]	radeonSoftwareVersionReported	The Radeon Software Version returned from AGSGPUInfo::radeonSoftwareVersion.
[in]	radeonSoftwareVersionRequired	The Radeon Software Version to check against. This is specificed using AGS_MAKE_VERSION.

Returns

The result of the check.

agsDeInitialize()

AMD_AGS_API AGSReturnCode agsDeInitialize

(

AGSContext *

context

)

Function used to clean up the AGS library.

Parameters

[in]

context

Pointer to a context. This function will deallocate the context from the heap.

agsGetVersionNumber()

AMD_AGS_API int agsGetVersionNumber

(

)

Function to return the AGS version number.

Returns

The version number made using AGS_MAKE_VERSION( AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH ).

agsInitialize()

AMD_AGS_API AGSReturnCode agsInitialize	(	int	agsVersion,
		const AGSConfiguration *	config,
		AGSContext **	context,
		AGSGPUInfo *	gpuInfo
	)

Function used to initialize the AGS library.

agsVersion must be specified as AGS_CURRENT_VERSION or the call will return AGS_INVALID_ARGS. Must be called prior to any of the subsequent AGS API calls. Must be called prior to ID3D11Device or ID3D12Device creation.

Note

The caller of this function should handle the possibility of the call failing in the cases below. One option is to do a vendor id check and only call agsInitialize if there is an AMD GPU present.

This function will fail with AGS_NO_AMD_DRIVER_INSTALLED if there is no AMD driver found on the system.

This function will fail with AGS_LEGACY_DRIVER in Catalyst versions before 12.20.

Parameters

[in]	agsVersion	The API version specified using the AGS_CURRENT_VERSION macro. If this does not match the version in the binary this initialization call will fail.
[in]	config	Optional pointer to a AGSConfiguration struct to override the default library configuration.
[out]	context	Address of a pointer to a context. This function allocates a context on the heap which is then required for all subsequent API calls.
[out]	gpuInfo	Optional pointer to a AGSGPUInfo struct which will get filled in for all the GPUs in the system.

agsSetDisplayMode()

AMD_AGS_API AGSReturnCode agsSetDisplayMode	(	AGSContext *	context,
		int	deviceIndex,
		int	displayIndex,
		const AGSDisplaySettings *	settings
	)

Function used to set a specific display into HDR mode.

Note

Setting all of the values apart from color space and transfer function to zero will cause the display to use defaults.

Call this function after each mode change (switch to fullscreen, any change in swapchain etc).

HDR10 PQ mode requires a 1010102 swapchain.

HDR10 scRGB mode requires an FP16 swapchain.

Freesync HDR scRGB mode requires an FP16 swapchain.

Freesync HDR Gamma 2.2 mode requires a 1010102 swapchain.

Dolby Vision requires a 8888 UNORM swapchain.

Parameters

[in]	context	Pointer to a context. This is generated by agsInitialize
[in]	deviceIndex	The index of the device listed in AGSGPUInfo::devices.
[in]	displayIndex	The index of the display listed in AGSDeviceInfo::displays.
[in]	settings	Pointer to the display settings to use.