-
Notifications
You must be signed in to change notification settings - Fork 42
/
Copy pathamd_ags.h
1355 lines (1219 loc) · 87 KB
/
amd_ags.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
//
// Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//
/// \file
/// \mainpage
/// AGS Library Overview
/// --------------------
/// This document provides an overview of the AGS (AMD GPU Services) library. The AGS library provides software developers with the ability to query
/// AMD GPU software and hardware state information that is not normally available through standard operating systems or graphic APIs.
///
/// The latest version of the API is publicly hosted here: https://github.com/GPUOpen-LibrariesAndSDKs/AGS_SDK/.
/// It is also worth checking http://gpuopen.com/gaming-product/amd-gpu-services-ags-library/ for any updates and articles on AGS.
/// \internal
/// Online documentation is publicly hosted here: http://gpuopen-librariesandsdks.github.io/ags/
/// \endinternal
///
/// ---------------------------------------
/// What's new in AGS 6.2 since version 6.1
/// ---------------------------------------
/// AGS 6.2 includes the following updates:
/// * Shader clock intrinsics
/// * Minor improvements and fixes
///
/// ---------------------------------------
/// What's new in AGS 6.1 since version 6.0
/// ---------------------------------------
/// AGS 6.1 includes the following updates:
/// * RDNA3 detection
///
/// ---------------------------------------
/// What's new in AGS 6.0 since version 5.4.2
/// ---------------------------------------
/// AGS 6.0 includes the following updates:
/// * DX12 ray tracing hit token for RDNA2 hardware.
/// * Shader intrinsic that exposes ReadLaneAt in DX12.
/// * Shader intrinsics that expose explicit float conversions in DX12.
/// * Refactored and revised API to minimize user error.
/// * Added agsGetVersionNumber.
/// * Detection for external GPUs.
/// * Detection of RDNA2 architecture.
/// * Grouped the more established intrinsics together into per year support.
/// * Function pointer typedefs for the API
///
/// ---------------------------------------
/// What's new in AGS 5.4.2 since version 5.4.1
/// ---------------------------------------
/// AGS 5.4.2 includes the following updates:
/// * sharedMemoryInBytes has been reinstated.
/// * Clock speed returned for APUs.
///
/// ---------------------------------------
/// What's new in AGS 5.4.1 since version 5.4.0
/// ---------------------------------------
/// AGS 5.4.1 includes the following updates:
/// * AsicFamily_Count to help with code maintenance.
/// * Visual Studio 2019 support.
/// * x86 support
/// * BaseInstance and BaseVertex intrinsics along with corresponding caps bits.
/// * GetWaveSize intrinsic along with corresponding caps bits.
///
/// ---------------------------------------
/// What's new in AGS 5.4 since version 5.3
/// ---------------------------------------
/// AGS 5.4 includes the following updates:
/// * A more detailed description of the GPU architecture, now including RDNA GPUs.
/// * Radeon 7 core and memory speeds returned.
/// * Draw index and Atomic U64 intrinsics for both DX11 and DX12.
///
/// ---------------------------------------
/// What's new in AGS 5.3 since version 5.2
/// ---------------------------------------
/// AGS 5.3 includes the following updates:
/// * DX11 deferred context support for Multi Draw Indirect and UAV Overlap extensions.
/// * A Radeon Software Version helper to determine whether the installed driver meets your game's minimum driver version requirements.
/// * Freesync HDR Gamma 2.2 mode which uses a 1010102 swapchain and can be considered as an alternative to using the 64 bit swapchain required for Freesync HDR scRGB.
///
/// Using the AGS library
/// ---------------------
/// It is recommended to take a look at the source code for the samples that come with the AGS SDK:
/// * AGSSample
/// * CrossfireSample
/// * EyefinitySample
/// The AGSSample application is the simplest of the three examples and demonstrates the code required to initialize AGS and use it to query the GPU and Eyefinity state.
/// The CrossfireSample application demonstrates the use of the new API to transfer resources on GPUs in Crossfire mode. Lastly, the EyefinitySample application provides a more
/// extensive example of Eyefinity setup than the basic example provided in AGSSample.
/// There are other samples on Github that demonstrate the DirectX shader extensions, such as the Barycentrics11 and Barycentrics12 samples.
///
/// To add AGS support to an existing project, follow these steps:
/// * Link your project against the correct import library. Choose from either the 32 bit or 64 bit version.
/// * Copy the AGS dll into the same directory as your game executable.
/// * Include the amd_ags.h header file from your source code.
/// * Include the AGS hlsl files if you are using the shader intrinsics.
/// * Declare a pointer to an AGSContext and make this available for all subsequent calls to AGS.
/// * On game initialization, call \ref agsInitialize passing in the address of the context. On success, this function will return a valid context pointer.
///
/// Don't forget to cleanup AGS by calling \ref agsDeInitialize when the app exits, after the device has been destroyed.
#ifndef AMD_AGS_H
#define AMD_AGS_H
#define AMD_AGS_VERSION_MAJOR 6 ///< AGS major version
#define AMD_AGS_VERSION_MINOR 2 ///< AGS minor version
#define AMD_AGS_VERSION_PATCH 0 ///< AGS patch version
#ifdef __cplusplus
extern "C" {
#endif
/// \defgroup Defines AGS defines
/// @{
#if defined (AGS_GCC)
#define AMD_AGS_API
#else
#define AMD_AGS_API __declspec(dllexport) ///< AGS exported functions
#endif
#define AGS_MAKE_VERSION( major, minor, patch ) ( ( major << 22 ) | ( minor << 12 ) | patch ) ///< Macro to create the app and engine versions for the fields in \ref AGSDX12ExtensionParams and \ref AGSDX11ExtensionParams and the Radeon Software Version
#define AGS_UNSPECIFIED_VERSION 0xFFFFAD00 ///< Use this to specify no version
#define AGS_CURRENT_VERSION AGS_MAKE_VERSION( AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH ) ///< Macro to return the current AGS version as defined by the AGS header file
/// @}
#if !defined (AGS_DIRECTX_TYPES_INCLUDED)
// Forward declaration of D3D and DXGI types
struct IDXGIAdapter;
struct IDXGISwapChain;
struct DXGI_SWAP_CHAIN_DESC;
enum D3D_DRIVER_TYPE;
enum D3D_FEATURE_LEVEL;
enum D3D_PRIMITIVE_TOPOLOGY;
// Forward declaration of D3D11 types
struct ID3D11Device;
struct ID3D11DeviceContext;
struct ID3D11Resource;
struct ID3D11Buffer;
struct ID3D11Texture1D;
struct ID3D11Texture2D;
struct ID3D11Texture3D;
struct D3D11_BUFFER_DESC;
struct D3D11_TEXTURE1D_DESC;
struct D3D11_TEXTURE2D_DESC;
struct D3D11_TEXTURE3D_DESC;
struct D3D11_SUBRESOURCE_DATA;
struct tagRECT;
typedef tagRECT D3D11_RECT; ///< typedef this ourselves so we don't have to drag d3d11.h in
// Forward declaration of D3D12 types
struct ID3D12Device;
struct ID3D12GraphicsCommandList;
#endif
/// \defgroup enums General enumerations
/// @{
/// The return codes
typedef enum AGSReturnCode
{
AGS_SUCCESS, ///< Successful function call
AGS_FAILURE, ///< Failed to complete call for some unspecified reason
AGS_INVALID_ARGS, ///< Invalid arguments into the function
AGS_OUT_OF_MEMORY, ///< Out of memory when allocating space internally
AGS_MISSING_D3D_DLL, ///< Returned when a D3D dll fails to load
AGS_LEGACY_DRIVER, ///< Returned if a feature is not present in the installed driver
AGS_NO_AMD_DRIVER_INSTALLED, ///< Returned if the AMD GPU driver does not appear to be installed
AGS_EXTENSION_NOT_SUPPORTED, ///< Returned if the driver does not support the requested driver extension
AGS_ADL_FAILURE, ///< Failure in ADL (the AMD Display Library)
AGS_DX_FAILURE, ///< Failure from DirectX runtime
AGS_D3DDEVICE_NOT_CREATED ///< Failure due to not creating the D3D device successfully via AGS.
} AGSReturnCode;
/// @}
struct AGSContext; ///< All function calls in AGS require a pointer to a context. This is generated via \ref agsInitialize
/// The rectangle struct used by AGS.
typedef struct AGSRect
{
int offsetX; ///< Offset on X axis
int offsetY; ///< Offset on Y axis
int width; ///< Width of rectangle
int height; ///< Height of rectangle
} AGSRect;
/// The display info struct used to describe a display enumerated by AGS
typedef struct AGSDisplayInfo
{
char name[ 256 ]; ///< The name of the display
char displayDeviceName[ 32 ]; ///< The display device name, i.e. DISPLAY_DEVICE::DeviceName
unsigned int isPrimaryDisplay : 1; ///< Whether this display is marked as the primary display
unsigned int HDR10 : 1; ///< HDR10 is supported on this display
unsigned int dolbyVision : 1; ///< Dolby Vision is supported on this display
unsigned int freesync : 1; ///< Freesync is supported on this display
unsigned int freesyncHDR : 1; ///< Freesync HDR is supported on this display
unsigned int eyefinityInGroup : 1; ///< The display is part of the Eyefinity group
unsigned int eyefinityPreferredDisplay : 1; ///< The display is the preferred display in the Eyefinity group for displaying the UI
unsigned int eyefinityInPortraitMode : 1; ///< The display is in the Eyefinity group but in portrait mode
unsigned int reservedPadding : 24; ///< Reserved for future use
int maxResolutionX; ///< The maximum supported resolution of the unrotated display
int maxResolutionY; ///< The maximum supported resolution of the unrotated display
float maxRefreshRate; ///< The maximum supported refresh rate of the display
AGSRect currentResolution; ///< The current resolution and position in the desktop, ignoring Eyefinity bezel compensation
AGSRect visibleResolution; ///< The visible resolution and position. When Eyefinity bezel compensation is enabled this will
///< be the sub region in the Eyefinity single large surface (SLS)
float currentRefreshRate; ///< The current refresh rate
int eyefinityGridCoordX; ///< The X coordinate in the Eyefinity grid. -1 if not in an Eyefinity group
int eyefinityGridCoordY; ///< The Y coordinate in the Eyefinity grid. -1 if not in an Eyefinity group
double chromaticityRedX; ///< Red display primary X coord
double chromaticityRedY; ///< Red display primary Y coord
double chromaticityGreenX; ///< Green display primary X coord
double chromaticityGreenY; ///< Green display primary Y coord
double chromaticityBlueX; ///< Blue display primary X coord
double chromaticityBlueY; ///< Blue display primary Y coord
double chromaticityWhitePointX; ///< White point X coord
double chromaticityWhitePointY; ///< White point Y coord
double screenDiffuseReflectance; ///< Percentage expressed between 0 - 1
double screenSpecularReflectance; ///< Percentage expressed between 0 - 1
double minLuminance; ///< The minimum luminance of the display in nits
double maxLuminance; ///< The maximum luminance of the display in nits
double avgLuminance; ///< The average luminance of the display in nits
int logicalDisplayIndex; ///< The internally used index of this display
int adlAdapterIndex; ///< The internally used ADL adapter index
int reserved; ///< reserved field
} AGSDisplayInfo;
/// The device info struct used to describe a physical GPU enumerated by AGS
typedef struct AGSDeviceInfo
{
/// The ASIC family
typedef enum AsicFamily
{
AsicFamily_Unknown, ///< Unknown architecture, potentially from another IHV. Check \ref AGSDeviceInfo::vendorId
AsicFamily_PreGCN, ///< Pre GCN architecture.
AsicFamily_GCN1, ///< AMD GCN 1 architecture: Oland, Cape Verde, Pitcairn & Tahiti.
AsicFamily_GCN2, ///< AMD GCN 2 architecture: Hawaii & Bonaire. This also includes APUs Kaveri and Carrizo.
AsicFamily_GCN3, ///< AMD GCN 3 architecture: Tonga & Fiji.
AsicFamily_GCN4, ///< AMD GCN 4 architecture: Polaris.
AsicFamily_Vega, ///< AMD Vega architecture, including Raven Ridge (ie AMD Ryzen CPU + AMD Vega GPU).
AsicFamily_RDNA, ///< AMD RDNA architecture
AsicFamily_RDNA2, ///< AMD RDNA2 architecture
AsicFamily_RDNA3, ///< AMD RDNA3 architecture
AsicFamily_Count ///< Number of enumerated ASIC families
} AsicFamily;
const char* adapterString; ///< The adapter name string
AsicFamily asicFamily; ///< Set to Unknown if not AMD hardware
unsigned int isAPU : 1; ///< Whether this device is an APU
unsigned int isPrimaryDevice : 1; ///< Whether this device is marked as the primary device
unsigned int isExternal :1; ///< Whether this device is a detachable, external device
unsigned int reservedPadding : 29; ///< Reserved for future use
int vendorId; ///< The vendor id
int deviceId; ///< The device id
int revisionId; ///< The revision id
int numCUs; ///< Number of compute units
int numWGPs; ///< Number of RDNA Work Group Processors. Only valid if ASIC is RDNA onwards.
int numROPs; ///< Number of ROPs
int coreClock; ///< Core clock speed at 100% power in MHz
int memoryClock; ///< Memory clock speed at 100% power in MHz
int memoryBandwidth; ///< Memory bandwidth in MB/s
float teraFlops; ///< Teraflops of GPU. Zero if not GCN onwards. Calculated from iCoreClock * iNumCUs * 64 Pixels/clk * 2 instructions/MAD
unsigned long long localMemoryInBytes; ///< The size of local memory in bytes. 0 for non AMD hardware.
unsigned long long sharedMemoryInBytes; ///< The size of system memory available to the GPU in bytes. It is important to factor this into your VRAM budget for APUs
///< as the reported local memory will only be a small fraction of the total memory available to the GPU.
int numDisplays; ///< The number of active displays found to be attached to this adapter.
AGSDisplayInfo* displays; ///< List of displays allocated by AGS to be numDisplays in length.
int eyefinityEnabled; ///< Indicates if Eyefinity is active
int eyefinityGridWidth; ///< Contains width of the multi-monitor grid that makes up the Eyefinity Single Large Surface.
int eyefinityGridHeight; ///< Contains height of the multi-monitor grid that makes up the Eyefinity Single Large Surface.
int eyefinityResolutionX; ///< Contains width in pixels of the multi-monitor Single Large Surface.
int eyefinityResolutionY; ///< Contains height in pixels of the multi-monitor Single Large Surface.
int eyefinityBezelCompensated; ///< Indicates if bezel compensation is used for the current SLS display area. 1 if enabled, and 0 if disabled.
int adlAdapterIndex; ///< Internally used index into the ADL list of adapters
int reserved; ///< reserved field
} AGSDeviceInfo;
/// \defgroup general General API functions
/// API for initialization, cleanup, HDR display modes and Crossfire GPU count
/// @{
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
/// The configuration options that can be passed in to \ref agsInitialize
typedef struct AGSConfiguration
{
AGS_ALLOC_CALLBACK allocCallback; ///< Optional memory allocation callback. If not supplied, malloc() is used
AGS_FREE_CALLBACK freeCallback; ///< Optional memory freeing callback. If not supplied, free() is used
} AGSConfiguration;
/// The top level GPU information returned from \ref agsInitialize
typedef struct AGSGPUInfo
{
const char* driverVersion; ///< The AMD driver package version
const char* radeonSoftwareVersion; ///< The Radeon Software Version
int numDevices; ///< Number of GPUs in the system
AGSDeviceInfo* devices; ///< List of GPUs in the system
} AGSGPUInfo;
/// The struct to specify the display settings to the driver.
typedef struct AGSDisplaySettings
{
/// The display mode
typedef enum Mode
{
Mode_SDR, ///< SDR mode
Mode_HDR10_PQ, ///< HDR10 PQ encoding, requiring a 1010102 UNORM swapchain and PQ encoding in the output shader.
Mode_HDR10_scRGB, ///< HDR10 scRGB, requiring an FP16 swapchain. Values of 1.0 == 80 nits, 125.0 == 10000 nits.
Mode_FreesyncHDR_scRGB, ///< Freesync HDR scRGB, requiring an FP16 swapchain. A value of 1.0 == 80 nits.
Mode_FreesyncHDR_Gamma22, ///< Freesync HDR Gamma 2.2, requiring a 1010102 UNORM swapchain. The output needs to be encoded to gamma 2.2.
Mode_DolbyVision, ///< Dolby Vision, requiring an 8888 UNORM swapchain
Mode_Count ///< Number of enumerated display modes
} Mode;
Mode mode; ///< The display mode to set the display into
double chromaticityRedX; ///< Red display primary X coord
double chromaticityRedY; ///< Red display primary Y coord
double chromaticityGreenX; ///< Green display primary X coord
double chromaticityGreenY; ///< Green display primary Y coord
double chromaticityBlueX; ///< Blue display primary X coord
double chromaticityBlueY; ///< Blue display primary Y coord
double chromaticityWhitePointX; ///< White point X coord
double chromaticityWhitePointY; ///< White point Y coord
double minLuminance; ///< The minimum scene luminance in nits
double maxLuminance; ///< The maximum scene luminance in nits
double maxContentLightLevel; ///< The maximum content light level in nits (MaxCLL)
double maxFrameAverageLightLevel; ///< The maximum frame average light level in nits (MaxFALL)
unsigned int disableLocalDimming : 1; ///< Disables local dimming if possible
unsigned int reservedPadding : 31; ///< Reserved
} AGSDisplaySettings;
/// The result returned from \ref agsCheckDriverVersion
typedef enum AGSDriverVersionResult
{
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.
} AGSDriverVersionResult;
///
/// Helper function to check the installed software version against the required software version.
///
/// \param [in] radeonSoftwareVersionReported The Radeon Software Version returned from \ref AGSGPUInfo::radeonSoftwareVersion.
/// \param [in] radeonSoftwareVersionRequired The Radeon Software Version to check against. This is specificed using \ref AGS_MAKE_VERSION.
/// \return The result of the check.
///
AMD_AGS_API AGSDriverVersionResult agsCheckDriverVersion( const char* radeonSoftwareVersionReported, unsigned int radeonSoftwareVersionRequired );
///
/// Function to return the AGS version number.
///
/// \return The version number made using AGS_MAKE_VERSION( AMD_AGS_VERSION_MAJOR, AMD_AGS_VERSION_MINOR, AMD_AGS_VERSION_PATCH ).
///
AMD_AGS_API int agsGetVersionNumber();
///
/// Function used to initialize the AGS library.
/// agsVersion must be specified as AGS_CURRENT_VERSION or the call will return \ref 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 \ref agsInitialize if there is an AMD GPU present.
/// \note This function will fail with \ref AGS_NO_AMD_DRIVER_INSTALLED if there is no AMD driver found on the system.
/// \note This function will fail with \ref AGS_LEGACY_DRIVER in Catalyst versions before 12.20.
///
/// \param [in] agsVersion The API version specified using the \ref AGS_CURRENT_VERSION macro. If this does not match the version in the binary this initialization call will fail.
/// \param [in] config Optional pointer to a AGSConfiguration struct to override the default library configuration.
/// \param [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.
/// \param [out] gpuInfo Optional pointer to a AGSGPUInfo struct which will get filled in for all the GPUs in the system.
///
AMD_AGS_API AGSReturnCode agsInitialize( int agsVersion, const AGSConfiguration* config, AGSContext** context, AGSGPUInfo* gpuInfo );
///
/// Function used to clean up the AGS library.
///
/// \param [in] context Pointer to a context. This function will deallocate the context from the heap.
///
AMD_AGS_API AGSReturnCode agsDeInitialize( AGSContext* context );
///
/// 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.
/// \note Call this function after each mode change (switch to fullscreen, any change in swapchain etc).
/// \note HDR10 PQ mode requires a 1010102 swapchain.
/// \note HDR10 scRGB mode requires an FP16 swapchain.
/// \note Freesync HDR scRGB mode requires an FP16 swapchain.
/// \note Freesync HDR Gamma 2.2 mode requires a 1010102 swapchain.
/// \note Dolby Vision requires a 8888 UNORM swapchain.
///
/// \param [in] context Pointer to a context. This is generated by \ref agsInitialize
/// \param [in] deviceIndex The index of the device listed in \ref AGSGPUInfo::devices.
/// \param [in] displayIndex The index of the display listed in \ref AGSDeviceInfo::displays.
/// \param [in] settings Pointer to the display settings to use.
///
AMD_AGS_API AGSReturnCode agsSetDisplayMode( AGSContext* context, int deviceIndex, int displayIndex, const AGSDisplaySettings* settings );
/// @}
/// @}
/// \defgroup dxappreg App Registration
/// @{
/// This extension allows an application to voluntarily register itself with the driver, providing a more robust app detection solution and avoid the issue of the driver relying on exe names to match the app to a driver profile.
/// It is available when creating the device for both DirectX11 and DirectX12 via \ref agsDriverExtensionsDX11_CreateDevice and \ref agsDriverExtensionsDX12_CreateDevice respectively.
/// This feature is supported in Radeon Software Version 17.9.2 onwards.
/// Rules:
/// * AppName or EngineName must be set, but both are not required. Engine profiles will be used only if app specific profiles do not exist.
/// * In an engine, the EngineName should be set, so a default profile can be built. If an app modifies the engine, the AppName should be set, to allow a profile for the specific app.
/// * Version number is not mandatory, but recommended. The use of which can prevent the use of profiles for incompatible versions (for instance engine versions that introduce or change features), and can help prevent older profiles from being used (and introducing new bugs) before the profile is tested with new app builds.
/// * If Version numbers are used and a new version is introduced, a new profile will not be enabled until an AMD engineer has been able to update a previous profile, or make a new one.
///
/// The cases for profile selection are as follows:
///
/// |Case|Profile Applied|
/// |----|---------------|
/// | App or Engine Version has profile | The profile is used. |
/// | App or Engine Version num < profile version num | The closest profile > the version number is used. |
/// | App or Engine Version num > profile version num | No profile selected/The previous method is used. |
/// | App and Engine Version have profile | The App's profile is used. |
/// | App and Engine Version num < profile version | The closest App profile > the version number is used. |
/// | App and Engine Version, no App profile found | The Engine profile will be used. |
/// | App/Engine name but no Version, has profile | The latest profile is used. |
/// | No name or version, or no profile | The previous app detection method is used. |
///
/// As shown above, if an App name is given, and a profile is found for that app, that will be prioritized. The Engine name and profile will be used only if no app name is given, or no viable profile is found for the app name.
/// In the case that App nor Engine have a profile, the previous app detection methods will be used. If given a version number that is larger than any profile version number, no profile will be selected.
/// This is specifically to prevent cases where an update to an engine or app will cause catastrophic breaks in the profile, allowing an engineer to test the profile before clearing it for public use with the new engine/app update.
///
/// @}
/// \defgroup dx12 DirectX12 Extensions
/// DirectX12 driver extensions
/// @{
/// \defgroup dx12init Device and device object creation and cleanup
/// It is now mandatory to call \ref agsDriverExtensionsDX12_CreateDevice when creating a device if the user wants to access any future DX12 AMD extensions.
/// The corresponding \ref agsDriverExtensionsDX12_DestroyDevice call must be called to release the device and free up the internal resources allocated by the create call.
/// @{
/// The struct to specify the DX12 device creation parameters
typedef struct AGSDX12DeviceCreationParams
{
IDXGIAdapter* pAdapter; ///< Pointer to the adapter to use when creating the device. This may be null.
IID iid; ///< The interface ID for the type of device to be created.
D3D_FEATURE_LEVEL FeatureLevel; ///< The minimum feature level to create the device with.
} AGSDX12DeviceCreationParams;
/// The struct to specify DX12 additional device creation parameters
typedef struct AGSDX12ExtensionParams
{
const WCHAR* pAppName; ///< Application name
const WCHAR* pEngineName; ///< Engine name
unsigned int appVersion; ///< Application version
unsigned int engineVersion; ///< Engine version
unsigned int uavSlot; ///< The UAV slot reserved for intrinsic support. Refer to the \ref agsDriverExtensionsDX12_CreateDevice documentation for more details.
} AGSDX12ExtensionParams;
/// The struct to hold all the returned parameters from the device creation call
typedef struct AGSDX12ReturnedParams
{
ID3D12Device* pDevice; ///< The newly created device
typedef struct ExtensionsSupported /// Extensions for DX12
{
unsigned int intrinsics16 : 1; ///< Supported in Radeon Software Version 16.9.2 onwards. ReadFirstLane, ReadLane, LaneID, Swizzle, Ballot, MBCount, Med3, Barycentrics
unsigned int intrinsics17 : 1; ///< Supported in Radeon Software Version 17.9.1 onwards. WaveReduce, WaveScan
unsigned int userMarkers : 1; ///< Supported in Radeon Software Version 17.9.1 onwards.
unsigned int appRegistration : 1; ///< Supported in Radeon Software Version 17.9.1 onwards.
unsigned int UAVBindSlot : 1; ///< Supported in Radeon Software Version 19.5.1 onwards.
unsigned int intrinsics19 : 1; ///< Supported in Radeon Software Version 19.12.2 onwards. DrawIndex, AtomicU64
unsigned int baseVertex : 1; ///< Supported in Radeon Software Version 20.2.1 onwards.
unsigned int baseInstance : 1; ///< Supported in Radeon Software Version 20.2.1 onwards.
unsigned int getWaveSize : 1; ///< Supported in Radeon Software Version 20.5.1 onwards.
unsigned int floatConversion : 1; ///< Supported in Radeon Software Version 20.5.1 onwards.
unsigned int readLaneAt : 1; ///< Supported in Radeon Software Version 20.11.2 onwards.
unsigned int rayHitToken : 1; ///< Supported in Radeon Software Version 20.11.2 onwards.
unsigned int shaderClock : 1; ///< Supported in Radeon Software Version 23.1.1 onwards.
unsigned int padding : 19; ///< Reserved
} ExtensionsSupported;
ExtensionsSupported extensionsSupported; ///< List of supported extensions
} AGSDX12ReturnedParams;
/// The space id for DirectX12 intrinsic support
const unsigned int AGS_DX12_SHADER_INTRINSICS_SPACE_ID = 0x7FFF0ADE; // 2147420894
///
/// Function used to create a D3D12 device with additional AMD-specific initialization parameters.
///
/// When using the HLSL shader extensions please note:
/// * The shader compiler should not use the D3DCOMPILE_SKIP_OPTIMIZATION (/Od) option or /O0, otherwise it will not work.
/// * The shader compiler needs D3DCOMPILE_ENABLE_STRICTNESS (/Ges) enabled.
/// * The intrinsic instructions require a 5.1 shader model.
/// * The Root Signature will need to reserve an extra UAV resource slot. This is not a real resource that requires allocating, it is just used to encode the intrinsic instructions.
///
/// The easiest way to set up the reserved UAV slot is to specify it at u0. The register space id will automatically be assumed to be \ref AGS_DX12_SHADER_INTRINSICS_SPACE_ID.
/// The HLSL expects this as default and the set up code would look similar to this:
/// \code{.cpp}
/// CD3DX12_DESCRIPTOR_RANGE range[];
/// ...
/// range[ 0 ].Init( D3D12_DESCRIPTOR_RANGE_TYPE_UAV, 1, 0, AGS_DX12_SHADER_INTRINSICS_SPACE_ID ); // u0 at driver-reserved space id
/// \endcode
///
/// Newer drivers also support a user-specified slot in which case the register space id is assumed to be 0. It is important that the \ref AGSDX12ReturnedParams::ExtensionsSupported::UAVBindSlot bit is set.
/// to ensure the driver can support this. If not, then u0 and \ref AGS_DX12_SHADER_INTRINSICS_SPACE_ID must be used.
/// If the driver does support this feature and a non zero slot is required, then the HLSL must also define AMD_EXT_SHADER_INTRINSIC_UAV_OVERRIDE as the matching slot value.
///
/// \param [in] context Pointer to a context. This is generated by \ref agsInitialize
/// \param [in] creationParams Pointer to the struct to specify the existing DX12 device creation parameters.
/// \param [in] extensionParams Optional pointer to the struct to specify DX12 additional device creation parameters.
/// \param [out] returnedParams Pointer to struct to hold all the returned parameters from the call.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX12_CreateDevice( AGSContext* context, const AGSDX12DeviceCreationParams* creationParams, const AGSDX12ExtensionParams* extensionParams, AGSDX12ReturnedParams* returnedParams );
///
/// Function to destroy the D3D12 device.
/// This call will also cleanup any AMD-specific driver extensions for D3D12.
///
/// \param [in] context Pointer to a context.
/// \param [in] device Pointer to the D3D12 device.
/// \param [out] deviceReferences Optional pointer to an unsigned int that will be set to the value returned from device->Release().
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX12_DestroyDevice( AGSContext* context, ID3D12Device* device, unsigned int* deviceReferences );
/// @}
/// \defgroup dx12usermarkers User Markers
/// @{
///
/// Function used to push an AMD user marker onto the command list.
/// This is only has an effect if \ref AGSDX12ReturnedParams::ExtensionsSupported::userMarkers is present.
/// Supported in Radeon Software Version 17.9.1 onwards.
///
/// \param [in] context Pointer to a context.
/// \param [in] commandList Pointer to the command list.
/// \param [in] data The UTF-8 marker string.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX12_PushMarker( AGSContext* context, ID3D12GraphicsCommandList* commandList, const char* data );
///
/// Function used to pop an AMD user marker on the command list.
/// Supported in Radeon Software Version 17.9.1 onwards.
///
/// \param [in] context Pointer to a context.
/// \param [in] commandList Pointer to the command list.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX12_PopMarker( AGSContext* context, ID3D12GraphicsCommandList* commandList );
///
/// Function used to insert an single event AMD user marker onto the command list.
/// Supported in Radeon Software Version 17.9.1 onwards.
///
/// \param [in] context Pointer to a context.
/// \param [in] commandList Pointer to the command list.
/// \param [in] data The UTF-8 marker string.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX12_SetMarker( AGSContext* context, ID3D12GraphicsCommandList* commandList, const char* data );
/// @}
/// @}
/// \defgroup dx11 DirectX11 Extensions
/// DirectX11 driver extensions
/// @{
/// \defgroup dx11init Device creation and cleanup
/// It is now mandatory to call \ref agsDriverExtensionsDX11_CreateDevice when creating a device if the user wants to access any DX11 AMD extensions.
/// The corresponding \ref agsDriverExtensionsDX11_DestroyDevice call must be called to release the device and free up the internal resources allocated by the create call.
/// @{
/// The different modes to control Crossfire behavior.
typedef enum AGSCrossfireMode
{
AGS_CROSSFIRE_MODE_DRIVER_AFR = 0, ///< Use the default driver-based AFR rendering. If this mode is specified, do NOT use the agsDriverExtensionsDX11_Create*() APIs to create resources
AGS_CROSSFIRE_MODE_EXPLICIT_AFR, ///< Use the AGS Crossfire API functions to perform explicit AFR rendering without requiring a CF driver profile
AGS_CROSSFIRE_MODE_DISABLE ///< Completely disable AFR rendering
} AGSCrossfireMode;
/// The struct to specify the existing DX11 device creation parameters
typedef struct AGSDX11DeviceCreationParams
{
IDXGIAdapter* pAdapter; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
D3D_DRIVER_TYPE DriverType; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
HMODULE Software; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
UINT Flags; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
const D3D_FEATURE_LEVEL* pFeatureLevels; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
UINT FeatureLevels; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
UINT SDKVersion; ///< Consult the DX documentation on D3D11CreateDevice for this parameter
const DXGI_SWAP_CHAIN_DESC* pSwapChainDesc; ///< Optional swapchain description. Specify this to invoke D3D11CreateDeviceAndSwapChain instead of D3D11CreateDevice.
} AGSDX11DeviceCreationParams;
/// The struct to specify DX11 additional device creation parameters
typedef struct AGSDX11ExtensionParams
{
const WCHAR* pAppName; ///< Application name
const WCHAR* pEngineName; ///< Engine name
unsigned int appVersion; ///< Application version
unsigned int engineVersion; ///< Engine version
unsigned int numBreadcrumbMarkers; ///< The number of breadcrumb markers to allocate. Each marker is a uint64 (ie 8 bytes). If 0, the system is disabled.
unsigned int uavSlot; ///< The UAV slot reserved for intrinsic support. This must match the slot defined in the HLSL, i.e. "#define AmdDxExtShaderIntrinsicsUAVSlot".
/// The default slot is 7, but the caller is free to use an alternative slot.
/// If 0 is specified, then the default of 7 will be used.
AGSCrossfireMode crossfireMode; ///< Desired Crossfire mode
} AGSDX11ExtensionParams;
/// The struct to hold all the returned parameters from the device creation call
typedef struct AGSDX11ReturnedParams
{
ID3D11Device* pDevice; ///< The newly created device
ID3D11DeviceContext* pImmediateContext; ///< The newly created immediate device context
IDXGISwapChain* pSwapChain; ///< The newly created swap chain. This is only created if a valid pSwapChainDesc is supplied in AGSDX11DeviceCreationParams.
D3D_FEATURE_LEVEL featureLevel; ///< The feature level supported by the newly created device
typedef struct ExtensionsSupported /// Extensions for DX11
{
unsigned int quadList : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int screenRectList : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int uavOverlap : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int depthBoundsTest : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int multiDrawIndirect : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int multiDrawIndirectCountIndirect : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int crossfireAPI : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int createShaderControls : 1; ///< Supported in Radeon Software Version 16.9.2 onwards.
unsigned int intrinsics16 : 1; ///< Supported in Radeon Software Version 16.9.2 onwards. ReadFirstLane, ReadLane, LaneID, Swizzle, Ballot, MBCount, Med3, Barycentrics
unsigned int multiView : 1; ///< Supported in Radeon Software Version 16.12.1 onwards.
unsigned int intrinsics17 : 1; ///< Supported in Radeon Software Version 17.9.1 onwards. WaveReduce, WaveScan
unsigned int appRegistration : 1; ///< Supported in Radeon Software Version 17.9.1 onwards.
unsigned int breadcrumbMarkers : 1; ///< Supported in Radeon Software Version 17.11.1 onwards.
unsigned int MDIDeferredContexts : 1; ///< Supported in Radeon Software Version 18.8.1 onwards.
unsigned int UAVOverlapDeferredContexts : 1; ///< Supported in Radeon Software Version 18.8.1 onwards.
unsigned int depthBoundsDeferredContexts : 1; ///< Supported in Radeon Software Version 18.8.1 onwards.
unsigned int intrinsics19 : 1; ///< Supported in Radeon Software Version 19.12.2 onwards. DrawIndex, AtomicU64
unsigned int getWaveSize : 1; ///< Supported in Radeon Software Version 20.2.1 onwards.
unsigned int baseVertex : 1; ///< Supported in Radeon Software Version 20.2.1 onwards.
unsigned int baseInstance : 1; ///< Supported in Radeon Software Version 20.2.1 onwards.
unsigned int padding : 12; ///< Reserved
} ExtensionsSupported;
ExtensionsSupported extensionsSupported; ///< List of supported extensions
unsigned int crossfireGPUCount; ///< The number of GPUs that are active for this app
void* breadcrumbBuffer; ///< The CPU buffer returned if the initialization of the breadcrumb was successful
} AGSDX11ReturnedParams;
///
/// Function used to create a D3D11 device with additional AMD-specific initialization parameters.
///
/// When using the HLSL shader extensions please note:
/// * The shader compiler should not use the D3DCOMPILE_SKIP_OPTIMIZATION (/Od) option, otherwise it will not work.
/// * The shader compiler needs D3DCOMPILE_ENABLE_STRICTNESS (/Ges) enabled.
///
/// \param [in] context Pointer to a context. This is generated by \ref agsInitialize
/// \param [in] creationParams Pointer to the struct to specify the existing DX11 device creation parameters.
/// \param [in] extensionParams Optional pointer to the struct to specify DX11 additional device creation parameters.
/// \param [out] returnedParams Pointer to struct to hold all the returned parameters from the call.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_CreateDevice( AGSContext* context, const AGSDX11DeviceCreationParams* creationParams, const AGSDX11ExtensionParams* extensionParams, AGSDX11ReturnedParams* returnedParams );
///
/// Function to destroy the D3D11 device and its immediate context.
/// This call will also cleanup any AMD-specific driver extensions for D3D11.
///
/// \param [in] context Pointer to a context.
/// \param [in] device Pointer to the D3D11 device.
/// \param [out] deviceReferences Optional pointer to an unsigned int that will be set to the value returned from device->Release().
/// \param [in] immediateContext Pointer to the D3D11 immediate device context.
/// \param [out] immediateContextReferences Optional pointer to an unsigned int that will be set to the value returned from immediateContext->Release().
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_DestroyDevice( AGSContext* context, ID3D11Device* device, unsigned int* deviceReferences, ID3D11DeviceContext* immediateContext, unsigned int* immediateContextReferences );
/// @}
/// \defgroup breadcrumbs Breadcrumb API
/// API for writing top-of-pipe and bottom-of-pipe markers to help track down GPU hangs.
///
/// The API is available if the \ref AGSDX11ReturnedParams::ExtensionsSupported::breadcrumbMarkers is present.
///
/// To use the API, a non zero value needs to be specificed in \ref AGSDX11ExtensionParams::numBreadcrumbMarkers. This enables the API (if available) and allocates a system memory buffer
/// which is returned to the user in \ref AGSDX11ReturnedParams::breadcrumbBuffer.
///
/// The user can now write markers before and after draw calls using \ref agsDriverExtensionsDX11_WriteBreadcrumb.
///
/// \section background Background
///
/// A top-of-pipe (TOP) command is scheduled for execution as soon as the command processor (CP) reaches the command.
/// A bottom-of-pipe (BOP) command is scheduled for execution once the previous rendering commands (draw and dispatch) finish execution.
/// TOP and BOP commands do not block CP. i.e. the CP schedules the command for execution then proceeds to the next command without waiting.
/// To effectively use TOP and BOP commands, it is important to understand how they interact with rendering commands:
///
/// When the CP encounters a rendering command it queues it for execution and moves to the next command. The queued rendering commands are issued in order.
/// There can be multiple rendering commands running in parallel. When a rendering command is issued we say it is at the top of the pipe. When a rendering command
/// finishes execution we say it has reached the bottom of the pipe.
///
/// A BOP command remains in a waiting queue and is executed once prior rendering commands finish. The queue of BOP commands is limited to 64 entries in GCN generation 1, 2, 3, 4 and 5.
/// If the 64 limit is reached the CP will stop queueing BOP commands and also rendering commands. Developers should limit the number of BOP commands that write markers to avoid contention.
/// In general, developers should limit both TOP and BOP commands to avoid stalling the CP.
///
/// \subsection eg1 Example 1:
///
/// \code{.cpp}
/// // Start of a command buffer
/// WriteMarker(TopOfPipe, 1)
/// WriteMarker(BottomOfPipe, 2)
/// WriteMarker(BottomOfPipe, 3)
/// DrawX
/// WriteMarker(BottomOfPipe, 4)
/// WriteMarker(BottomOfPipe, 5)
/// WriteMarker(TopOfPipe, 6)
/// // End of command buffer
/// \endcode
///
/// In the above example, the CP writes markers 1, 2 and 3 without waiting:
/// Marker 1 is TOP so it's independent from other commands
/// There's no wait for marker 2 and 3 because there are no draws preceding the BOP commands
/// Marker 4 is only written once DrawX finishes execution
/// Marker 5 doesn't wait for additional draws so it is written right after marker 4
/// Marker 6 can be written as soon as the CP reaches the command. For instance, it is very possible that CP writes marker 6 while DrawX
/// is running and therefore marker 6 gets written before markers 4 and 5
///
/// \subsection eg2 Example 2:
///
/// \code{.cpp}
/// WriteMarker(TopOfPipe, 1)
/// DrawX
/// WriteMarker(BottomOfPipe, 2)
/// WriteMarker(TopOfPipe, 3)
/// DrawY
/// WriteMarker(BottomOfPipe, 4)
/// \endcode
///
/// In this example marker 1 is written before the start of DrawX
/// Marker 2 is written once DrawX finishes execution
/// Similarly marker 3 is written before the start of DrawY
/// Marker 4 is written once DrawY finishes execution
/// In case of a GPU hang, if markers 1 and 3 are written but markers 2 and 4 are missing we can conclude that:
/// The CP has reached both DrawX and DrawY commands since marker 1 and 3 are present
/// The fact that marker 2 and 4 are missing means that either DrawX is hanging while DrawY is at the top of the pipe or both DrawX and DrawY
/// started and both are simultaneously hanging
///
/// \subsection eg3 Example 3:
///
/// \code{.cpp}
/// // Start of a command buffer
/// WriteMarker(BottomOfPipe, 1)
/// DrawX
/// WriteMarker(BottomOfPipe, 2)
/// DrawY
/// WriteMarker(BottomOfPipe, 3)
/// DrawZ
/// WriteMarker(BottomOfPipe, 4)
/// // End of command buffer
/// \endcode
///
/// In this example marker 1 is written before the start of DrawX
/// Marker 2 is written once DrawX finishes
/// Marker 3 is written once DrawY finishes
/// Marker 4 is written once DrawZ finishes
/// If the GPU hangs and only marker 1 is written we can conclude that the hang is happening in either DrawX, DrawY or DrawZ
/// If the GPU hangs and only marker 1 and 2 are written we can conclude that the hang is happening in DrawY or DrawZ
/// If the GPU hangs and only marker 4 is missing we can conclude that the hang is happening in DrawZ
///
/// \subsection eg4 Example 4:
///
/// \code{.cpp}
/// Start of a command buffer
/// WriteMarker(TopOfPipe, 1)
/// DrawX
/// WriteMarker(TopOfPipe, 2)
/// DrawY
/// WriteMarker(TopOfPipe, 3)
/// DrawZ
/// // End of command buffer
/// \endcode
///
/// In this example, in case the GPU hangs and only marker 1 is written we can conclude that the hang is happening in DrawX
/// In case the GPU hangs and only marker 1 and 2 are written we can conclude that the hang is happening in DrawX or DrawY
/// In case the GPU hangs and all 3 markers are written we can conclude that the hang is happening in any of DrawX, DrawY or DrawZ
///
/// \subsection eg5 Example 5:
///
/// \code{.cpp}
/// DrawX
/// WriteMarker(TopOfPipe, 1)
/// WriteMarker(BottomOfPipe, 2)
/// DrawY
/// WriteMarker(TopOfPipe, 3)
/// WriteMarker(BottomOfPipe, 4)
/// \endcode
///
/// Marker 1 is written right after DrawX is queued for execution.
/// Marker 2 is only written once DrawX finishes execution.
/// Marker 3 is written right after DrawY is queued for execution.
/// Marker 4 is only written once DrawY finishes execution
/// If marker 1 is written we would know that the CP has reached the command DrawX (DrawX at the top of the pipe).
/// If marker 2 is written we can say that DrawX has finished execution (DrawX at the bottom of the pipe).
/// In case the GPU hangs and only marker 1 and 3 are written we can conclude that the hang is happening in DrawX or DrawY
/// In case the GPU hangs and only marker 1 is written we can conclude that the hang is happening in DrawX
/// In case the GPU hangs and only marker 4 is missing we can conclude that the hang is happening in DrawY
///
/// \section data Retrieving GPU Data
///
/// In the event of a GPU hang, the user can inspect the system memory buffer to determine which draw has caused the hang.
/// For example:
/// \code{.cpp}
/// // Force the work to be flushed to prevent CPU ahead of GPU
/// g_pImmediateContext->Flush();
///
/// // Present the information rendered to the back buffer to the front buffer (the screen)
/// HRESULT hr = g_pSwapChain->Present( 0, 0 );
///
/// // Read the marker data buffer once detect device lost
/// if ( hr != S_OK )
/// {
/// for (UINT i = 0; i < g_NumMarkerWritten; i++)
/// {
/// UINT64* pTempData;
/// pTempData = static_cast<UINT64*>(pMarkerBuffer);
///
/// // Write the marker data to file
/// ofs << i << "\r\n";
/// ofs << std::hex << *(pTempData + i * 2) << "\r\n";
/// ofs << std::hex << *(pTempData + (i * 2 + 1)) << "\r\n";
///
/// WCHAR s1[256];
/// setlocale(LC_NUMERIC, "en_US.iso88591");
///
/// // Output the marker data to console
/// swprintf(s1, 256, L" The Draw count is %d; The Top maker is % 016llX and the Bottom marker is % 016llX \r\n", i, *(pTempData + i * 2), *(pTempData + (i * 2 + 1)));
///
/// OutputDebugStringW(s1);
/// }
/// }
/// \endcode
///
/// The console output would resemble something like:
/// \code{.cpp}
/// D3D11: Removing Device.
/// D3D11 ERROR: ID3D11Device::RemoveDevice: Device removal has been triggered for the following reason (DXGI_ERROR_DEVICE_HUNG: The Device took an unreasonable amount of time to execute its commands, or the hardware crashed/hung. As a result, the TDR (Timeout Detection and Recovery) mechanism has been triggered. The current Device Context was executing commands when the hang occurred. The application may want to respawn and fallback to less aggressive use of the display hardware). [ EXECUTION ERROR #378: DEVICE_REMOVAL_PROCESS_AT_FAULT]
/// The Draw count is 0; The Top maker is 00000000DEADCAFE and the Bottom marker is 00000000DEADBEEF
/// The Draw count is 1; The Top maker is 00000000DEADCAFE and the Bottom marker is 00000000DEADBEEF
/// The Draw count is 2; The Top maker is 00000000DEADCAFE and the Bottom marker is 00000000DEADBEEF
/// The Draw count is 3; The Top maker is 00000000DEADCAFE and the Bottom marker is 00000000DEADBEEF
/// The Draw count is 4; The Top maker is 00000000DEADCAFE and the Bottom marker is 00000000DEADBEEF
/// The Draw count is 5; The Top maker is CDCDCDCDCDCDCDCD and the Bottom marker is CDCDCDCDCDCDCDCD
/// The Draw count is 6; The Top maker is CDCDCDCDCDCDCDCD and the Bottom marker is CDCDCDCDCDCDCDCD
/// The Draw count is 7; The Top maker is CDCDCDCDCDCDCDCD and the Bottom marker is CDCDCDCDCDCDCDCD
/// \endcode
///
/// @{
/// The breadcrumb marker struct used by \ref agsDriverExtensionsDX11_WriteBreadcrumb
typedef struct AGSBreadcrumbMarker
{
/// The marker type
typedef enum Type
{
TopOfPipe = 0, ///< Top-of-pipe marker
BottomOfPipe = 1 ///< Bottom-of-pipe marker
} Type;
unsigned long long markerData; ///< The user data to write.
Type type; ///< Whether this marker is top or bottom of pipe.
unsigned int index; ///< The index of the marker. This should be less than the value specified in \ref AGSDX11ExtensionParams::numBreadcrumbMarkers
} AGSBreadcrumbMarker;
///
/// Function to write a breadcrumb marker.
///
/// This method inserts a write marker operation in the GPU command stream. In the case where the GPU is hanging the write
/// command will never be reached and the marker will never get written to memory.
///
/// In order to use this function, \ref AGSDX11ExtensionParams::numBreadcrumbMarkers must be set to a non zero value.
///
/// \param [in] context Pointer to a context.
/// \param [in] marker Pointer to a marker.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_WriteBreadcrumb( AGSContext* context, const AGSBreadcrumbMarker* marker );
/// @}
/// \defgroup dx11Topology Extended Topology
/// API for primitive topologies
/// @{
/// Additional topologies supported via extensions
typedef enum AGSPrimitiveTopologyDX11
{
AGS_PRIMITIVE_TOPOLOGY_QUADLIST = 7, ///< Quad list
AGS_PRIMITIVE_TOPOLOGY_SCREENRECTLIST = 9 ///< Screen rect list
} AGSPrimitiveTopologyDX11;
///
/// Function used to set the primitive topology. If you are using any of the extended topology types, then this function should
/// be called to set ALL topology types.
///
/// The Quad List extension is a convenient way to submit quads without using an index buffer. Note that this still submits two triangles at the driver level.
/// In order to use this function, AGS must already be initialized and agsDriverExtensionsDX11_Init must have been called successfully.
///
/// The Screen Rect extension, which is only available on GCN hardware, allows the user to pass in three of the four corners of a rectangle.
/// The hardware then uses the bounding box of the vertices to rasterize the rectangle primitive (i.e. as a rectangle rather than two triangles).
/// \note Note that this will not return valid interpolated values, only valid SV_Position values.
/// \note If either the Quad List or Screen Rect extension are used, then agsDriverExtensionsDX11_IASetPrimitiveTopology should be called in place of the native DirectX11 equivalent all the time.
///
/// \param [in] context Pointer to a context.
/// \param [in] topology The topology to set on the D3D11 device. This can be either an AGS-defined topology such as AGS_PRIMITIVE_TOPOLOGY_QUADLIST
/// or a standard D3D-defined topology such as D3D_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP.
/// NB. the AGS-defined types will require casting to a D3D_PRIMITIVE_TOPOLOGY type.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_IASetPrimitiveTopology( AGSContext* context, D3D_PRIMITIVE_TOPOLOGY topology );
/// @}
/// \defgroup dx11UAVOverlap UAV Overlap
/// API for enabling overlapping UAV writes
///
/// The AMD DX11 driver will automatically track resource usage and insert barriers as necessary to clear read-after-write (RAW) and write-after-write (WAW)
/// hazards. The UAV overlap extension allows applications to indicate to the driver it can skip inserting barriers for UAV resources used in
/// dispatches and draws within the \ref agsDriverExtensionsDX11_BeginUAVOverlap/ \ref agsDriverExtensionsDX11_EndUAVOverlap calls. This can be useful for applications to allow
/// multiple back-to-back dispatches or draws in flight even if they are accessing the same UAV resource but the data written or read does not overlap within the resource.
///
/// Usage would be as follows:
/// \code{.cpp}
/// m_device->Dispatch( ... ); // First call that writes to the UAV
///
/// // Disable automatic WAW syncs
/// agsDriverExtensionsDX11_BeginUAVOverlap( m_agsContext );
///
/// // Submit other dispatches that write to the same UAV concurrently
/// m_device->Dispatch( ... );
/// m_device->Dispatch( ... );
/// m_device->Dispatch( ... );
///
/// // Reenable automatic WAW syncs
/// agsDriverExtensionsDX11_EndUAVOverlap( m_agsContext );
/// \endcode
/// @{
///
/// Function used indicate to the driver the start of the overlap scope.
///
/// \param [in] context Pointer to a context.
/// \param [in] dxContext Pointer to the DirectX device context. If this is to work using the non-immediate context, then you need to check support. If nullptr is specified, then the immediate context is assumed.
/// with the AGS_DX11_EXTENSION_DEFERRED_CONTEXTS bit.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_BeginUAVOverlap( AGSContext* context, ID3D11DeviceContext* dxContext );
///
/// Function used indicate to the driver the end of the overlap scope.
///
/// \param [in] context Pointer to a context.
/// \param [in] dxContext Pointer to the DirectX device context. If this is to work using the non-immediate context, then you need to check support. If nullptr is specified, then the immediate context is assumed.
/// with the AGS_DX11_EXTENSION_DEFERRED_CONTEXTS bit.
///
AMD_AGS_API AGSReturnCode agsDriverExtensionsDX11_EndUAVOverlap( AGSContext* context, ID3D11DeviceContext* dxContext );
/// @}