Vulkan-Docs/doc/specs/vulkan/appendices/extensions.txt

// Copyright (c) 2015-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[appendix]
= Layers & Extensions

Extensions to the {apiname} API can: be defined by authors, groups of
authors, and the Khronos {apiname} Working Group. In order not to compromise
the readability of the {apiname} Specification, the core Specification does
not incorporate most extensions. The online registry of extensions is
available at URL

http://www.khronos.org/registry/vulkan/

and allows generating versions of the Specification incorporating different
extensions.

[NOTE]
.Note
====
The mechanism and process of specifying extensions is subject to change, as
we receive feedback from authors and further requirements of documentation
tooling. This appendix will be updated as this evolves.
====


== Introduction

The Khronos extension registries and extension naming conventions serve
several purposes:

  * Avoiding naming collisions between extensions developed by mutually
    unaware parties, both in the extension names themselves, as well as
    their token, command, and type names.
  * Allocating enumerant values for tokens added by extensions
  * Creating a defined order between extensions. Extensions with higher
    numbers may: have dependencies upon extensions with lower numbers, and
    must: define any relevant interactions with lower-numbered extensions.
  * Provides a central repository for documentation and header changes
    associated with extensions

{apiname}'s design and general software development trends introduces two
new paradigms that require rethinking the existing mechanisms:

  * Layers, and with them a focus on a more open ecosystem where non-Khronos
    members are expected to extend a Khronos API using the Layer mechanism.
  * Namespaced constants (enumerations) that don't necessarily draw from a
    single global set of token values.


== General Rules/Guidelines

Some general rules to simplify the specific rules below:

  * Extensions and layers must: each have a globally unique name.
  * All commands and tokens must: have a globally unique name.
  * Extensions can: expose new commands, types, and/or tokens, but layers
    mustnot:.
  ** However, layers can: expose their own extensions, which in turn are
     allowed to expose new commands and tokens.
  * All extensions must: be registered with Khronos.
  * Extensions must: be strictly additive and backwards-compatible. That is,
    extensions mustnot: remove existing functionality, or change existing
    default behaviors. A {apiname} implementation may: support any
    combination of extensions, but applications written using only the core
    API, or a subset of the supported extensions, must: continue to work in
    such an implementation without changes in behavior.

== Extension and Layer Naming Conventions

  * Extensions are named with the syntax: +VK_AUTHOR_<name>+.
  * Layers are named with the syntax: +VK_LAYER_{AUTHOR|FQDN}_<name>+.

Both extensions and layer names include a +VK_+ prefix. In addition, layers
add a +LAYER_+ prefix. Extension and layer names also contain an _author
prefix_ identifying the author of the extension/layer. This prefix is a
short, capitalized, registered string identifying an author, such as a
Khronos member developing {apiname} implementations for their devices, or a
non-Khronos developer creating {apiname} layers.

Some authors have platform communities they wish to distinguish between, and
can: register additional author prefixes for that purpose. For example,
Google has separate Android and Chrome communities.

Details on how to register an author prefix are provided below. Layer
authors not wishing to register an author prefix with Khronos can: instead
use a fully-qualified domain name (FQDN) as the prefix. The FQDN should: be
a domain name owned by the author. FQDNs cannot: be used for extensions,
only for layers.

  * The following are examples of extension and layer names, demonstrating
    the above syntax:
  ** Extension names all use the base prefix +VK_+.
  ** Khronos-ratified extensions add the special author prefix +KHR+, and
     will use the prefix +VK_KHR_+.
  ** The following author prefixes are reserved and mustnot: be used:
  *** +VK+ - To avoid confusion with the top-level +VK_+ prefix.
  *** +VULKAN+ - To avoid confusion with the name of the {apiname} API.
  *** +LAYER+ - To avoid confusion with the higher-level ``LAYER'' prefix.
  *** +KHRONOS+ - To avoid confusion with the Khronos organization.
  ** Multi-author extensions that have not been ratified by Khronos (those
     developed via cooperation between, and intended to be supported by two
     or more registered authors) add the special author prefix +EXT+ to the
     base prefix, and will use the prefix +VK_EXT_+.
  ** Traditional author-specific extensions developed by one author (or one
     author in cooperation with non-authors) add the author prefix to the
     base prefix. For example, NVIDIA will use the prefix +VK_NV_+, and
     Valve will use the prefix +VK_VALVE_+. Some authors can: have
     additional registered author prefixes for special purposes. For
     example, an Android extension developed by Google - but part of an
     Android open-source community project, and so not a proprietary Google
     extension - will use the prefix +VK_ANDROID_+.
  ** Layer names follow the same conventions as extensions, but use the base
     prefix +VK_LAYER_+.
  ** Because layers need not be registered with Khronos, an alternative
     prefix mechanism is needed to allow creating unique layer names without
     registering an author prefix. Layer authors that prefer not to register
     an author prefix can: instead use a fully-qualified domain name (FQDN)
     in reverse-order as an author prefix, using all lower-case characters,
     and replacing +.+ (period) with `_` (underscore) characters. For
     example, a layer written by the owner of www.3dxcl.com would use the
     prefix `VK_LAYER_com_3dxcl_www_`. FQDNs must: be encoded in UTF-8.


