Vulkan 1.0.19 + WSI Extensions - A Specification

The Khronos Vulkan Working Group

Revision History
Revision 1.0.19Fri Jul 1 09:14:53 UTC 2016T
from git branch: 1.0-wsi_extensions commit: 89287838eafadc0c8a53c487026498fe59380e78

Table of Contents

1. Introduction
1.1. What is the Vulkan Graphics System?
1.1.1. The Programmer’s View of Vulkan
1.1.2. The Implementor’s View of Vulkan
1.1.3. Our View of Vulkan
1.2. Filing Bug Reports
1.3. Terminology
1.4. Normative References
2. Fundamentals
2.1. Architecture Model
2.2. Execution Model
2.2.1. Queue Operation
2.3. Object Model
2.3.1. Object Lifetime
2.4. Command Syntax and Duration
2.5. Threading Behavior
2.6. Errors
2.6.1. Valid Usage
2.6.2. Return Codes
2.7. Numeric Representation and Computation
2.7.1. Floating-Point Computation
2.7.2. 16-Bit Floating-Point Numbers
2.7.3. Unsigned 11-Bit Floating-Point Numbers
2.7.4. Unsigned 10-Bit Floating-Point Numbers
2.7.5. General Requirements
2.8. Fixed-Point Data Conversions
2.8.1. Conversion from Normalized Fixed-Point to Floating-Point
2.8.2. Conversion from Floating-Point to Normalized Fixed-Point
2.9. API Version Numbers and Semantics
2.10. Common Object Types
2.10.1. Offsets
2.10.2. Extents
2.10.3. Rectangles
3. Initialization
3.1. Command Function Pointers
3.2. Instances
4. Devices and Queues
4.1. Physical Devices
4.2. Devices
4.2.1. Device Creation
4.2.2. Device Use
4.2.3. Lost Device
4.2.4. Device Destruction
4.3. Queues
4.3.1. Queue Family Properties
4.3.2. Queue Creation
4.3.3. Queue Family Index
4.3.4. Queue Priority
4.3.5. Queue Submission
4.3.6. Queue Destruction
5. Command Buffers
5.1. Command Pools
5.2. Command Buffer Allocation and Management
5.3. Command Buffer Recording
5.4. Command Buffer Submission
5.5. Queue Forward Progress
5.6. Secondary Command Buffer Execution
6. Synchronization and Cache Control
6.1. Fences
6.2. Semaphores
6.3. Events
6.4. Execution And Memory Dependencies
6.5. Pipeline Barriers
6.5.1. Subpass Self-dependency
6.5.2. Pipeline Stage Flags
6.5.3. Memory Barriers
6.5.4. Global Memory Barriers
6.5.5. Buffer Memory Barriers
6.5.6. Image Memory Barriers
6.5.7. Wait Idle Operations
6.6. Host Write Ordering Guarantees
7. Render Pass
7.1. Render Pass Creation
7.2. Render Pass Compatibility
7.3. Framebuffers
7.4. Render Pass Commands
8. Shaders
8.1. Shader Modules
8.2. Shader Execution
8.3. Shader Memory Access Ordering
8.4. Shader Inputs and Outputs
8.5. Vertex Shaders
8.5.1. Vertex Shader Execution
8.6. Tessellation Control Shaders
8.6.1. Tessellation Control Shader Execution
8.7. Tessellation Evaluation Shaders
8.7.1. Tessellation Evaluation Shader Execution
8.8. Geometry Shaders
8.8.1. Geometry Shader Execution
8.9. Fragment Shaders
8.9.1. Fragment Shader Execution
8.9.2. Early Fragment Tests
8.10. Compute Shaders
8.11. Interpolation Decorations
8.12. Static Use
8.13. Invocation and Derivative Groups
9. Pipelines
9.1. Compute Pipelines
9.2. Graphics Pipelines
9.3. Pipeline destruction
9.4. Multiple Pipeline Creation
9.5. Pipeline Derivatives
9.6. Pipeline Cache
9.7. Specialization Constants
9.8. Pipeline Binding
10. Memory Allocation
10.1. Host Memory
10.2. Device Memory
10.2.1. Host Access to Device Memory Objects
10.2.2. Lazily Allocated Memory
11. Resource Creation
11.1. Buffers
11.2. Buffer Views
11.3. Images
11.4. Image Layouts
11.5. Image Views
11.6. Resource Memory Association
11.7. Resource Sharing Mode
11.8. Memory Aliasing
12. Samplers
13. Resource Descriptors
13.1. Descriptor Types
13.1.1. Storage Image
13.1.2. Sampler
13.1.3. Sampled Image
13.1.4. Combined Image Sampler
13.1.5. Uniform Texel Buffer
13.1.6. Storage Texel Buffer
13.1.7. Uniform Buffer
13.1.8. Storage Buffer
13.1.9. Dynamic Uniform Buffer
13.1.10. Dynamic Storage Buffer
13.1.11. Input Attachment
13.2. Descriptor Sets
13.2.1. Descriptor Set Layout
13.2.2. Pipeline Layouts
13.2.3. Allocation of Descriptor Sets
13.2.4. Descriptor Set Updates
13.2.5. Descriptor Set Binding
13.2.6. Push Constant Updates
14. Shader Interfaces
14.1. Shader Input and Output Interfaces
14.1.1. Built-in Interface Block
14.1.2. User-defined Variable Interface
14.1.3. Interface Matching
14.1.4. Location Assignment
14.1.5. Component Assignment
14.2. Vertex Input Interface
14.3. Fragment Output Interface
14.4. Fragment Input Attachment Interface
14.5. Shader Resource Interface
14.5.1. Push Constant Interface
14.5.2. Descriptor Set Interface
14.5.3. DescriptorSet and Binding Assignment
14.5.4. Offset and Stride Assignment
14.6. Built-In Variables
15. Image Operations
15.1. Image Operations Overview
15.1.1. Texel Coordinate Systems
15.2. Conversion Formulas
15.2.1. RGB to Shared Exponent Conversion
15.2.2. Shared Exponent to RGB
15.3. Texel Input Operations
15.3.1. Texel Input Validation Operations
15.3.2. Format Conversion
15.3.3. Texel Replacement
15.3.4. Depth Compare Operation
15.3.5. Conversion to RGBA
15.3.6. Component Swizzle
15.3.7. Sparse Residency
15.4. Texel Output Operations
15.4.1. Texel Output Validation Operations
15.4.2. Integer Texel Coordinate Validation
15.4.3. Sparse Texel Operation
15.4.4. Texel Output Format Conversion
15.5. Derivative Operations
15.6. Normalized Texel Coordinate Operations
15.6.1. Projection Operation
15.6.2. Derivative Image Operations
15.6.3. Cube Map Face Selection and Transformations
15.6.4. Cube Map Face Selection
15.6.5. Cube Map Coordinate Transformation
15.6.6. Cube Map Derivative Transformation
15.6.7. Scale Factor Operation, Level-of-Detail Operation and Image Level(s) Selection
15.6.8. (s,t,r,q,a) to (u,v,w,a) Transformation
15.7. Unnormalized Texel Coordinate Operations
15.7.1. (u,v,w,a) to (i,j,k,l,n) Transformation And Array Layer Selection
15.8. Image Sample Operations
15.8.1. Wrapping Operation
15.8.2. Texel Gathering
15.8.3. Texel Filtering
15.8.4. Texel Anisotropic Filtering
15.9. Image Operation Steps
16. Queries
16.1. Query Pools
16.2. Query Operation
16.3. Occlusion Queries
16.4. Pipeline Statistics Queries
16.5. Timestamp Queries
17. Clear Commands
17.1. Clearing Images Outside A Render Pass Instance
17.2. Clearing Images Inside A Render Pass Instance
17.3. Clear Values
17.4. Filling Buffers
17.5. Updating Buffers
18. Copy Commands
18.1. Common Operation
18.2. Copying Data Between Buffers
18.3. Copying Data Between Images
18.4. Copying Data Between Buffers and Images
18.5. Image Copies with Scaling
18.6. Resolving Multisample Images
19. Drawing Commands
19.1. Primitive Topologies
19.1.1. Points
19.1.2. Separate Lines
19.1.3. Line Strips
19.1.4. Triangle Strips
19.1.5. Triangle Fans
19.1.6. Separate Triangles
19.1.7. Lines With Adjacency
19.1.8. Line Strips With Adjacency
19.1.9. Triangle List With Adjacency
19.1.10. Triangle Strips With Adjacency
19.1.11. Separate Patches
19.1.12. General Considerations For Polygon Primitives
19.2. Programmable Primitive Shading
20. Fixed-Function Vertex Processing
20.1. Vertex Attributes
20.1.1. Attribute Location and Component Assignment
20.2. Vertex Input Description
20.3. Example
21. Tessellation
21.1. Tessellator
21.2. Tessellator Patch Discard
21.3. Tessellator Spacing
21.4. Triangle Tessellation
21.5. Quad Tessellation
21.6. Isoline Tessellation
21.7. Tessellation Pipeline State
22. Geometry Shading
22.1. Geometry Shader Input Primitives
22.2. Geometry Shader Output Primitives
22.3. Multiple Invocations of Geometry Shaders
22.4. Geometry Shader Primitive Ordering
23. Fixed-Function Vertex Post-Processing
23.1. Flatshading
23.2. Primitive Clipping
23.3. Clipping Shader Outputs
23.4. Coordinate Transformations
23.5. Controlling the Viewport
24. Rasterization
24.1. Discarding Primitives Before Rasterization
24.2. Multisampling
24.3. Sample Shading
24.4. Points
24.4.1. Basic Point Rasterization
24.5. Line Segments
24.5.1. Basic Line Segment Rasterization
24.6. Polygons
24.6.1. Basic Polygon Rasterization
24.6.2. Polygon Mode
24.6.3. Depth Bias
25. Fragment Operations
25.1. Early Per-Fragment Tests
25.2. Scissor Test
25.3. Sample Mask
25.4. Early Fragment Test Mode
25.5. Late Per-Fragment Tests
25.6. Multisample Coverage
25.7. Depth and Stencil Operations
25.8. Depth Bounds Test
25.9. Stencil Test
25.10. Depth Test
25.11. Sample Counting
26. The Framebuffer
26.1. Blending
26.1.1. Blend Factors
26.1.2. Dual-Source Blending
26.1.3. Blend Operations
26.2. Logical Operations
27. Dispatching Commands
28. Sparse Resources
28.1. Sparse Resource Features
28.2. Sparse Buffers and Fully-Resident Images
28.2.1. Sparse Buffer and Fully-Resident Image Block Size
28.3. Sparse Partially-Resident Buffers
28.4. Sparse Partially-Resident Images
28.4.1. Accessing Unbound Regions
28.4.2. Mip Tail Regions
28.4.3. Standard Sparse Image Block Shapes
28.4.4. Custom Sparse Image Block Shapes
28.4.5. Multiple Aspects
28.5. Sparse Memory Aliasing
28.6. Sparse Resource Implementation Guidelines
28.7. Sparse Resource API
28.7.1. Physical Device Features
28.7.2. Physical Device Sparse Properties
28.7.3. Sparse Image Format Properties
28.7.4. Sparse Resource Creation
28.7.5. Sparse Resource Memory Requirements
28.7.6. Binding Resource Memory
28.8. Examples
28.8.1. Basic Sparse Resources
28.8.2. Advanced Sparse Resources
29. Window System Integration (WSI)
29.1. WSI Platform
29.2. WSI Surface
29.2.1. Android Platform
29.2.2. Mir Platform
29.2.3. Wayland Platform
29.2.4. Win32 Platform
29.2.5. XCB Platform
29.2.6. Xlib Platform
29.2.7. Platform-Independent Information
29.3. Presenting Directly to Display Devices
29.3.1. Display Enumeration
29.3.2. Display Surfaces
29.4. Querying for WSI Support
29.4.1. Android Platform
29.4.2. Mir Platform
29.4.3. Wayland Platform
29.4.4. Win32 Platform
29.4.5. XCB Platform
29.4.6. Xlib Platform
29.5. Surface Queries
29.6. WSI Swapchain
30. Extended Functionality
30.1. Layers
30.1.1. Device Layer Deprecation
30.2. Extensions
30.2.1. Instance Extensions and Device Extensions
31. Features, Limits, and Formats
31.1. Features
31.1.1. Feature Requirements
31.2. Limits
31.2.1. Limit Requirements
31.3. Formats
31.3.1. Format Definition
31.3.2. Format Properties
31.3.3. Required Format Support
31.4. Additional Image Capabilities
31.4.1. Allowed Extent Values Based On Image Type
A. Vulkan Environment for SPIR-V
A.1. Required Versions and Formats
A.2. Capabilities
A.3. Validation Rules within a Module
A.4. Precision and Operation of SPIR-V Instructions
A.5. Compatibility Between SPIR-V Image Formats And Vulkan Formats
B. Compressed Image Formats
B.1. Block-Compressed Image Formats
B.2. ETC Compressed Image Formats
B.3. ASTC Compressed Image Formats
C. Layers & Extensions
C.1. Introduction
C.2. General Rules/Guidelines
C.3. Extension and Layer Naming Conventions
C.4. Extension Command, Type, and Token Naming Conventions
C.5. The Vulkan Registry
C.6. Registering an Author Prefix with Khronos
C.7. Registering a Vendor ID with Khronos
C.8. Registering Extensions and Layers
C.9. Documenting Extensions
C.10. Assigning Extension Token Values
C.11. Required Extension Tokens
C.12. Extension Objects, Enums, and Typedefs
C.13. Extension Function Prototypes
C.14. Accessing Extension Functions from Programs
C.14.1. Reserving Bitfield Values
C.15. Extension Interactions
C.16. VK_KHR_sampler_mirror_clamp_to_edge
C.16.1. New Enum Constants
C.16.2. Example
C.16.3. Version History
D. Invariance
D.1. Repeatability
D.2. Multi-pass Algorithms
D.3. Invariance Rules
D.4. Tessellation Invariance
E. Window System Integration (WSI) Extensions
E.1. Editors
E.2. VK_KHR_surface
E.2.1. New Object Types
E.2.2. New Enum Constants
E.2.3. New Enums
E.2.4. New Structures
E.2.5. New Functions
E.2.6. Examples
E.2.7. Issues
E.2.8. Version History
E.3. VK_KHR_swapchain
E.3.1. New Object Types
E.3.2. New Enum Constants
E.3.3. New Enums
E.3.4. New Structures
E.3.5. New Functions
E.3.6. Issues
E.3.7. Examples
E.3.8. Version History
E.4. VK_KHR_display
E.4.1. New Object Types
E.4.2. New Enum Constants
E.4.3. New Enums
E.4.4. New Structures
E.4.5. New Functions
E.4.6. Issues
E.4.7. Examples
E.4.8. Version History
E.5. VK_KHR_display_swapchain
E.5.1. New Object Types
E.5.2. New Enum Constants
E.5.3. New Enums
E.5.4. New Structures
E.5.5. New Functions
E.5.6. Issues
E.5.7. Examples
E.5.8. Version History
E.6. VK_KHR_android_surface
E.6.1. New Object Types
E.6.2. New Enum Constants
E.6.3. New Enums
E.6.4. New Structures
E.6.5. New Functions
E.6.6. Issues
E.6.7. Version History
E.7. VK_KHR_mir_surface
E.7.1. New Object Types
E.7.2. New Enum Constants
E.7.3. New Enums
E.7.4. New Structures
E.7.5. New Functions
E.7.6. Issues
E.7.7. Version History
E.8. VK_KHR_wayland_surface
E.8.1. New Object Types
E.8.2. New Enum Constants
E.8.3. New Enums
E.8.4. New Structures
E.8.5. New Functions
E.8.6. Issues
E.8.7. Version History
E.9. VK_KHR_win32_surface
E.9.1. New Object Types
E.9.2. New Enum Constants
E.9.3. New Enums
E.9.4. New Structures
E.9.5. New Functions
E.9.6. Issues
E.9.7. Version History
E.10. VK_KHR_xcb_surface
E.10.1. New Object Types
E.10.2. New Enum Constants
E.10.3. New Enums
E.10.4. New Structures
E.10.5. New Functions
E.10.6. Issues
E.10.7. Version History
E.11. VK_KHR_xlib_surface
E.11.1. New Object Types
E.11.2. New Enum Constants
E.11.3. New Enums
E.11.4. New Structures
E.11.5. New Functions
E.11.6. Issues
E.11.7. Version History
Common Abbreviations
F. Credits

