// Copyright (c) 2015-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[naming]]
= API Naming Conventions

Identifiers in the OpenXR API (e.g. types, parameters, constants, etc.) all
follow a set of naming rules, providing a consistent scheme for developers.

The OpenXR C API uses prefixes as an implicit namespace control mechanism.
Bindings to other languages can choose not to use these prefixes if the
language provides an explicit namespace mechanism.


== General Naming Rules

Names of identifiers should generally be written with full words, avoiding
abbreviations, as a concise description of what that identifier is.
For example, the type of a structure containing information about how to
create an instance is stext:XrInstanceCreateInfo.

Abbreviations and prefixes are sometimes used in the API when they are in
common use.

All abbreviations and prefixes used in the API must be approved by the
OpenXR working group, and be added to the <<naming-abbreviations,Common
Abbreviations>> and <<naming-prefixes,Standard Prefixes>> sections,
respectively.

Whenever an abbreviation exists for a particular word, it should be used in
place of the full word unless there is good reason not to.

[[naming-preprocessor]]
== Preprocessor Defines

Preprocessor definitions include an underscore `_` as a delimiter between
words, with every character in upper case.

Each definition is prefixed with `XR_`, followed by the name.

This rule applies to most declarations with the C Preprocessor's `#define`
token, including macros and constants.
There are however a few exceptions:

* The header guard for each header includes an additional underscore `_` at
  the end of the identifier.
** Example: `OPENXR_H_`
* Definitions that denote the presence of an extension follow the
  <<extensions-naming-conventions-name-strings,extension name string
  convention>>.
** Example: `XR_KHR_opengl_enable`
* Three `XRAPI_*` definitions are defined by the platform header to alias
  certain platform-specific identifiers related to calling conventions.
** Examples: `XRAPI_ATTR`, `XRAPI_CALL` and `XRAPI_PTR`
* The C preprocessor may be used to create aliases between other OpenXR
  identifiers, which could happen if a determination is made that something
  has been misnamed.
  In these cases, the fixed name is added to the API, and the old name is
  made into an alias of that.
  In these cases, the name will be whatever the original misnamed identifier
  was.

.Example: Macro
include::{generated}/api/defines/XR_VERSION_MAJOR.no-xref.adoc[]

.Example: Value
include::{generated}/api/defines/XR_CURRENT_API_VERSION.no-xref.adoc[]


== Type Names

Type names are declared with no separator between words.
Each word starts with a capital letter, and other characters in each word
are lower case.


Each type name is prefixed with `Xr`.

This rule applies to all type definitions except <<naming-funcpointers,
function pointer types>>, including struct and union types, handles, base
typedefs, and enumerant types.

.Example: Handle
include::{generated}/api/handles/XrInstance.no-xref.adoc[]

.Example: Base Type
include::{generated}/api/basetypes/XrFlags64.no-xref.adoc[]

// Note: This is manually inserted to be able to omit all enumerants.
[source, c]
.Example: Enumerator Type
----
typedef enum XrStructureType {
    ...
} XrStructureType;
----

.Example: Structure
include::{generated}/api/structs/XrInstanceCreateInfo.no-xref.adoc[]

[[naming-extension-structures]]
=== Extension Structure Names

Structures which extend other structures through the pname:next chain should
reflect the name of the base structure they extend, or the role that they
play.
Examples of the "role" guideline include:

* `GraphicsBinding` structures in the `XrSessionCreateInfo` pname:next chain
* `XrSpaceVelocity` in the `XrSpaceLocation` pname:next chain

New non-`KHR` structures which add extended object creation parameters to a
base structure should use this naming scheme:

.Extended Object Information Structures
[width="60%",options="header"]
|====
| Base Structure Name | Extension Structure Name
| `Xr__Object__CreateInfo`
    | `Xr__ObjectName__CreateInfo__Author__`
|====

`_Object_` is the name of the object being created.
`_Name_` is a short name for the extension or the new information added by
that extension.
`_Author_` is the author ID of the extension.

== Enumerant Names

Enumerants include an underscore `_` as a delimiter between words, with
every character in upper case.

Each enumerant name is prefixed with `XR_`.

Enumerants are prefixed with the exact name of the type it belongs to,
converted to the correct case (e.g. `XrEyeVisibility` ->
`XR_EYE_VISIBILITY_LEFT`), and with the extension author indication moved to
the end.

This rule applies to all enumerants, with some exceptions.

* The `XrStructureType` enumerants begin with `XR_TYPE` instead of
  `XR_STRUCTURE_TYPE`.
* Flag types do not use `FLAGS` in the name (e.g. `XrSpaceLocationFlags`
  uses `XR_SPACE_LOCATION_POSITION_VALID_BIT` instead of
  `XR_SPACE_LOCATION_FLAGS_POSITION_VALID_BIT`).
* The `XrResult` enumerants are split into two sub types: error and success
  codes.