== Extension Command, Token, and Type Naming Conventions

Extensions may: add new commands, tokens, and types, or collectively
``objects'' to the {apiname} API. These objects also require globally unique
names. These names shall conform to the following template:

["source","{basebackend@docbook:c++:cpp}",title=""]
------------------------------------------------------------------------------
vk<CommandName><ExtensionAuthorPrefix>
------------------------------------------------------------------------------

Where +ExtensionAuthorPrefix+ is equal to that of the prefixes defined above
for extension names with the exception that a leading `_` (underscore) is
added for non-Khronos extensions. For example, a Khronos-blessed extension
could expose the following command:

["source","{basebackend@docbook:c++:cpp}",title=""]
------------------------------------------------------------------------------
void vkDoSomethingKHR(void);
------------------------------------------------------------------------------

A Google extension could expose the following command:

["source","{basebackend@docbook:c++:cpp}",title=""]
------------------------------------------------------------------------------
void vkDoSomethingGOOGLE(void);
------------------------------------------------------------------------------

A multi-author extension could expose the following type:

["source","{basebackend@docbook:c++:cpp}",title=""]
------------------------------------------------------------------------------
typedef struct VkSomeDataEXT;
------------------------------------------------------------------------------

And a non-Khronos extension could expose this enumerant:

["source","{basebackend@docbook:c++:cpp}",title=""]
------------------------------------------------------------------------------
enum VkSomeValuesGRPHX {
    VK_SOME_VALUE_0_GRPHX = 0,
    VK_SOME_VALUE_1_GRPHX = 1,
    VK_SOME_VALUE_2_GRPHX = 2,
};
------------------------------------------------------------------------------


[[extensions-api-registry]]
== The {apiname} Registry

The canonical definition of the {apiname} APIs is kept in an XML file known
as the *{apiname} registry*. The registry is kept in +src/spec/vk.xml+ in
the branch of the vulkan project containing the most recently released core
API specification. The registry contains reserved author prefixes, core and
extension interface definitions, definitions of individual commands and
structures, and other information which must be agreed on by all
implementations. The registry is used to maintain a single, consistent
global namespace for the registered entities, to generate the
Khronos-supplied +vulkan.h+, and to create a variety of related
documentation used in generating the API specification and reference pages.


[[extensions-author-prefix]]
== Registering an Author Prefix with Khronos

Previous Khronos APIs could only officially be modified by Khronos members.
In an effort to build a more flexible platform, {apiname} allows non-Khronos
developers to extend and modify the API via layers and extensions in the
same manner as Khronos members. However, extensions must: still be
registered with Khronos. A mechanism for non-members to register layers and
extensions is provided.

Extension authors will be able to create an account on the Khronos github
project and, using this account, register an author prefix with
Khronos. This string must: be used as the author prefix in any extensions
the author registers. The same account will be used to request registration
of extensions or layers with Khronos, as described below.

To reserve an author prefix, propose a merge request against
<<extensions-api-registry,+vk.xml+>>. The merge must: add a +<tag>+ XML tag
and fill in the +name+, +author+ and +contact+ attributes with the requested
author prefix, the author's formal name (e.g. company or project name), and
contact email address, respectively. The author prefix will be reserved only
once this merge request is accepted.

Please do not try to reserve author names which clearly belong to another
existing company or software project which may: wish to develop {apiname}
extensions or layers in the future, as a matter of courtesy and respect.
Khronos may: decline to register author names that are not requested in good
faith.


[[extensions-vendor-id]]
== Registering a Vendor ID with Khronos

{apiname} implementers must report a valid vendor ID for their
implementation, as reported by
<<devsandqueues-physical-device-enumeration,physical device queries>>. If
there is no valid PCI vendor ID defined for the physical device,
implementations must: obtain a Khronos vendor ID.

