API 样板

此附录定义了 Vulkan API 功能，这些功能是 Vulkan 完整功能描述所需的基础结构，但在逻辑上不属于规范中的其他位置。

Vulkan 头文件

Vulkan 被定义为 C99 语言中的 API。Khronos 为使用该 API 的应用程序提供了一组相应的头文件，这些头文件可以在 C 或 C++ 代码中使用。规范中的接口描述与这些头文件中定义的接口相同，并且两者都源自 vk.xml XML API 注册表，这是 Vulkan API 的规范机器可读描述。注册表、用于将其处理成各种形式的脚本以及注册表模式的文档可按 https://registry.khronos.org/vulkan/#apiregistry 中所述的方式获得。

可以使用规范和注册表中的信息定义其他语言的语言绑定。Khronos 不提供任何此类绑定，但第三方开发人员创建了一些其他绑定。

Vulkan 组合 API 头文件 `vulkan.h` (信息性)

应用程序通常会包含头文件 vulkan.h。反过来，vulkan.h 始终包含以下头文件

vk_platform.h，定义特定于平台的宏和头文件。
vulkan_core.h，定义 Vulkan 核心和所有已注册扩展的 API，除了特定于窗口系统的和临时的扩展，这些扩展包含在单独的头文件中。

此外，在包含 vulkan.h 时定义的特定预处理器宏会导致包含相应的特定于窗口系统和临时接口的头文件，如下所述。

Vulkan 特定于平台的头文件 `vk_platform.h` (信息性)

特定于平台的宏和接口在 vk_platform.h 中定义。这些宏用于控制依赖于平台的行为，它们的精确定义受特定平台和 Vulkan 实现的控制。

特定于平台的调用约定

在许多平台上，以下宏是空字符串，导致使用特定于平台和编译器的默认调用约定。

VKAPI_ATTR 是一个宏，放置在 Vulkan API 函数声明中的返回类型之前。此宏控制 C++11 和 GCC/Clang 样式编译器的调用约定。

VKAPI_CALL 是一个宏，放置在 Vulkan API 函数声明中的返回类型之后。此宏控制 MSVC 样式编译器的调用约定。

VKAPI_PTR 是一个宏，放置在 Vulkan API 函数指针声明中的 '(' 和 '*' 之间。此宏还控制调用约定，并且通常具有与 VKAPI_ATTR 或 VKAPI_CALL 相同的定义，具体取决于编译器。

使用这些宏，Vulkan 函数声明采用以下形式

VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);

此外，Vulkan 函数指针类型声明采用以下形式

typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);

特定于平台的头文件控制

如果应用程序在编译时定义了 VK_NO_STDINT_H 宏，则 Vulkan API 使用的扩展整数类型（例如 uint8_t）必须也由应用程序定义。否则，Vulkan 头文件将无法编译。如果未定义 VK_NO_STDINT_H，则使用系统 <stdint.h> 来定义这些类型。当在编译时检测到 Microsoft Visual Studio 2008 及更早版本时，存在回退路径。

如果应用程序在编译时定义了 VK_NO_STDDEF_H 宏，则 size_t 必须也由应用程序定义。否则，Vulkan 头文件将无法编译。如果未定义 VK_NO_STDDEF_H，则使用系统 <stddef.h> 来定义此类型。

Vulkan 核心 API 头文件 `vulkan_core.h`

不使用特定于窗口系统的扩展的应用程序可以直接包含 vulkan_core.h 而不是 vulkan.h，尽管通常没有理由这样做。除了 Vulkan API，vulkan_core.h 还定义了一些 C 预处理器宏，如下所述。

Vulkan 头文件版本号

VK_HEADER_VERSION 是 vulkan_core.h 头文件的版本号。该值与发布的规范的补丁版本保持同步。

// Provided by VK_VERSION_1_0
// Version of this file
#define VK_HEADER_VERSION 305

VK_HEADER_VERSION_COMPLETE 是 vulkan_core.h 头文件的完整版本号，包括主版本号、次版本号和补丁版本号。主版本号/次版本号与发布的规范的完整版本保持同步。该值旨在供自动化工具使用，以准确识别在其生成过程中使用的头文件的版本。