** Success codes are prefixed with `XR_`.
** Error codes are prefixed with `XR_ERROR_`.
* Some graphics API names are exceptions to this rule, see
  <<naming-exceptions, Naming Exceptions>>

// Note: This is manually inserted to be able to limit it and not include all enumerants.
[source, c]
.Example: XrStructureType Enumerants (rule exception)
----
typedef enum XrStructureType {
    XR_TYPE_API_LAYER_PROPERTIES = 0,
    XR_TYPE_EXTENSION_PROPERTIES = 1,
    ...
} XrStructureType;
----

.Example: Flag Types and Bit Values (rule exception)
include::{generated}/api/flags/XrSwapchainCreateFlags.no-xref.adoc[]
include::{generated}/api/enums/XrSwapchainCreateFlagBits.no-xref.adoc[]

// Note: This is manually inserted to be able to limit it and not include all enumerants.
[source, c]
.Example: XrResult Enumerants (rule exception)
----
typedef enum XrResult {
    XR_SUCCESS = 0,
    ...
    XR_ERROR_SESSION_RUNNING = -3,
    ...
} XrResult;
----

ifdef::XR_KHR_android_thread_settings[]
// In an ifdef to avoid breaking style guide if we didn't generate the extension includes.
.Example: Enumeration and Enumerant in an Extension
include::{generated}/api/enums/XrAndroidThreadTypeKHR.no-xref.adoc[]
endif::XR_KHR_android_thread_settings[]

== Function Names

Function names are declared with no separator between words.
Each word starts with a capital letter, and every other character in each
word is lower case.

Function names are prefixed with `xr`.
This rule applies to all function declarations.

// Note: This is manually inserted to be able to omit parameters.
[source, c]
.Example: Function Calls
----
XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance( ... );
XRAPI_ATTR XrResult XRAPI_CALL xrGetSystem( ... );
----


[[naming-funcpointers]]
=== Function Pointer Type Names

Function pointer names are declared exactly as the equivalent statically
declared function would be declared, but prefixed with `PFN_`, standing for
"Pointer to FunctioN".

// Note: This is manually inserted because no API includes are generated for this type.
[source, c]
.Example: Function Pointer Type
----
typedef XrResult (XRAPI_PTR *PFN_xrCreateInstance)( ... );
----


== Function Parameter and Struct/Union Member Names

Function parameter names are declared with no separator between words.
Each new word, *except* for the first, starts with a capital letter.
All other characters in the parameter name are in lower case.

Members/parameters of a type that is not a base type should generally be
named in a similar way to the type itself, with additional context added for
clarity when necessary.

Any member that describes the size of a memory allocation should be suffixed
with `Size`, or `CapacityInput` in the case of the input parameter to the
two-call idiom.

Any member that describes the number of something, such as an array length
or number of internal allocations, should be suffixed with `Count`, or
`CountOutput` in the case of the count output parameter to the two-call
idiom.
The `size` rule overrides this rule, though it is possible to have multiple
sizes (e.g. `sizeCount`).
If the member is an array length, then the name of length should correspond
to the name of the array member, usually `xyzCount` for an array named
`xyzs`.
If a member of a chained extension structure is an array whose length must
match the length of an array of the base structure, then the chained
extension structure should include an array length member with the same name
as the length in the base structure.

[[naming-two-call-idiom]]
=== Two-call Idiom Parameter Names

The two-call idiom for buffer size parameters uses names as follows.

* For arrays of typed structures that are not strings or byte buffers,
  naming is based on a noun describing a single item.
  In this example, we will use `item` as that noun.
** The first parameter should be the singular noun followed by
   `CapacityInput`.
   e.g. `itemCapacityInput`
** The second parameter should be the singular noun followed by
   `CountOutput`.
   e.g. `itemCountOutput`
** The third parameter (the array output) should be the item noun
   pluralized.
   e.g. `items`.
* For byte buffers or strings (`char` arrays), the following parameter names
  are used:
** `bufferCapacityInput`
** `bufferCountOutput`
** `buffer`

This naming is enforced by the `xml_consistency` script.
If your item name is unusual to pluralize (e.g. "index" -> "indices") the
script may need modification.

.Example: Function Parameters (including a single indirected pointer)
include::{generated}/api/protos/xrGetInputSourceLocalizedName.no-xref.adoc[]

.Example: Structure Members (including the type exception and a double indirected pointer)
include::{generated}/api/structs/XrFrameEndInfo.no-xref.adoc[]

ifdef::XR_EXT_debug_utils[]
.Example: Function Pointer Members
include::{generated}/api/structs/XrDebugUtilsMessengerCreateInfoEXT.no-xref.adoc[]
endif::XR_EXT_debug_utils[]

.Example: Size Parameter
include::{generated}/api/protos/xrPollEvent.no-xref.adoc[]