Khronos vendor IDs are reserved in a similar fashion to
<<extensions-author-prefix,author prefixes>>. While vendor IDs are not
directly related to API extensions, the reservation process is very similar
and so is described in this section.

To reserve an Khronos vendor ID, you must first have a Khronos author
prefix. Propose a merge request against
<<extensions-api-registry,+vk.xml+>>. The merge must: add a +<vendorid>+ tag
and fill in the +name+ and +id+ attributes. The +name+ attribute must: be
set to the author prefix. The +id+ attribute must: be the first sequentially
available ID in the list of +<vendorid>+ tags. The vendor ID will be
reserved only once this merge request has been accepted.

Please do not try to reserve vendor IDs unless you are making a good faith
effort to develop a {apiname} implementation and require one for that
purpose.


== Registering Extensions and Layers

Extensions must: be registered with Khronos. Layers may: be registered, and
registration is strongly recommended. Registration means:

  * Receiving an extension number.
  * Adding the extension or layer name to the list in +vk.xml+ and appearing
    on the Khronos registry website, which will link to associated
    documentation hosted on Khronos.
  * For extensions which add to the {apiname} API, including definitions of
    those additions to +vk.xml+.

Registration for Khronos members is handled by filing a merge request in the
internal gitlab repository against the branch containing the core
specification against which the extension or layer will be written. The
merge must: modify +vk.xml+ to define extension names, API interfaces, and
related information. Registration is not complete until the registry
maintainer has validated and accepted the merge.

Since this process could in principle be completely automated, this
suggests a scalable mechanism for accepting registration of non-Khronos
extensions. Non-Khronos members who want to create extensions must: register
with Khronos by creating a github account, and registering their author
prefix and/or FQDNs to that account. They can: then submit new extension
registration requests by proposing merges to +vk.xml+. On acceptance of the
merge, the extension will be registered, though its specification need not
be checked into the Khronos github repository at that point.

The registration process can: be split into several steps to accommodate
extension number assignment prior to extension publication:

  * Acquire an extension number. This is done by proposing a merge request
    against +vk.xml+ similarly to how <<extensions-author-prefix,author
    prefixes are reserved>>. The merge should: add a new +<extension>+ tag
    at the end of the file with attributes specifying the proposed extension
    +name+, the next unused sequential extension +number+, the +author+ and
    +contact+ information (if different than that already specified for the
    author prefix used in the extension name), and finally, specifying
    +supported="disabled"+. The extension number will be reserved only once
    this merge request is accepted into the master branch.
  * Develop and test the extension using the registered extension number.
  * Publish the extension to Khronos using the previously registered
    extension number, by creating a branch of the repository with
    appropriate changes relative to the core {apiname} API branch.
  * Mark the extension as enabled, by proposing a merge to master changing
    the +supported+ attribute value of the +<extension>+ to
    +supported="vulkan"+. This should: be completely automated and under the
    control of the publishers, to allow them to align publication on Khronos
    with product releases. However, complete automation might be difficult,
    since steps such as regenerating and validating +vulkan.h+ are involved.
    Once the merge is accepted and the corresponding updated header with the
    new extension interface is committed to the master branch, publication
    is complete.

The automated process does not exist yet, and would require significant
investment in infrastructure to support the process on the Khronos servers.

ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO: This section is subject to change and not complete yet, but in broad
is how we expect extension registration and specifications to work. The
process will be refined as members and outside authors define further
extensions.
====
endif::editing-notes[]


== Documenting Extensions

Extensions are documented as modifications to the {apiname} specification.
These modifications will be on Git branches that are named with the
following syntax: +<major.minor core spec version>-<extension_name>+

For example, the VK_KHR_surface extension will be documented relative
to version 1.0 of the {apiname} specification. As such, the branch name will
be: +1.0-VK_KHR_surface+

If the extension modifies an existing section of the {apiname}
specification, those modifications are made in-place. Since the changes are
on a branch, the core-only specification can: be easily produced. A
specification with an extension is created by merging in the extension's
branch contents.

Extensions should: be merged according to their registered extension number.
If two extensions both modify the same portion of the specification, the
higher-numbered extension should: take care to deal with any conflicts.