应用程序不应将此值用作它们的 VkApplicationInfo::apiVersion。相反，应用程序应显式选择特定的固定主版本号/次版本号 API，例如使用 VK_API_VERSION_*_* 值之一。

// Provided by VK_VERSION_1_0
// Complete version of this file
#define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 4, VK_HEADER_VERSION)

VK_API_VERSION 现在已在 vulkan_core.h 中注释掉，并且不能使用。

// Provided by VK_VERSION_1_0
// DEPRECATED: This define has been removed. Specific version defines (e.g. VK_API_VERSION_1_0), or the VK_MAKE_VERSION macro, should be used instead.
//#define VK_API_VERSION VK_MAKE_API_VERSION(0, 1, 0, 0) // Patch version should always be set to 0

Vulkan 句柄宏

VK_DEFINE_HANDLE 定义一个可分发句柄类型。

// Provided by VK_VERSION_1_0

#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;

object 是生成的 C 类型的名称。

唯一的可分发句柄类型是与设备和实例管理相关的类型，例如 VkDevice。

VK_DEFINE_NON_DISPATCHABLE_HANDLE 定义一个不可分发句柄类型。

// Provided by VK_VERSION_1_0

#ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE
    #if (VK_USE_64_BIT_PTR_DEFINES==1)
        #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
    #else
        #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
    #endif
#endif

object 是生成的 C 类型的名称。

大多数 Vulkan 句柄类型，例如 VkBuffer，都是不可分发的。

vulkan_core.h 头文件允许应用程序重写 VK_DEFINE_NON_DISPATCHABLE_HANDLE 和 VK_NULL_HANDLE 的定义。如果在编译 vulkan_core.h 时已经定义了 VK_DEFINE_NON_DISPATCHABLE_HANDLE，则会跳过 VK_DEFINE_NON_DISPATCHABLE_HANDLE 和 VK_NULL_HANDLE 的默认定义。这允许应用程序定义一个二进制兼容的自定义句柄，该句柄可能提供更高的类型安全性或应用程序所需的其他功能。应用程序必须不要以不二进制兼容的方式定义句柄 - 其中二进制兼容性取决于平台。

VK_NULL_HANDLE 是一个保留值，表示一个无效的对象句柄。只有在明确允许的情况下，它才能传递给 Vulkan 命令并从其中返回。

// Provided by VK_VERSION_1_0

#ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE
    #if (VK_USE_64_BIT_PTR_DEFINES==1)
        #if (defined(__cplusplus) && (__cplusplus >= 201103L)) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L))
            #define VK_NULL_HANDLE nullptr
        #else
            #define VK_NULL_HANDLE ((void*)0)
        #endif
    #else
        #define VK_NULL_HANDLE 0ULL
    #endif
#endif
#ifndef VK_NULL_HANDLE
    #define VK_NULL_HANDLE 0
#endif

VK_USE_64_BIT_PTR_DEFINES 定义是否使用 64 位指针类型或 64 位无符号整数类型声明默认的不可分发句柄。

将 VK_USE_64_BIT_PTR_DEFINES 设置为 '1' 以使用 64 位指针类型，或者将其他任何值设置为使用 64 位无符号整数类型。

// Provided by VK_VERSION_1_0

#ifndef VK_USE_64_BIT_PTR_DEFINES
    #if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) || (defined(__riscv) && __riscv_xlen == 64)
        #define VK_USE_64_BIT_PTR_DEFINES 1
    #else
        #define VK_USE_64_BIT_PTR_DEFINES 0
    #endif
#endif

vulkan_core.h 头文件允许应用程序重写 VK_USE_64_BIT_PTR_DEFINES 的定义。这允许应用程序在预定义的预处理器检查未识别所需配置的情况下，为不可分发句柄选择 64 位指针类型或 64 位无符号整数类型。

此宏是从 Vulkan 1.2.174 头文件开始引入的，并且可以通过要求 VK_HEADER_VERSION >= 174 在编译时检查其可用性。

如果您使用的是较旧的头文件（例如，可能随较旧的 Vulkan SDK 一起发布的头文件），则此宏不可用。在这种情况下，需要此功能的开发人员可能希望在他们的项目中包含当前 Vulkan 头文件的副本。

窗口系统特定头文件控制（信息性）

