Package org.lwjgl.openxr

Class EXTFuture

java.lang.Object

org.lwjgl.openxr.EXTFuture

public class EXTFuture
extends Object

The XR_EXT_future extension.

In XR systems there are certain operations that are long running and do not reasonably complete within a normal frame loop. This extension introduces the concept of a future which supports creation of asynchronous (async) functions for such long running operations. This extension does not include any asynchronous operations: it is expected that other extensions will use these futures and their associated conventions in this extension to define their asynchronous operations.

An XrFutureEXT represents the future result of an asynchronous operation, comprising an XrResult and possibly additional outputs. Long running operations immediately return an XrFutureEXT when started, letting the application poll the state of the future, and get the result once ready by calling a "complete"-function.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	XR_ERROR_FUTURE_INVALID_EXT	Extends XrResult.
static final int	XR_ERROR_FUTURE_PENDING_EXT	Extends XrResult.
static final String	XR_EXT_FUTURE_EXTENSION_NAME	The extension name.
static final int	XR_EXT_future_SPEC_VERSION	The extension specification version.
static final int	XR_FUTURE_STATE_PENDING_EXT	XrFutureStateEXT - Information on future to cancel
static final int	XR_FUTURE_STATE_READY_EXT	XrFutureStateEXT - Information on future to cancel
static final int	XR_NULL_FUTURE_EXT	XR_NULL_FUTURE_EXT
static final int	XR_TYPE_FUTURE_CANCEL_INFO_EXT	Extends XrStructureType.
static final int	XR_TYPE_FUTURE_COMPLETION_EXT	Extends XrStructureType.
static final int	XR_TYPE_FUTURE_POLL_INFO_EXT	Extends XrStructureType.
static final int	XR_TYPE_FUTURE_POLL_RESULT_EXT	Extends XrStructureType.

Method Summary

Modifier and Type	Method	Description
static int	nxrCancelFutureEXT(org.lwjgl.openxr.XrInstance instance, long cancelInfo)	Unsafe version of: CancelFutureEXT
static int	nxrPollFutureEXT(org.lwjgl.openxr.XrInstance instance, long pollInfo, long pollResult)	Unsafe version of: PollFutureEXT
static int	xrCancelFutureEXT(org.lwjgl.openxr.XrInstance instance, XrFutureCancelInfoEXT cancelInfo)	Cancel future.
static int	xrPollFutureEXT(org.lwjgl.openxr.XrInstance instance, XrFuturePollInfoEXT pollInfo, XrFuturePollResultEXT pollResult)	Polls the lifecycle state of an XrFuture.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

XR_EXT_future_SPEC_VERSION

public static final int XR_EXT_future_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

XR_EXT_FUTURE_EXTENSION_NAME

public static final String XR_EXT_FUTURE_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

XR_NULL_FUTURE_EXT

public static final int XR_NULL_FUTURE_EXT

XR_NULL_FUTURE_EXT

See Also:

• Constant Field Values

XR_ERROR_FUTURE_PENDING_EXT

public static final int XR_ERROR_FUTURE_PENDING_EXT

Extends XrResult.

Enum values:

• ERROR_FUTURE_PENDING_EXT
• ERROR_FUTURE_INVALID_EXT

See Also:

• Constant Field Values

XR_ERROR_FUTURE_INVALID_EXT

public static final int XR_ERROR_FUTURE_INVALID_EXT

Extends XrResult.

Enum values:

• ERROR_FUTURE_PENDING_EXT
• ERROR_FUTURE_INVALID_EXT

See Also:

• Constant Field Values

XR_TYPE_FUTURE_CANCEL_INFO_EXT

public static final int XR_TYPE_FUTURE_CANCEL_INFO_EXT

Extends XrStructureType.

Enum values:

• TYPE_FUTURE_CANCEL_INFO_EXT
• TYPE_FUTURE_POLL_INFO_EXT
• TYPE_FUTURE_COMPLETION_EXT
• TYPE_FUTURE_POLL_RESULT_EXT