List of Figures

9.1. Block diagram of the Vulkan pipeline
19.1. Triangle strips, fans, and lists
19.2. Lines with adjacency
19.3. Triangles with adjacency
19.4. Triangle strips with adjacency
21.1. Domain parameterization for tessellation primitive modes
21.2. Inner Triangle Tessellation
21.3. Inner Quad Tessellation
24.1. Non strict lines
28.1. Sparse Image
28.2. Sparse Image with Single Mip Tail
28.3. Sparse Image with Aligned Mip Size
28.4. Sparse Image with Aligned Mip Size and Single Mip Tail
28.5. Multiple Aspect Sparse Image

List of Tables

6.1. Supported pipeline stage flags
6.2. Supported access flags
9.1. Layout for pipeline cache header version VK_PIPELINE_CACHE_HEADER_VERSION_ONE
11.1. Image and image view parameter compatibility requirements
11.2. Component Mappings Equivalent To VK_COMPONENT_SWIZZLE_IDENTITY
13.1. Pipeline Layout Resource Limits
14.1. Shader Input and Output Locations
14.2. Shader Resource and Descriptor Type Correspondence
14.3. Shader Resource and Storage Class Correspondence
14.4. Shader Resource Limits
15.1. Border Color $B$
15.2. Border Texel Components After Replacement
15.3. Texel Color After Conversion To RGBA
15.4. Cube map face and coordinate selection
15.5. Cube map derivative selection
19.1. Triangles generated by triangle strips with adjacency.
20.1. Input attribute components accessed by 32-bit input variables
20.2. Input attributes accessed by 32-bit input matrix variables
20.3. Input attribute locations and components accessed by 64-bit input variables
23.1. Provoking vertex selection
24.1. Standard sample locations
26.1. Blend Factors
26.2. Blend Operations
26.3. Logical Operations
28.1. Standard Sparse Image Block Shapes (Single Sample)
28.2. Standard Sparse Image Block Shapes (MSAA)
31.1. Required Limit Types
31.2. Required Limits
31.3. Interpretation of Numeric Format
31.4. Interpretation of Compression Scheme
31.5. Byte mappings for non-packed/compressed color formats
31.6. Bit mappings for packed 8-bit formats
31.7. Bit mappings for packed 16-bit VK_FORMAT_* formats
31.8. Bit mappings for packed 32-bit formats
31.9. Compatible formats
31.10. Key for format feature tables
31.11. Feature bits in optimalTilingFeatures
31.12. Feature bits in bufferFeatures
31.13. Mandatory format support: sub-byte channels
31.14. Mandatory format support: 1-3 byte-sized channels
31.15. Mandatory format support: 4 byte-sized channels
31.16. Mandatory format support: 10-bit channels
31.17. Mandatory format support: 16-bit channels
31.18. Mandatory format support: 32-bit channels
31.19. Mandatory format support: 64-bit/uneven channels and depth/stencil
31.20. Mandatory format support: BC compressed formats with VkImageType VK_IMAGE_TYPE_2D and VK_IMAGE_TYPE_3D
31.21. Mandatory format support: ETC2 and EAC compressed formats with VkImageType VK_IMAGE_TYPE_2D
31.22. Mandatory format support: ASTC LDR compressed formats with VkImageType VK_IMAGE_TYPE_2D
A.1. SPIR-V Capabilities which are not required, and corresponding feature names
A.2. Precision of core SPIR-V Instructions
B.1. Mapping of Vulkan BC formats to descriptions
B.2. Mapping of Vulkan ETC formats to descriptions
B.3. Mapping of Vulkan ASTC formats to descriptions

List of Equations

24.1. line_perspective_interpolation
24.2. line_noperspective_interpolation
24.3. triangle_perspective_interpolation
24.4. triangle_noperspective_interpolation