Functions related to the management of glasses state and exclusivity. More...

Collaboration diagram for Glasses state management:

Functions
T5_EXPORT T5_Result	t5ReserveGlasses (T5_Glasses glasses, const char *displayName)
	Reserve glasses for exclusive operations by the client. More...

T5_EXPORT T5_Result	t5SetGlassesDisplayName (T5_Glasses glasses, const char *displayName)
	Set the display name for glasses that were previously reserved for exclusive operations. More...

T5_EXPORT T5_Result	t5EnsureGlassesReady (T5_Glasses glasses)
	Ensure that reserved glasses are ready for exclusive operations. More...

T5_EXPORT T5_Result	t5GetGlassesConnectionState (T5_Glasses glasses, T5_ConnectionState *connectionState)
	Get the exclusivity/connection status of the glasses. More...

T5_EXPORT T5_Result	t5GetGlassesIdentifier (T5_Glasses glasses, char buffer, size_t bufferSize)
	Get the device identifier of a glasses. More...

Detailed Description

Functions related to the management of glasses state and exclusivity.

Function Documentation

◆ t5EnsureGlassesReady()

T5_EXPORT T5_Result t5EnsureGlassesReady ( T5_Glasses glasses )

Ensure that reserved glasses are ready for exclusive operations.

Ensure that reserved glasses are ready for exclusive operations, such as the ability to get poses (t5GetGlassesPose()) and send frames (t5SendFrameToGlasses()). To reserve glasses for exclusive use t5ReserveGlasses() . This must be checked for success prior to exclusive operations, otherwise those operations will fail.

In normal operation, this will return either T5_SUCCESS or T5_ERROR_TRY_AGAIN . This should be called until success or an different error is seen.

If glasses are not reserved before calling, this will return an error.

Threading: Exclusivity group 1 - Functions in this group must not be called concurrently from different threads.

Parameters

[in] glasses - T5_Glasses returned by t5CreateGlasses()

Return values

T5_SUCCESS	Glasses ready for exclusive operations.
T5_ERROR_TRY_AGAIN	Glasses not yet ready for exclusive operations.
T5_ERROR_UNAVAILABLE	Glasses already in use by another client.
T5_ERROR_DEVICE_LOST	Glasses have disconnected - destroy glasses with t5DestroyGlasses(), re-obtain with t5CreateGlasses() and try again.
T5_ERROR_INVALID_STATE	Glasses weren't reserved first or client is invalid.
T5_ERROR_INVALID_ARGS	Nullptr or invalid input supplied for `info`.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_INTERNAL	Internal error - not correctable.
T5_ERROR_STRING_OVERFLOW	One or more of the provided strings is too long.

Referenced by tiltfive::Glasses::ensureReady().

◆ t5GetGlassesConnectionState()

T5_EXPORT T5_Result t5GetGlassesConnectionState	(	T5_Glasses	glasses,
		T5_ConnectionState *	connectionState
	)

Get the exclusivity/connection status of the glasses.

Threading: Exclusivity group 1 - Functions in this group must not be called concurrently from different threads.

Parameters

[in]	glasses	- T5_Glasses returned by t5CreateGlasses()
[out]	connectionState	- T5_ConnectionState representing connection state

Return values

T5_SUCCESS	Connection state was returned successfully
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_INTERNAL	Internal error - not correctable.

Referenced by tiltfive::Glasses::getConnectionState().

◆ t5GetGlassesIdentifier()

T5_EXPORT T5_Result t5GetGlassesIdentifier	(	T5_Glasses	glasses,
		char *	buffer,
		size_t *	bufferSize
	)

Get the device identifier of a glasses.

Threading: Exclusivity group 1 - Functions in this group must not be called concurrently from different threads.

Parameters

[in]	glasses	- T5_Glasses returned by t5CreateGlasses()
[out]	buffer	- C string buffer into which the result will be stored
[in,out]	bufferSize	- On Call: Size of buffer. On Return: Size of written data. Note that this may be larger than the buffer, in which case T5_ERROR_OVERFLOW is returned, and this value represents the size of the buffer needed to avoid overflow.

Return values

T5_SUCCESS	Identifier written to `ident`.
T5_ERROR_INVALID_ARGS	Nullptr was supplied for `ident`.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_STRING_OVERFLOW	Buffer is too small to contain the resutl

◆ t5ReserveGlasses()

T5_EXPORT T5_Result t5ReserveGlasses	(	T5_Glasses	glasses,
		const char *	displayName
	)

Reserve glasses for exclusive operations by the client.

Although several operations can be performed without acquiring an exclusive lock on glasses, there are a few for which an exclusive lock is required. Primarily, the ability to get poses (t5GetGlassesPose()) and send frames (t5SendFrameToGlasses()). To reserve glasses for exclusive use, use this function.

Clients may request glasses that aren't fully available yet (e.g. a device that isn't fully booted, or needs to be rebooted to be compatible with the client). That is why there's a two-step approach here requiring a request for exclusive access first. To finish preparing for exclusive operations, use t5EnsureGlassesReady().

Repeated calls to this function should be made until reserve is successful or an error occurs.

Threading: Exclusivity group 1 - Functions in this group must not be called concurrently from different threads.

Parameters

[in]	glasses	- T5_Glasses returned by t5CreateGlasses()
[in]	displayName	- Null terminated C string to display in control panel (localized) E.g. "Awesome Game (Player 1)"

Return values

T5_SUCCESS	Glasses reserved for this client.
T5_ERROR_UNAVAILABLE	Glasses already reserved by another client.
T5_ERROR_ALREADY_CONNECTED	Glasses already reserved and connected for this client.
T5_ERROR_DEVICE_LOST	Glasses have disconnected - destroy glasses with t5DestroyGlasses(), re-obtain with t5CreateGlasses() and try again.
T5_ERROR_INVALID_ARGS	Nullptr or invalid input supplied for `displayName`.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_INTERNAL	Internal error - not correctable.
T5_ERROR_STRING_OVERFLOW	`displayName` is too long.

Referenced by tiltfive::Glasses::reserve().

◆ t5SetGlassesDisplayName()

T5_EXPORT T5_Result t5SetGlassesDisplayName	(	T5_Glasses	glasses,
		const char *	displayName
	)

Set the display name for glasses that were previously reserved for exclusive operations.

Threading: Exclusivity group 1 - Functions in this group must not be called concurrently from different threads.

Parameters

[in]	glasses	- T5_Glasses returned by t5CreateGlasses()
[in]	displayName	- Null terminated C string to display in control panel (localized) E.g. "Awesome Game (Player 2)"

Return values

T5_SUCCESS	Glasses reserved for this client.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_INVALID_ARGS	Nullptr or invalid input supplied for `displayName`.
T5_ERROR_INVALID_STATE	Glasses weren't reserved first or client is invalid.
T5_ERROR_STRING_OVERFLOW	`displayName` is too long.