See Also:

• Constant Field Values

XR_TYPE_FUTURE_POLL_INFO_EXT

public static final int XR_TYPE_FUTURE_POLL_INFO_EXT

Extends XrStructureType.

Enum values:

• TYPE_FUTURE_CANCEL_INFO_EXT
• TYPE_FUTURE_POLL_INFO_EXT
• TYPE_FUTURE_COMPLETION_EXT
• TYPE_FUTURE_POLL_RESULT_EXT

See Also:

• Constant Field Values

XR_TYPE_FUTURE_COMPLETION_EXT

public static final int XR_TYPE_FUTURE_COMPLETION_EXT

Extends XrStructureType.

Enum values:

• TYPE_FUTURE_CANCEL_INFO_EXT
• TYPE_FUTURE_POLL_INFO_EXT
• TYPE_FUTURE_COMPLETION_EXT
• TYPE_FUTURE_POLL_RESULT_EXT

See Also:

• Constant Field Values

XR_TYPE_FUTURE_POLL_RESULT_EXT

public static final int XR_TYPE_FUTURE_POLL_RESULT_EXT

Extends XrStructureType.

Enum values:

• TYPE_FUTURE_CANCEL_INFO_EXT
• TYPE_FUTURE_POLL_INFO_EXT
• TYPE_FUTURE_COMPLETION_EXT
• TYPE_FUTURE_POLL_RESULT_EXT

See Also:

• Constant Field Values

XR_FUTURE_STATE_PENDING_EXT

public static final int XR_FUTURE_STATE_PENDING_EXT

XrFutureStateEXT - Information on future to cancel

Enumerant Descriptions

• FUTURE_STATE_PENDING_EXT. The state of a future that is waiting for the async operation to conclude. This is typically the initial state of a future returned from an async function.
• FUTURE_STATE_READY_EXT. The state of a future when the result of the async operation is ready. The application can retrieve the result by calling the associated completion function.

A future that is not invalidated (or completed) may be in one of two states, Pending and Ready, represented by FUTURE_STATE_PENDING_EXT and FUTURE_STATE_READY_EXT respectively.

• When successfully returned from an async function the future starts out as Pending. In this state the future may be polled, but must not be passed to a completion function. Applications should wait for the future to become ready and keep polling the state of the future. If a pending future is passed to the associated completion function, it must return ERROR_FUTURE_PENDING_EXT.
• Once the asynchronous operation succeeds or fails, the state of the future moves to Ready. In the ready state the future may be "Completed" with the Complete function. See Completing a Future.
• After being successfully completed, the future becomes invalidated if the completion function returns a success code, and in the case of two-call idioms, the array was not NULL.
• After a call to CancelFutureEXT, the future becomes invalidated immediately and any resources associated with it may be freed (including handles)
• When the associated handle is destroyed, the futures become invalidated. See Future Scope.

A future returned from an async function must be in either the state FUTURE_STATE_PENDING_EXT or FUTURE_STATE_READY_EXT. A runtime may skip the Pending state and go directly to Ready if the result is immediately available.

See Also

XrFuturePollResultEXT, CancelFutureEXT

See Also:

• Constant Field Values

XR_FUTURE_STATE_READY_EXT

public static final int XR_FUTURE_STATE_READY_EXT

XrFutureStateEXT - Information on future to cancel

Enumerant Descriptions

• FUTURE_STATE_PENDING_EXT. The state of a future that is waiting for the async operation to conclude. This is typically the initial state of a future returned from an async function.
• FUTURE_STATE_READY_EXT. The state of a future when the result of the async operation is ready. The application can retrieve the result by calling the associated completion function.

A future that is not invalidated (or completed) may be in one of two states, Pending and Ready, represented by FUTURE_STATE_PENDING_EXT and FUTURE_STATE_READY_EXT respectively.