.Example: Two-Call Idiom with `CapacityInput` and `CountOutput`
include::{generated}/api/protos/xrEnumerateApiLayerProperties.no-xref.adoc[]

.Example: Count Members
include::{generated}/api/structs/XrCompositionLayerProjection.no-xref.adoc[]

[[naming-exceptions]]
=== Naming exceptions

There are a few graphics API-related names that have specific capitalization
that are an exception to these rules:

* Direct3D, usually shortened to D3D, followed by a version number with no
  delimiter.
  Left as-is in all names, e.g. `D3D11`
* OpenGL
* OpenGL ES - `OpenGLES` in function and type names, and `OPENGL_ES` in
  enumerants.

[[naming-extension-identifiers]]
== Extension Identifier Naming Conventions

Identifiers defined by an extension are modified by appending the
extension's author ID to the end of the identifier, as described below.
Author IDs are obtained as described in the
<<extensions-naming-conventions,Extension and Layer Naming Conventions>>
section.

If an extension becomes part of core, a new version of the extension's
identifiers should be created, that do not contain the author ID at the end
of the identifier.
The original identifiers should be kept in order to maintain source-level
compatibility with existing software.

=== Extension Type Names

Types defined by extensions have the author ID appended to the end of the
type name.

ifdef::XR_KHR_vulkan_enable[]
.Example: Structure Name with `KHR` Appended
include::{generated}/api/structs/XrGraphicsBindingVulkanKHR.no-xref.adoc[]
endif::XR_KHR_vulkan_enable[]

=== Extension Enumerant Names

Enumerants defined by extensions will have the author ID appended to the end
of the enumerant name, separated by an underscore.
This includes the begin, end, range and max values added to enumeranted type
definitions by the generator scripts.

ifdef::XR_EXT_debug_utils[]
.Example: Enumerants with `_EXT` Appended
include::{generated}/api/enums/XrDebugUtilsMessageTypeFlagBitsEXT.no-xref.adoc[]
endif::XR_EXT_debug_utils[]


=== Extension Function Names

Function and function pointer type names defined by extensions have the
author ID appended to the end of the name.


ifdef::XR_KHR_vulkan_enable[]
.Example: Function with `KHR` Appended
include::{generated}/api/protos/xrGetVulkanGraphicsRequirementsKHR.no-xref.adoc[]
endif::XR_KHR_vulkan_enable[]

// Note: This is manually inserted because no API includes are generated for this type.
[source, c]
.Example: Corresponding Function Pointer Type with `KHR` Appended
----
typedef XrResult (XRAPI_PTR *PFN_xrGetVulkanGraphicsRequirementsKHR)(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsVulkanKHR*            graphicsRequirements);
----


=== Extension Interaction Profile Names

Interaction Profile names defined by extensions have the author ID appended
to the end of the name.

// Note: This is manually inserted because no API includes are generated for this type
[source, xml]
.Example: Interaction Profile name with _khr appended.
----
    <extensions>
        <extension name="XR_KHR_loader_init" number="89" type="instance" supported="openxr">
            <require>
                <enum value="1" name="XR_KHR_loader_init_SPEC_VERSION"/>
                <enum value="&quot;XR_KHR_loader_init&quot;" name="XR_KHR_LOADER_INIT_EXTENSION_NAME"/>
                <interaction_profile name="/interaction_profiles/khr/flux_compensator_khr"/>
            </require>
        </extension>
    </extensions>
----

[[naming-abbreviations]]
== Common Abbreviations

Abbreviations and acronyms are sometimes used in the
link:{uri-openxr-ratified-spec}[OpenXR API Specification] and the OpenXR API
where they are considered clear and commonplace.
All such abbreviations used in the core API are defined here.
Extensions should also use these abbreviations where appropriate.

Src::
    Source

Dst::
    Destination

Min::
    Minimum

Max::
    Maximum

Rect::
    Rectangle

Info::
    Information

Bool::
    Boolean

[NOTE]
====
Exceptions may be made for historical reasons.
If that decision is made these exceptions may be noted here.
====

Addr::
    Address

ID::
    Identifier

UUID::
    Universally Unique Identifier

Op::
    Operation

R::
    Red color component

G::
    Green color component

B::
    Blue color component

A::
    Alpha color component

D3D::
    Direct3D

D3D10::
    Direct3D 10.x

D3D11::
    Direct3D 11.x

D3D12::
    Direct3D 12

Perf::
    Performance

[[naming-prefixes]]
== Standard Prefixes

Prefixes are used in the API to denote specific semantic meaning of OpenXR
names, or as a label to avoid name clashes, and are explained here:

XR/Xr/xr::
    OpenXR namespace +
    All types, commands, enumerants and C macro definitions in the OpenXR
    specification are prefixed with these two characters, according to the
    rules defined above.

PFN::
    Function Pointer +
    Denotes that a type is a function pointer.