The WSI extensions were used to help pioneer what should: be done for
extensions. This includes the following:

  * All extensions should: add to the appendix of the {apiname}
    specification. This should: be modeled after what was done for the
    +VK_KHR_surface+ extension, which contains some high-level information
    about the extension (as well as code examples, and revision history) in
    the +appendices/vk_khr_surface.txt+ file.
  * Each extension's appendix file is included by adding an +include+
    statement to the +vkspec.txt+ file. Since most extensions will all put
    their +include+ line at the same place in this file, they should: add
    this statement on the master branch, even though the file won't actually
    exist on the master branch. This will avoid merge conflicts when
    multiple extensions' branches are merged in order to create the ``full''
    branch specification.
  * If there are any other places where 2 or more extensions will extend the
    {apiname} specification, it is best to put that content in a file, and
    use an +include+ statement to put that content into the spec. Again,
    this +include+ line should: be put on the master branch in order to
    avoid merge conflicts.
  * If an extension is more of an addition to the {apiname} specification,
    the extension should: add a chapter to the {apiname} specification.


== Assigning Extension Token Values

Extensions can: define their own enumeration types and assign any values to
their enumerants that they like. Each enumeration has a private namespace,
so collisions are not a problem. However, when extending existing
enumeration object with new values, care must: be taken to preserve global
uniqueness of values. Enumerations which define new bitfields are treated
specially as described in <<extensions-reserving-bitfield-values,Reserving
Bitfield Values>> below.

Each extension is assigned a range of values that can: be used to create
globally-unique enum values. Most values will be negative numbers, but
positive numbers are also reserved. The ability to create both positive and
negative extension values is necessary to enable extending enumerations such
as stext:VkResult that assign special meaning to negative and positive
values. Therefore, 1000 positive and 1000 negative values are reserved for
each extension. Extensions must: not define enum values outside their
reserved range without explicit permission from the owner of those values
(e.g. from the author of another extension whose range is infringed on, or
from the Khronos Registrar if the values do not belong to any extension's
range).

[NOTE]
.Note
====
Typically, extensions use a unique offset for each enumeration constant they
add, yielding 1000 distinct token values per extension. Since each
enumeration object has its own namespace, if an extension needs to add many
enumeration constant values, it can: reuse offsets on a per-type basis.
====

The information needed to add new values to the XML are as follows:

  * The **extension name** (e.g. +VK_KHR_swapchain+) that is adding the new
    enumeration constant.
  * The existing enumeration **type** being extended (e.g.
    stext:VkStructureType).
  * The name of the new enumeration **token** being added (e.g.
    etext:VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR).
  * The **offset**, which is an integer between 0 and 999 relative to the
    base being used for the extension.
  * The **direction** may: be specified to indicate a negative value
    (+dir="-"+) when needed for negative stext:VkResult values indicating
    errors, like etext:VK_ERROR_SURFACE_LOST_KHR. The default direction is
    positive, if not specified.

Implicit is the registered number of an extension, which is used to create a
block of unused values offset against a global extension base value.
Individual enumerant values are calculated as offsets in that block. Values
are calculated as follows:

  * base_value = 1000000000
  * block_size = 1000
  * enum_offset(extension_number,offset) = base_value +
    (extension_number - 1) × block_size + offset
  * Positive values: enum_offset(extension_number,offset)
  * Negative values: -enum_offset(extension_number,offset)

The exact syntax for specifying extension enumerant values is defined in the
+readme.pdf+ specifying the format of +vk.xml+, and extension authors can:
also refer to existing extensions for examples.


== Required Extension Tokens

In addition to any tokens specific to the functionality of an extension,
all extensions must: define two additional tokens.

  * VK_EXTNAME_SPEC_VERSION is an integer constant which is the revision of
    the extension named +VK_extname+ (EXTNAME is all upper-case, while
    extname is the capitalization of the actual extension name) in
    +vulkan.h+. This value begins at 1 with the initial version of an
    extension specification, and is incremented when significant changes
    (bugfixes or added functionality) are made. Note that the revision of an
    extension defined in +vulkan.h+ and the revision supported by the
    {apiname} implementation (the pname:specVersion field of the
    slink:VkExtensionProperties structure corresponding to the extension and
    returned by one of the <<debug-extensions,Extension Queries>>) may:
    differ. In such cases, only the functionality and behavior of the
    lowest-numbered revision can: be used.
  * VK_EXTNAME_EXTENSION_NAME is a string constant which is the name of the
    extension.

For example, for the WSI extension +VK_KHR_surface+, at the time of writing
the following definitions were in effect:

[source,c]
---------------------------------------------------
#define VK_KHR_SURFACE_SPEC_VERSION 24
#define VK_KHR_SURFACE_EXTENSION_NAME "VK_KHR_surface"
---------------------------------------------------


== Extension Objects, Enums, and Typedefs

Expanding on previous discussion, extensions can: add values to existing
enums; and can: add their own objects, enums, typedefs, etc. This is done by
adding to <<extensions-api-registry,+vk.xml+>>. All such additions will be
included in the +vulkan.h+ header supplied by Khronos.

[NOTE]
.Note
====
Application developers are encouraged to be careful when using +switch+
statements with {apiname} API enums. This is because extensions can: add new
values to existing enums. The use of a +default:+ statement, within a
+switch+, may: avoid future compilation issues.
====


[[extension-function_prototypes]]
== Extension Function Prototypes

Function pointer declarations and function prototypes for all core {apiname}
API functions are included in the +vulkan.h+ file. These come from the
official XML specification of the {apiname} API hosted by Khronos.

Function pointer declarations are also included in the +vulkan.h+ file for
all extension functions. Function prototypes for extensions may: be included
in +vulkan.h+. Extension functions that are part of the {apiname} ABI must:
be flagged in the XML. Prototypes will be included in +vulkan.h+ for all
extension functions that are part of the {apiname} ABI.

An extension can: be considered platform specific, in which case, its
objects, functions, etc. are protected by #ifdefs. This is orthogonal to
whether a function is considered to be part of the {apiname} ABI.

The initial set of WSI extension functions are considered to be part of the
{apiname} ABI. Prototypes for these WSI functions are included in the
+vulkan.h+ provided by Khronos, though the platform-specific portions of
+vulkan.h+ are protected by #ifdefs.

[NOTE]
.Note
====
Based on feedback from implementers, Khronos expects that the Android,
Linux, and Windows {apiname} SDKs will include our +vulkan.h+ and export
the supported WSI functions for those platforms from their loader
libraries. Other implementations can: make different choices for their
headers and loader libraries, but are encouraged to be consistent with
these implementations.
====


== Accessing Extension Function from Programs

The {apiname} API flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr
functions (i.e. GPA functions) can: be used in order to obtain addresses for
core and extension functions (per the description in
<<initialization-functionpointers,Command Function Pointers>>). Various
{apiname} API loaders can: be created on different platforms, which can:
statically export some or all of the core {apiname} API functions, and which
can: statically export some or all extension functions. If a loader
statically exports a function, an application can: link against that
function without needing to call a GPA function.

[NOTE]
.Note
====
As mentioned above, the {apiname} API loader on Android, Linux, and Windows
will export all core {apiname} API and WSI extension functions. The WSI
functions are considered special, because they are required for many
applications.
====

[[extensions-reserving-bitfield-values]]
=== Reserving Bitfield Values

Enumerants which define bitfield values are a special case, since there are
only a small number of unused bits available for extensions. For core Vulkan
API and KHR extension bitfield types, reservations must: be approved by a
vote of the Vulkan Working Group. For EXT and vendor extension bitfield
types, reservations must: be approved by the listed contact of the
extension. Bits are not reserved, and mustnot: be used in a published
implementation or specification until the reservation is merged into
<<extensions-api-registry,+vk.xml+>> by the registry maintainer.

[NOTE]
.Note
====
In reality the approving authority for EXT and vendor extension bitfield
additions will probably be the owner of the github branch containing the
specification of that extension; however, until the github process is fully
defined and locked down, it's safest to refer to the listed contact.
====


== Extension Interactions

Extensions modifying the behavior of existing commands should: provide
additional parameters by using the param:pNext field of an existing
structure, pointing to a new structure defined by the extension, as
described in the <<fundamentals-validusage,Valid Usage>> section. Extension
structures defined by multiple extensions affecting the same structure can
be chained together in this fashion.

It is in principle possible for extensions to provide additional parameters
through alternate means, such as passing a handle parameter to a structure
with a pname:sType defined by the extension, but this approach is
discouraged and shouldnot: be used.

When chaining multiple extensions to a structure, the implementation will
process the chain starting with the base parameter and proceeding through
each successive chained structure in turn. Extensions should: be defined to
accept any order of chaining, and must: define their interactions with other
extensions such that the results are deterministic. If an extension needs a
specific ordering of its extension structure with respect to other
extensions in a chain to provide deterministic results, it must: define the
required ordering and expected behavior as part of its specification.