xrEnumerateSwapchainFormats - Enumerates swapchain formats

Parameter Descriptions

• session is the session that enumerates the supported formats.

• formatCapacityInput is the capacity of the formats, or 0 to retrieve the required capacity.
• formatCountOutput is a pointer to the count of uint64_t formats written, or a pointer to the required capacity in the case that formatCapacityInput is 0.
• formats is a pointer to an array of int64_t format ids, but can be NULL if formatCapacityInput is 0. The format ids are specific to the specified graphics API.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required formats size.

Description

enumerateSwapchainFormats enumerates the texture formats supported by the current session. The type of formats returned are dependent on the graphics API specified in createSession. For example, if a DirectX graphics API was specified, then the enumerated formats correspond to the DXGI formats, such as DXGI_FORMAT_R8G8B8A8_UNORM_SRGB. Texture formats should be in order from highest to lowest runtime preference.

With an OpenGL-based graphics API, the texture formats correspond to OpenGL internal formats.

With a Direct3D-based graphics API, enumerateSwapchainFormats never returns typeless formats (e.g. DXGI_FORMAT_R8G8B8A8_TYPELESS). Only concrete formats are returned, and only concrete formats may be specified by applications for swapchain creation.

Runtimes must always return identical buffer contents from this enumeration for the lifetime of the session.

Valid Usage (Implicit)

• session must be a valid Session handle

• formatCountOutput must be a pointer to a uint32_t value
• If formatCapacityInput is not 0, formats must be a pointer to an array of formatCapacityInput int64_t values

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_SIZE_INSUFFICIENT
• ERROR_VALIDATION_FAILURE

See Also

Session, createSwapchain

xrCreateSwapchain - Creates an XrSwapchain

Parameter Descriptions

Description

Creates an Swapchain handle. The returned swapchain handle may be subsequently used in API calls. Multiple Swapchain handles may exist simultaneously, up to some limit imposed by the runtime. The Swapchain handle must be eventually freed via the destroySwapchain function. The runtime must return ERROR_SWAPCHAIN_FORMAT_UNSUPPORTED if the image format specified in the SwapchainCreateInfo is unsupported. The runtime must return ERROR_FEATURE_UNSUPPORTED if any bit of the create flags specified in the SwapchainCreateInfo is unsupported.

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_LIMIT_REACHED
• ERROR_HANDLE_INVALID
• ERROR_OUT_OF_MEMORY
• ERROR_SWAPCHAIN_FORMAT_UNSUPPORTED
• ERROR_FEATURE_UNSUPPORTED
• ERROR_VALIDATION_FAILURE

See Also

Session, Swapchain, SwapchainCreateInfo, acquireSwapchainImage, destroySwapchain, enumerateSwapchainFormats, enumerateSwapchainImages, releaseSwapchainImage

A convenience wrapper to make a compatible pair of calls to createSwapchain and destroySwapchain

To ensure that destroySwapchain is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

xrDestroySwapchain - Destroys an XrSwapchain

Parameter Descriptions

Description

All submitted graphics API commands that refer to swapchain must have completed execution. Runtimes may continue to utilize swapchain images after destroySwapchain is called.

Valid Usage (Implicit)

• swapchain must be a valid Swapchain handle

Thread Safety

• Access to swapchain, and any child handles, must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID

See Also

Swapchain, createSwapchain

xrEnumerateSwapchainImages - Gets images from an XrSwapchain

Parameter Descriptions

• swapchain is the Swapchain to get images from.

• imageCapacityInput is the capacity of the images array, or 0 to indicate a request to retrieve the required capacity.
• imageCountOutput is a pointer to the count of images written, or a pointer to the required capacity in the case that imageCapacityInput is 0.
• images is a pointer to an array of graphics API-specific XrSwapchainImage structures based off of SwapchainImageBaseHeader. It can be NULL if imageCapacityInput is 0.
• See Buffer Size Parameters chapter for a detailed description of retrieving the required images size.

Description

Fills an array of graphics API-specific XrSwapchainImage structures. The resources must be constant and valid for the lifetime of the Swapchain.

Runtimes must always return identical buffer contents from this enumeration for the lifetime of the swapchain.

Note: images is a pointer to an array of structures of graphics API-specific type, not an array of structure pointers.

Valid Usage (Implicit)

• swapchain must be a valid Swapchain handle

• imageCountOutput must be a pointer to a uint32_t value
• If imageCapacityInput is not 0, images must be a pointer to an array of imageCapacityInput SwapchainImageBaseHeader-based structures. See also: SwapchainImageD3D11KHR, SwapchainImageD3D12KHR, SwapchainImageOpenGLESKHR, SwapchainImageOpenGLKHR, SwapchainImageVulkanKHR

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_SIZE_INSUFFICIENT
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE

See Also

Swapchain, SwapchainImageBaseHeader, createSwapchain

xrAcquireSwapchainImage - Acquire a swapchain image

Parameter Descriptions

Description

Acquires the image corresponding to the index position in the array returned by enumerateSwapchainImages. The runtime must return ERROR_CALL_ORDER_INVALID if index has already been acquired and not yet released with releaseSwapchainImage. If the swapchain was created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in SwapchainCreateInfo::createFlags, this function must not have been previously called for this swapchain. The runtime must return ERROR_CALL_ORDER_INVALID if a swapchain created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in SwapchainCreateInfo::createFlags and this function has been successfully called previously for this swapchain.

Valid Usage (Implicit)

• swapchain must be a valid Swapchain handle

• If acquireInfo is not NULL, acquireInfo must be a pointer to a valid SwapchainImageAcquireInfo structure
• index must be a pointer to a uint32_t value

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_CALL_ORDER_INVALID

See Also

Swapchain, SwapchainImageAcquireInfo, createSwapchain, destroySwapchain, enumerateSwapchainImages, releaseSwapchainImage, waitSwapchainImage

xrWaitSwapchainImage - Wait for a swapchain image to be available

Parameter Descriptions

Description

Before an application can begin writing to a swapchain image, it must first wait on the image to avoid writing to it before the compositor has finished reading from it. waitSwapchainImage will implicitly wait on the oldest acquired swapchain image which has not yet been successfully waited on. Once a swapchain image has been successfully waited on, it must be released before waiting on the next acquired swapchain image.

This function may block for longer than the timeout specified in SwapchainImageWaitInfo due to scheduling or contention.

If the timeout expires without the image becoming available for writing, TIMEOUT_EXPIRED must be returned. If waitSwapchainImage returns TIMEOUT_EXPIRED, the next call to waitSwapchainImage will wait on the same image index again until the function succeeds with SUCCESS. Note that this is not an error code; XR_SUCCEEDED(XR_TIMEOUT_EXPIRED) is true.

The runtime must return ERROR_CALL_ORDER_INVALID if no image has been acquired by calling acquireSwapchainImage.

Return Codes

Success

• SUCCESS
• TIMEOUT_EXPIRED
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_CALL_ORDER_INVALID

See Also

Swapchain, SwapchainImageWaitInfo, acquireSwapchainImage, createSwapchain, destroySwapchain, enumerateSwapchainImages, releaseSwapchainImage

A variant of waitSwapchainImage which makes a *safe* FFI call

xrReleaseSwapchainImage - Release a swapchain image

Parameter Descriptions

Description

If the swapchain was created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in SwapchainCreateInfo::createFlags structure, this function must not have been previously called for this swapchain.

The runtime must return ERROR_CALL_ORDER_INVALID if no image has been waited on by calling waitSwapchainImage.

Valid Usage (Implicit)

• swapchain must be a valid Swapchain handle

• If releaseInfo is not NULL, releaseInfo must be a pointer to a valid SwapchainImageReleaseInfo structure

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_CALL_ORDER_INVALID

See Also

Swapchain, SwapchainImageReleaseInfo, acquireSwapchainImage, createSwapchain, destroySwapchain, enumerateSwapchainImages, waitSwapchainImage

XrSwapchainCreateInfo - Creation info for a swapchain

Valid Usage (Implicit)

See Also

SessionCreateFlags, StructureType, SwapchainCreateFlags, SwapchainUsageFlags, createSession, createSwapchain, createSwapchainAndroidSurfaceKHR, enumerateSwapchainFormats

XrSwapchainImageBaseHeader - Image base header for a swapchain image

Member Descriptions

Description

The SwapchainImageBaseHeader is a base structure that can be overridden by a graphics API-specific XrSwapchainImage* child structure.

Valid Usage (Implicit)

See Also

StructureType, enumerateSwapchainImages

XrSwapchainImageAcquireInfo - Describes a swapchain image acquisition

Member Descriptions

Description

Because this structure only exists to support extension-specific structures, acquireSwapchainImage will accept a NULL argument for acquireInfo for applications that are not using any relevant extensions.

Valid Usage (Implicit)

See Also

StructureType, acquireSwapchainImage

XrSwapchainImageWaitInfo - Describes a swapchain image wait operation

Valid Usage (Implicit)

See Also

https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrDuration, StructureType, waitSwapchainImage

XrSwapchainImageReleaseInfo - Describes a swapchain image release

Member Descriptions

Description

Because this structure only exists to support extension-specific structures, releaseSwapchainImage will accept a NULL argument for releaseInfo for applications that are not using any relevant extensions.

Valid Usage (Implicit)

See Also

StructureType, releaseSwapchainImage