xrCreateSwapchainAndroidSurfaceKHR - Creates a swapchain and an Android Surface

Parameter Descriptions

Description

createSwapchainAndroidSurfaceKHR creates an Swapchain object returned in swapchain and an Android Surface jobject returned in surface. The jobject must be valid to be passed back to Java code using JNI and must be valid to be used with ordinary Android APIs for submitting images to Surfaces. The returned Swapchain must be valid to be referenced in SwapchainSubImage structures to show content on the screen. The width and height passed in SwapchainCreateInfo may not be persistent throughout the life cycle of the created swapchain, since on Android, the size of the images is controlled by the producer and possibly changes at any time.

The only function that is allowed to be called on the Swapchain returned from this function is destroySwapchain. For example, calling any of the functions enumerateSwapchainImages, acquireSwapchainImage, waitSwapchainImage or releaseSwapchainImage is invalid.

When the application receives the EventDataSessionStateChanged event with the SESSION_STATE_STOPPING state, it must ensure that no threads are writing to any of the Android surfaces created with this extension before calling endSession. The effect of writing frames to the Surface when the session is in states other than SESSION_STATE_VISIBLE or SESSION_STATE_FOCUSED is undefined.

createSwapchainAndroidSurfaceKHR must return the same set of error codes as createSwapchain under the same circumstances, plus ERROR_FUNCTION_UNSUPPORTED in case the function is not supported.

Valid Usage of SwapchainCreateInfo members

• The SwapchainCreateInfo::format, SwapchainCreateInfo::sampleCount, SwapchainCreateInfo::faceCount, SwapchainCreateInfo::arraySize and SwapchainCreateInfo::mipCount members of the structure passed as the info parameter must be zero.

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling createSwapchainAndroidSurfaceKHR

• session must be a valid Session handle
• info must be a pointer to a valid SwapchainCreateInfo structure
• swapchain must be a pointer to an Swapchain handle
• surface must be a pointer to a jobject value

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_LIMIT_REACHED
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_FUNCTION_UNSUPPORTED

See Also

Session, Swapchain, SwapchainCreateInfo, destroySwapchain

A convenience wrapper to make a compatible pair of calls to createSwapchainAndroidSurfaceKHR 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.