Mantle Programming Guide and API Reference

435 Pages·2015·1.97 MB·English

by  Guennadi Riguer

Mantle Programming Guide
and API Reference
Revision 1.0
March 6, 2015
The information presented in this document is for informational purposes only and may contain
technical inaccuracies, omissions and typographical errors.
The information contained herein is subject to change and may be rendered inaccurate for many
reasons, including but not limited to product and roadmap changes, component and motherboard
version changes, new model and/or product releases, product differences between differing
manufacturers, software changes, BIOS flashes, firmware upgrades, or the like. AMD assumes no
obligation to update or otherwise correct or revise this information. However, AMD reserves the
right to revise this information and to make changes from time to time to the content hereof
without obligation of AMD to notify any person of such revisions or changes.
AMD MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF
AND ASSUMES NO RESPONSIBILITY FOR ANY INACCURACIES, ERRORS OR OMISSIONS THAT MAY
APPEAR IN THIS INFORMATION.
AMD SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR
ANY PARTICULAR PURPOSE. IN NO EVENT WILL AMD BE LIABLE TO ANY PERSON FOR ANY DIRECT,
INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES ARISING FROM THE USE OF ANY
INFORMATION CONTAINED HEREIN, EVEN IF AMD IS EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
ATTRIBUTION
© 2015 Advanced Micro Devices, Inc. All rights reserved. AMD, the AMD Arrow logo and
combinations thereof are trademarks of Advanced Micro Devices, Inc. in the United States and/or
other jurisdictions. Other names are for informational purposes only and may be trademarks of
their respective owners.
T C
ABLE OF ONTENTS
Chapter I. Introduction......................................................................................................................9
Motivation.............................................................................................................................................9
Solution Overview.................................................................................................................................9
Developer Manifesto...........................................................................................................................11
Chapter II. Programming Overview..................................................................................................12
Software Infrastructure.......................................................................................................................12
Mantle Libraries in Windows..........................................................................................................13
Execution Model..................................................................................................................................15
Memory in Mantle...............................................................................................................................17
Objects in Mantle................................................................................................................................18
Pipelines and Shaders..........................................................................................................................18
Window and Presentation Systems.....................................................................................................19
Error Checking and Return Codes.......................................................................................................19
Lost Mantle Devices........................................................................................................................20
Debug and Validation Layer............................................................................................................20
Chapter III. Basic Mantle Operation.................................................................................................21
GPU Identification and Initialization...................................................................................................21
Device Creation...................................................................................................................................22
GPU Memory Heaps............................................................................................................................24
GPU Memory Objects..........................................................................................................................25
GPU Memory Priority.....................................................................................................................26
CPU Access to GPU Memory Objects.............................................................................................27
Pinned Memory..............................................................................................................................28
Virtual Memory Remapping...........................................................................................................28
Memory Allocation and Management Strategy.............................................................................30
Generic Mantle API objects.................................................................................................................32
API Object Destruction...................................................................................................................32
Querying API Object Properties......................................................................................................33
Querying Parent Device..................................................................................................................33
API Object Memory Binding...........................................................................................................33
Image Memory Binding..................................................................................................................35
Queues and Command Buffers...........................................................................................................36
Queues............................................................................................................................................36
Command Buffers...........................................................................................................................37
Command Buffer Building...............................................................................................................38
Command Buffer Optimizations.....................................................................................................40
Command Buffer Submission.........................................................................................................40
GPU Memory References...............................................................................................................41
Read-only GPU Memory References..............................................................................................42
Mantle Programming Guide Page 1
Compute Dispatch Operations............................................................................................................44
Indirect Dispatch.............................................................................................................................44
Rendering Operations.........................................................................................................................44
Indirect Rendering..........................................................................................................................45
Primitive Topology..........................................................................................................................46
Queries................................................................................................................................................46
Timestamps.........................................................................................................................................48
Synchronization...................................................................................................................................48
Command Buffer Fences.................................................................................................................48
Events..............................................................................................................................................49
Queue Semaphores........................................................................................................................50
Draining Queues.............................................................................................................................51
Queue Memory Atomics.....................................................................................................................51
Shader Atomic Counters......................................................................................................................51
Chapter IV. Resource Objects and Views..........................................................................................53
Memory Views.....................................................................................................................................53
Images.................................................................................................................................................54
Image Organization and Subresources...........................................................................................55
Image Aspects.................................................................................................................................55
1D Images.......................................................................................................................................56
2D Images.......................................................................................................................................56
Cubemaps.......................................................................................................................................57
3D Images.......................................................................................................................................57
Image Tiling and Image Data Organization.....................................................................................58
Retrieving Image Properties...........................................................................................................58
Resource Formats and Capabilities.....................................................................................................59
Compressed Images........................................................................................................................60
Multisampled Images..........................................................................................................................60
Image Views.........................................................................................................................................60
Render Targets.....................................................................................................................................64
Color Targets...................................................................................................................................64
Depth-Stencil Targets......................................................................................................................65
Target Binding.................................................................................................................................67
Read-only Depth-stencil Views.......................................................................................................67
View Format Compatibility..................................................................................................................68
Data Feedback Loop............................................................................................................................68
Resource Aliasing.................................................................................................................................68
Invariant Image Data...........................................................................................................................69
Resource States and Preparation........................................................................................................70
Memory and Image States..............................................................................................................70
Initial Resource State......................................................................................................................72
Data Transfer States........................................................................................................................73
State Preparations..........................................................................................................................73
Mantle Programming Guide Page 2
Multisampled Image Preparation...................................................................................................75
Memory and Image State Reset.....................................................................................................75
Multi-Queue Considerations..........................................................................................................75
Hazards...........................................................................................................................................76
Resource Operations...........................................................................................................................78
Resource Copies..............................................................................................................................79
Image Cloning.................................................................................................................................80
Immediate Memory Updates.........................................................................................................80
Resource Upload Strategies............................................................................................................81
Memory Fill.....................................................................................................................................81
Image Clears....................................................................................................................................82
Multisampled Image Resolves........................................................................................................83
Image Samplers...................................................................................................................................83
Resource Shader Binding.....................................................................................................................84
Descriptor Sets................................................................................................................................84
Descriptor Set Updates...................................................................................................................86
Chapter V. State, Shaders, and Pipelines..........................................................................................88
Mantle State Overview........................................................................................................................88
Static vs. Dynamic State..................................................................................................................88
Dynamic State Objects........................................................................................................................89
Rasterizer State...............................................................................................................................90
Viewport and Scissor State.............................................................................................................90
Color Blender State.........................................................................................................................90
Depth-stencil State.........................................................................................................................92
Multisampling State........................................................................................................................92
Default Sample Patterns.................................................................................................................92
Shaders................................................................................................................................................93
Pipelines..............................................................................................................................................93
Compute Pipelines...............................................................................................................................94
Graphics Pipelines...............................................................................................................................95
Graphics Pipeline Operation...........................................................................................................98
Vertex Fetch in Graphics Pipeline...................................................................................................98
Graphics Pipeline State...................................................................................................................98
“Re-Z” Support for Pixel Shaders..................................................................................................100
Graphics Pipeline Shader Linking..................................................................................................101
Pipeline Serialization.........................................................................................................................101
Constant-Based Pipeline Compilation...............................................................................................102
Pipeline Binding.................................................................................................................................102
Pipeline Resource Access..................................................................................................................103
Pipeline Resource Mapping..........................................................................................................103
Descriptor Set Binding..................................................................................................................106
Dynamic Memory View................................................................................................................106
Chapter VI. Multi-device Operation...............................................................................................108
Mantle Programming Guide Page 3
Overview............................................................................................................................................108
Multi-device Configurations..............................................................................................................109
Symmetric AMD CrossFire™ Configurations.................................................................................109
Asymmetric AMD CrossFire™ Configurations...............................................................................109
Asymmetric Configurations not Supported by AMD CrossFire™.................................................109
Other Multi-device Configurations...............................................................................................109
Multiple Devices................................................................................................................................110
GPU Device Selection...................................................................................................................111
Image Quality Matching...............................................................................................................112
Sharing Memory between GPUs.......................................................................................................112
Discovery of Shareable Heaps......................................................................................................113
Shared Memory Creation.............................................................................................................113
Shared Images..............................................................................................................................114
Queue Semaphore Sharing...............................................................................................................114
Shared Semaphore Creation.........................................................................................................114
Peer-to-peer Transfers.......................................................................................................................115
Opening Peer Memory.................................................................................................................115
Opening Peer Images....................................................................................................................116
Peer Transfer Execution................................................................................................................116
Compositing and Cross-device Presentation.....................................................................................117
Discovering Cross-device Display Capabilities..............................................................................117
Cross-device Presentable Images.................................................................................................118
Cross-device Presentation............................................................................................................118
Chapter VII. Debugging and Validation Layer.................................................................................119
Debug Device Initialization................................................................................................................119
Validation Levels...........................................................................................................................120
Debugger Callback.............................................................................................................................120
Debug Message Filtering..............................................................................................................121
Object Debug Data............................................................................................................................122
Object Tagging..............................................................................................................................122
Generic Object Information..........................................................................................................122
Memory Object Information........................................................................................................124
Command Buffer Trace.................................................................................................................125
Queue Semaphore State...............................................................................................................125
Command Buffer Markers.................................................................................................................125
Tag and Marker Formatting Convention...........................................................................................125
Debug Infrastructure Settings...........................................................................................................126
Chapter VIII. Mantle Extension Mechanism...................................................................................127
Extension Discovery...........................................................................................................................128
AMD Extension Library......................................................................................................................128
Chapter IX. Window System Interface for Windows®.....................................................................129
Extension Overview...........................................................................................................................129
Mantle Programming Guide Page 4
Extension Discovery......................................................................................................................130
Windowed Mode Overview..............................................................................................................130
Fullscreen Mode Overview................................................................................................................130
Display Objects.............................................................................................................................130
Fullscreen Exclusive Mode............................................................................................................131
Gamma Ramp Control..................................................................................................................132
CPU/Display Coordination.................................................................................................................132
Presentation......................................................................................................................................133
Presentable Images.......................................................................................................................133
Query Queue Support...................................................................................................................134
Present..........................................................................................................................................134
Display Rotation for Present.........................................................................................................134
Presentable Image Preparation....................................................................................................135
Presentation Queue Limit.............................................................................................................135
Querying Presentable Image Properties.......................................................................................136
Chapter X. DMA Queue Extension.................................................................................................137
Extension Overview...........................................................................................................................137
Extension Discovery......................................................................................................................137
DMA Queue Type..............................................................................................................................138
Memory and Image State..................................................................................................................138
DMA Command Buffer Building Functions.......................................................................................139
Functional Limitations.......................................................................................................................139
General Limitations.......................................................................................................................140
grCmdCopyMemory Limitations...................................................................................................140
grCmdCopyImage Limitations.......................................................................................................140
grCmdCopyMemoryToImage Limitations.....................................................................................140
grCmdCopyMemoryToImage Limitations.....................................................................................141
grCmdFillMemory Limitations......................................................................................................141
grCmdUpdateMemory Limitations...............................................................................................141
grCmdWriteTimestamp Limitations..............................................................................................141
Chapter XI. Timer Queue Extension...............................................................................................142
Extension Overview...........................................................................................................................142
Extension Discovery......................................................................................................................142
Timer Queue Type.............................................................................................................................142
Timed Delays.....................................................................................................................................143
Chapter XII. Advanced Multisampling Extension............................................................................144
Extension Overview...........................................................................................................................144
Extension Discovery......................................................................................................................145
EQAA Images.....................................................................................................................................145
EQAA Resolve Behavior................................................................................................................145
EQAA Image View Behavior..........................................................................................................146
Advanced Multisampling State..........................................................................................................146
Mantle Programming Guide Page 5
Sample Rates................................................................................................................................146
Sample Clustering for Over-rasterization.....................................................................................147
Alpha-to-coverage Controls..........................................................................................................147
Custom Sample Patterns...............................................................................................................148
Multisampled Image FMask..............................................................................................................150
FMask Image Views......................................................................................................................150
FMask Preparation........................................................................................................................151
FMask Shader Access....................................................................................................................151
Chapter XIII. Border Color Palette Extension..................................................................................153
Extension Overview...........................................................................................................................153
Extension Discovery......................................................................................................................153
Querying Queue Support..................................................................................................................154
Palette Management.........................................................................................................................154
Palette Binding..................................................................................................................................154
Sampler Border Color Palette Support..............................................................................................155
Chapter XIV. Occlusion Query Data Copy Extension.......................................................................157
Extension Overview...........................................................................................................................157
Extension Discovery......................................................................................................................157
Copying Occlusion Results.................................................................................................................158
Chapter XV. GPU Timestamp Calibration Extension........................................................................159
Extension Overview...........................................................................................................................159
Extension Discovery......................................................................................................................159
Calibrating GPU Timestamps.............................................................................................................160
Chapter XVI. Command Buffer Control Flow Extension..................................................................161
Extension Overview...........................................................................................................................161
Extension Discovery......................................................................................................................161
Control Flow Operation.....................................................................................................................162
Querying Support..............................................................................................................................162
Predication........................................................................................................................................163
Occlusion-Based Predication........................................................................................................163
Memory Value Based Predication................................................................................................164
Conditional Command Buffer Execution...........................................................................................164
Loops in Command Buffers...............................................................................................................165
Memory State for Control Flow.........................................................................................................166
Chapter XVII. Resource State Access Extension..............................................................................167
Extension Overview...........................................................................................................................167
Extension Discovery......................................................................................................................167
Extended Memory and Image States................................................................................................168
Chapter XVIII. Mantle API Reference..............................................................................................172
Functions...........................................................................................................................................172
Initialization and Device Functions...............................................................................................172
Mantle Programming Guide Page 6
Extension Discovery Functions.....................................................................................................177
Queue Functions...........................................................................................................................178
Memory Management Functions.................................................................................................183
Generic API Object Management Functions................................................................................192
Image and Sampler Functions......................................................................................................196
Image View Functions...................................................................................................................202
Shader and Pipeline Functions.....................................................................................................206
Descriptor Set Functions...............................................................................................................213
State Object Functions..................................................................................................................219
Query and Synchronization Function...........................................................................................224
Multi-device Management Functions..........................................................................................234
Command Buffer Management Functions...................................................................................239
Command Buffer Building Functions............................................................................................243
Enumerations....................................................................................................................................268
Flags...................................................................................................................................................300
Data Structures..................................................................................................................................308
Callbacks............................................................................................................................................353
Errors and Return Codes...................................................................................................................354
Chapter XIX. Mantle Debug and Validation API Reference.............................................................357
Functions...........................................................................................................................................357
Enumerations....................................................................................................................................364
Callbacks............................................................................................................................................370
Chapter XX. Window System Interface (WSI) for Windows............................................................371
Functions...........................................................................................................................................371
Enumerations....................................................................................................................................380
Flags...................................................................................................................................................383
Data Structures..................................................................................................................................385
Errors and Return Codes...................................................................................................................391
Chapter XXI. Mantle Extension Reference......................................................................................392
Library Versioning..............................................................................................................................392
Functions......................................................................................................................................392
Enumerations................................................................................................................................393
Data Structures.............................................................................................................................394
Border Color Palette Extension.........................................................................................................395
Functions......................................................................................................................................395
Enumerations................................................................................................................................398
Data Structures.............................................................................................................................399
Advanced Multisampling Extension..................................................................................................400
Functions......................................................................................................................................400
Enumerations................................................................................................................................402
Data Structures.............................................................................................................................403
Copy Occlusion Query Data Extension..............................................................................................406
Mantle Programming Guide Page 7
Functions......................................................................................................................................406
Enumerations................................................................................................................................408
Command Buffer Control Flow Extension.........................................................................................409
Functions......................................................................................................................................409
Enumerations................................................................................................................................414
Flags..............................................................................................................................................415
Data Structures.............................................................................................................................416
DMA Queue Extension......................................................................................................................417
Enumerations................................................................................................................................417
Timer Queue Extension.....................................................................................................................418
Functions......................................................................................................................................418
Enumerations................................................................................................................................419
GPU Timestamp Calibration Extension..............................................................................................420
Functions......................................................................................................................................420
Data Structures.............................................................................................................................421
Resource State Access Extension......................................................................................................422
Flags..............................................................................................................................................422
Appendix A. Mantle Class Diagram................................................................................................423
Appendix B. Feature Mapping to Other APIs..................................................................................425
Appendix C. Format Capabilities....................................................................................................427
Appendix D. Command Buffer Building Function Summary............................................................430
Mantle Programming Guide Page 8