要使用支持特定于平台的窗口系统的 Vulkan 扩展，必须在编译时包含该窗口系统的头文件，或者必须前向声明特定于平台的类型。Vulkan 头文件无法确定编译时是否存在外部头文件，因此特定于平台的扩展与核心 API 和独立于平台的扩展在单独的头文件中提供，从而允许应用程序决定它们需要定义哪些扩展以及如何包含外部头文件。

依赖于特定平台头文件集或前向声明特定于平台类型的扩展在以该平台命名的头文件中声明。在包含这些特定于平台的 Vulkan 头文件之前，应用程序必须同时包含 vulkan_core.h 和平台扩展所依赖的任何外部原生头文件。

为了方便不需要单独的特定于平台的 Vulkan 头文件的灵活性的应用程序，vulkan.h 包括 vulkan_core.h，然后有条件地包括特定于平台的 Vulkan 头文件以及它们所依赖的外部头文件。应用程序通过在包含 vulkan.h 之前 #define 宏来控制包含哪些特定于平台的头文件。

特定于平台的扩展、它们所需的外部头文件、声明它们的特定于平台的头文件以及允许 vulkan.h 包含它们的预处理器宏之间的对应关系在下表中显示。

表 1. 窗口系统扩展和头文件
扩展名称	窗口系统名称	特定于平台的头文件	所需的外部头文件	控制 `vulkan.h` 的宏
`VK_KHR_android_surface`	Android	`vulkan_android.h`	无	`VK_USE_PLATFORM_ANDROID_KHR`
`VK_KHR_wayland_surface`	Wayland	`vulkan_wayland.h`	`<wayland-client.h>`	`VK_USE_PLATFORM_WAYLAND_KHR`
`VK_KHR_win32_surface`, `VK_KHR_external_memory_win32`, `VK_KHR_win32_keyed_mutex`, `VK_KHR_external_semaphore_win32`, `VK_KHR_external_fence_win32`, `VK_NV_external_memory_win32`, `VK_NV_win32_keyed_mutex`	Microsoft Windows	`vulkan_win32.h`	`<windows.h>`	`VK_USE_PLATFORM_WIN32_KHR`
`VK_KHR_xcb_surface`	X11 Xcb	`vulkan_xcb.h`	`<xcb/xcb.h>`	`VK_USE_PLATFORM_XCB_KHR`
`VK_KHR_xlib_surface`	X11 Xlib	`vulkan_xlib.h`	`<X11/Xlib.h>`	`VK_USE_PLATFORM_XLIB_KHR`
`VK_EXT_directfb_surface`	DirectFB	`vulkan_directfb.h`	`<directfb/directfb.h>`	`VK_USE_PLATFORM_DIRECTFB_EXT`
`VK_EXT_acquire_xlib_display`	X11 XRAndR	`vulkan_xlib_xrandr.h`	`<X11/Xlib.h>`, `<X11/extensions/Xrandr.h>`	`VK_USE_PLATFORM_XLIB_XRANDR_EXT`
`VK_GGP_stream_descriptor_surface`, `VK_GGP_frame_token`	Google Games Platform	`vulkan_ggp.h`	<ggp_c/vulkan_types.h>	`VK_USE_PLATFORM_GGP`
`VK_MVK_ios_surface`	iOS	`vulkan_ios.h`	无	`VK_USE_PLATFORM_IOS_MVK`
`VK_MVK_macos_surface`	macOS	`vulkan_macos.h`	无	`VK_USE_PLATFORM_MACOS_MVK`
`VK_NN_vi_surface`	VI	`vulkan_vi.h`	无	`VK_USE_PLATFORM_VI_NN`
`VK_FUCHSIA_imagepipe_surface`	Fuchsia	`vulkan_fuchsia.h`	`<zircon/types.h>`	`VK_USE_PLATFORM_FUCHSIA`
`VK_EXT_metal_surface`	CoreAnimation 上的 Metal	`vulkan_metal.h`	无	`VK_USE_PLATFORM_METAL_EXT`
`VK_QNX_screen_surface`	QNX Screen	`vulkan_screen.h`	`<screen/screen.h>`	`VK_USE_PLATFORM_SCREEN_QNX`

本节描述头文件的用途，独立于窗口系统扩展本身的特定底层功能。只有在查看包含该扩展的规范时，每个扩展名称才会链接到该扩展的描述。

