## C.10. 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 objects with new values, care must be taken to preserve global uniqueness of values. Enumerations which define new bitfields are treated specially as described in 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 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 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. VkStructureType).
• The name of the new enumeration token being added (e.g. 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 VkResult values indicating errors, like 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 range of unused values offset against a global extension base value. Individual enumerant values are calculated as offsets in that range. Values are calculated as follows:

• base_value = 1000000000
• range_size = 1000
• enum_offset(extension_number,offset) = base_value (extension_number - 1) × range_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.