| Tilt Five NDK |

Functions
Glasses state management
Tilt Five™ Native Interface (C) » Glasses functions

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.