临时扩展头文件控制（信息性）

临时扩展不应该在生产应用程序中使用。此类扩展定义的功能可能会发生变化，从而在修订版本之间以及在最终发布该扩展的非临时版本之前破坏向后兼容性。

临时扩展在单独的临时头文件vulkan_beta.h 中定义，允许应用程序决定是否包含它们。该机制类似于窗口系统特定的头文件：在包含 vulkan_beta.h 之前，应用程序必须包含 vulkan_core.h。

有时，临时扩展会在 vulkan_core.h 中包含其接口的子集。如果临时扩展是从现有的供应商或 EXT 扩展升级的，并且一些现有接口被定义为临时扩展接口的别名，则可能会发生这种情况。该临时扩展的所有其他未被别名的接口都将包含在 vulkan_beta.h 中。

为了方便应用程序，vulkan.h 会有条件地包含 vulkan_beta.h。应用程序可以通过在包含 vulkan.h 之前 #define 宏 VK_ENABLE_BETA_EXTENSIONS 来控制 vulkan_beta.h 的包含。

从规范的 1.2.171 版本开始，所有临时枚举都受宏 VK_ENABLE_BETA_EXTENSIONS 的保护。需要使用临时扩展的应用程序必须始终定义此宏，即使它们显式包含 vulkan_beta.h。这是行为上的一个小变化，仅影响临时扩展。

本节描述临时头文件的用途，独立于该头文件在任何给定时间包含的特定临时扩展。临时扩展的扩展附录会注明其临时状态，并链接回本节以获取更多信息。临时扩展旨在为前沿开发人员提供早期访问权限，但需要理解扩展接口可能会根据开发人员的反馈进行更改。临时扩展很可能最终会被更新并作为非临时扩展发布，但不能保证这种情况会发生，或者如果发生，需要多长时间。

视频标准头文件

执行视频编码操作通常涉及应用程序必须提供特定于所使用的特定视频压缩标准的各种参数、数据结构或其他语法元素，并且相关的语义由这些标准的规范覆盖。

这些接口描述可在从 video.xml XML 文件派生的头文件中找到，该文件是对与外部提供的视频压缩标准相关的数据结构和枚举的规范机器可读描述。

表 2. 视频标准头文件
视频标准头文件名称	描述	头文件	相关扩展
`vulkan_video_codecs_common`	编解码器无关的公共定义	`<vk_video/vulkan_video_codecs_common.h>`	-
`vulkan_video_codec_h264std`	ITU-T H.264 公共定义	`<vk_video/vulkan_video_codec_h264std.h>`	VK_KHR_video_decode_h264, VK_KHR_video_encode_h264
`vulkan_video_codec_h264std_decode`	ITU-T H.264 解码特定定义	`<vk_video/vulkan_video_codec_h264std_decode.h>`	VK_KHR_video_decode_h264
`vulkan_video_codec_h264std_encode`	ITU-T H.264 编码特定定义	`<vk_video/vulkan_video_codec_h264std_encode.h>`	VK_KHR_video_encode_h264
`vulkan_video_codec_h265std`	ITU-T H.265 公共定义	`<vk_video/vulkan_video_codec_h265std.h>`	VK_KHR_video_decode_h265, VK_KHR_video_encode_h265
`vulkan_video_codec_h265std_decode`	ITU-T H.265 解码特定定义	`<vk_video/vulkan_video_codec_h265std_decode.h>`	VK_KHR_video_decode_h265
`vulkan_video_codec_h265std_encode`	ITU-T H.265 编码特定定义	`<vk_video/vulkan_video_codec_h265std_encode.h>`	VK_KHR_video_encode_h265
`vulkan_video_codec_av1std`	AV1 公共定义	`<vk_video/vulkan_video_codec_av1std.h>`	VK_KHR_video_decode_av1
`vulkan_video_codec_av1std_decode`	AV1 解码特定定义	`<vk_video/vulkan_video_codec_av1std_decode.h>`	VK_KHR_video_decode_av1
`vulkan_video_codec_av1std_encode`	AV1 编码特定定义	`<vk_video/vulkan_video_codec_av1std_encode.h>`	VK_KHR_video_encode_av1