• When successfully returned from an async function the future starts out as Pending. In this state the future may be polled, but must not be passed to a completion function. Applications should wait for the future to become ready and keep polling the state of the future. If a pending future is passed to the associated completion function, it must return ERROR_FUTURE_PENDING_EXT.
• Once the asynchronous operation succeeds or fails, the state of the future moves to Ready. In the ready state the future may be "Completed" with the Complete function. See Completing a Future.
• After being successfully completed, the future becomes invalidated if the completion function returns a success code, and in the case of two-call idioms, the array was not NULL.
• After a call to CancelFutureEXT, the future becomes invalidated immediately and any resources associated with it may be freed (including handles)
• When the associated handle is destroyed, the futures become invalidated. See Future Scope.

A future returned from an async function must be in either the state FUTURE_STATE_PENDING_EXT or FUTURE_STATE_READY_EXT. A runtime may skip the Pending state and go directly to Ready if the result is immediately available.

See Also

XrFuturePollResultEXT, CancelFutureEXT

See Also:

• Constant Field Values

Method Details

nxrPollFutureEXT

public static int nxrPollFutureEXT(org.lwjgl.openxr.XrInstance instance,
 long pollInfo,
 long pollResult)

Unsafe version of: PollFutureEXT

xrPollFutureEXT

public static int xrPollFutureEXT(org.lwjgl.openxr.XrInstance instance,
 XrFuturePollInfoEXT pollInfo,
 XrFuturePollResultEXT pollResult)

Polls the lifecycle state of an XrFuture.

C Specification

The PollFutureEXT function is defined as:

 XrResult xrPollFutureEXT(
     XrInstance                                  instance,
     const XrFuturePollInfoEXT*                  pollInfo,
     XrFuturePollResultEXT*                      pollResult);

Description

Applications can use this function to check the current state of a future, typically while waiting for the async operation to complete and the future to become "ready" to complete.

Note

Each XrFutureEXT value must be externally synchronized by the application when calling completion, polling, and cancellation functions, and when destroying the associated handle.

Valid Usage (Implicit)

• The XR_EXT_future extension must be enabled prior to calling PollFutureEXT
• instance must be a valid XrInstance handle
• pollInfo must be a pointer to a valid XrFuturePollInfoEXT structure
• pollResult must be a pointer to an XrFuturePollResultEXT structure

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_FUTURE_INVALID_EXT

See Also

XrFuturePollInfoEXT, XrFuturePollResultEXT

Parameters:

instance - an XrInstance handle

pollInfo - a pointer to an XrFuturePollInfoEXT structure.

pollResult - a pointer to an XrFuturePollResultEXT structure to be populated on a successful call.

nxrCancelFutureEXT

public static int nxrCancelFutureEXT(org.lwjgl.openxr.XrInstance instance,
 long cancelInfo)

Unsafe version of: CancelFutureEXT

xrCancelFutureEXT

public static int xrCancelFutureEXT(org.lwjgl.openxr.XrInstance instance,
 XrFutureCancelInfoEXT cancelInfo)

Cancel future.

C Specification

The CancelFutureEXT function is defined as:

 XrResult xrCancelFutureEXT(
     XrInstance                                  instance,
     const XrFutureCancelInfoEXT*                cancelInfo);

Description

This function cancels the future and signals that the async operation is not required. After a future has been cancelled any functions using this future must return ERROR_FUTURE_INVALID_EXT.

A runtime may stop the asynchronous operation associated with a future after an app has cancelled it.

Note

Each XrFutureEXT value must be externally synchronized by the application when calling completion, polling, and cancellation functions, or destroying the associated handle.

Valid Usage (Implicit)

• The XR_EXT_future extension must be enabled prior to calling CancelFutureEXT
• instance must be a valid XrInstance handle
• cancelInfo must be a pointer to a valid XrFutureCancelInfoEXT structure

Thread Safety

• Access to the future member of the cancelInfo parameter must be externally synchronized

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_FUTURE_INVALID_EXT

See Also

XrFutureCancelInfoEXT

Parameters:

instance - an XrInstance handle

cancelInfo - a pointer to an XrFutureCancelInfoEXT structure.