Collaboration diagram for Glasses functions:

Modules
	Glasses state management
	Functions related to the management of glasses state and exclusivity.

	Exclusive functions
	Functions requiring an exclusive connection.

	Glasses parameters
	Functions for getting glasses parameters.

	Wand related
	Functions related to wands.

Functions
T5_EXPORT T5_Result	t5ReleaseGlasses (T5_Glasses glasses)

T5_EXPORT T5_Result	t5ConfigureCameraStreamForGlasses (T5_Glasses glasses, T5_CameraStreamConfig config)
	Configure the camera stream. More...

T5_EXPORT T5_Result	t5GetFilledCamImageBuffer (T5_Glasses glasses, T5_CamImage *image)

T5_EXPORT T5_Result	t5SubmitEmptyCamImageBuffer (T5_Glasses glasses, T5_CamImage *image)
	Submit an empty image buffer to be filled by the camera frame stream. More...

T5_EXPORT T5_Result	t5CancelCamImageBuffer (T5_Glasses glasses, uint8_t *buffer)
	Clear out the remaining buffers and return all buffers as a vector of camera images. More...

T5_EXPORT T5_Result	t5ValidateFrameInfo (T5_Glasses glasses, const T5_FrameInfo info, char detail, size_t *detailSize)
	Validate a provided T5_FrameInfo. More...

T5_EXPORT T5_Result	t5GetProjection (T5_Glasses glasses, T5_CartesianCoordinateHandedness handedness, T5_DepthRange depthRange, T5_MatrixOrder matrixOrder, double nearPlane, double farPlane, double worldScale, T5_ProjectionInfo *projectionInfo)
	Get projection properties for glasses. More...

Detailed Description

Require a T5_Glasses for invocation

Function Documentation

◆ t5CancelCamImageBuffer()

T5_EXPORT T5_Result t5CancelCamImageBuffer	(	T5_Glasses	glasses,
		uint8_t *	buffer
	)

Clear out the remaining buffers and return all buffers as a vector of camera images.

Exclusive Connection: Requires an exclusive connection - established with makeExclusive().

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

Parameters

[in]	glasses	- T5_Glasses returned by T5ApiSys::createGlasses().
[in]	buffer	- A pointer to an image buffer that should be cancelled and no longer used by the service

Return values

T5_SUCCESS	Buffer is no longer in use and is available for freeing
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_NOT_CONNECTED	Glasses aren't exclusively connected for this client. Use makeExclusive() first.
T5_ERROR_INTERNAL	Internal error - not correctable.

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

◆ t5ConfigureCameraStreamForGlasses()

T5_EXPORT T5_Result t5ConfigureCameraStreamForGlasses	(	T5_Glasses	glasses,
		T5_CameraStreamConfig	config
	)

Configure the camera stream.

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]	config	- T5_CameraStreamConfig filled by client to detail configuration

Return values

T5_SUCCESS	Stream configured ok.
T5_ERROR_IO_FAILURE	Failed to communicate with the service.
T5_ERROR_NO_SERVICE	Service is unavailable.
T5_ERROR_TARGET_NOT_FOUND	Device not found.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.

The following are internal errors that should be discarded and/or logged:

Return values

T5_ERROR_INTERNAL	Internal (Not correctable): Generic error.
T5_ERROR_INVALID_STATE	Internal (Not correctable): Invalid state for request.

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

◆ t5GetFilledCamImageBuffer()

T5_EXPORT T5_Result t5GetFilledCamImageBuffer	(	T5_Glasses	glasses,
		T5_CamImage *	image
	)

Get a new filled image buffer from the camera stream. Will always return the oldest filled buffer. This function does not block on call, and will return a TryAgain error if there are no available filled buffers. To ensure images don't become stale, continual polling of t5GetFilledCamImageBuffer() and resubmission of empty buffers via t5SubmitEmptyCamImageBuffer() is expected.

Exclusive Connection: Requires an exclusive connection - established with makeExclusive().

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

Parameters

[in]	glasses	- T5_Glasses returned by T5ApiSys::createGlasses().
[out]	image	- T5_CamImage representing a camera image wrapper that will contain a filled buffer upon successful return.

Return values

T5_SUCCESS	Image written to `image`.
T5_ERROR_TRY_AGAIN	No available image.
T5_ERROR_INVALID_ARGS	Nullptr was supplied for `image`.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_NOT_CONNECTED	Glasses aren't exclusively connected for this client. Use makeExclusive() first.
::T5_INVALID_BUFFER	The buffer does not have the requisite size for a camera image
T5_ERROR_INTERNAL	Internal error - not correctable.

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

◆ t5GetProjection()

T5_EXPORT T5_Result t5GetProjection	(	T5_Glasses	glasses,
		T5_CartesianCoordinateHandedness	handedness,
		T5_DepthRange	depthRange,
		T5_MatrixOrder	matrixOrder,
		double	nearPlane,
		double	farPlane,
		double	worldScale,
		T5_ProjectionInfo *	projectionInfo
	)

Get projection properties for glasses.

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

Parameters

Each graphics API requires different properties when creating a projection matrix. They each have their defaults, for which the properties are shown below. If you are not using the defaults for your graphics API, ensure that you adjust the parameters used here.

      ┌───────┬──────┬──────┬──────────────────────────────────┐
      │ L/RHS │ Near │ Far  │ Native Equivalent Function       │

┌─────────┼───────┼──────┼──────┼──────────────────────────────────│ │ OpenGL │ RHS→ │ -1 │ +1 │ glFrustum │ │ DirectX │ ←LHS │ 0 │ +1 │ D3DXMatrixPerspectiveOffCenterLH │ │ Vulkan │ RHS→ │ 0 │ +1 │ │ │ Metal │ RHS→ │ -1 │ +1 │ │ └─────────┴───────┴──────┴──────┴──────────────────────────────────┘ Note: When referencing D3DXMatrixPerspectiveOffCenterLH, DirectX uses Row-major matrix

Parameters

[in]	glasses	- T5_Glasses returned by t5CreateGlasses().
[in]	handedness	- T5_CartesianCoordinateHandedness specifying handedness.
[in]	depthRange	- T5_DepthRange to use for matrix creation.
[in]	matrixOrder	- T5_MatrixOrder representing row or column major ordering.
[in]	nearPlane	- The near clipping plane in view space
[in]	farPlane	- The far clipping plane in view space
[in]	worldScale	- Conversion factor between world space and real-world units.
[out]	projectionInfo	- T5_ProjectionInfo to write values to.

Return values

T5_SUCCESS	Projection info written to projectionInfo.
T5_ERROR_INVALID_ARGS	Nullptr was supplied for `projectionInfo`. or Nullptr was supplied for `projectionInfo.matrix`. or `handedness` is invalid. or `depthRange` is invalid. or `matrixOrder` is invalid.
T5_ERROR_INVALID_GEOMETRY	nearPlane ≤ 0 or farPlane ≤ 0 or farPlane ≤ nearPlane or worldScale ≤ 0
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_IO_FAILURE	Failed to communicate with the service.
T5_ERROR_NO_SERVICE	Service is unavailable.
T5_ERROR_TARGET_NOT_FOUND	Device not found.

◆ t5ReleaseGlasses()

T5_EXPORT T5_Result t5ReleaseGlasses ( T5_Glasses glasses )

Release previously-reserved glasses.

Release glasses that were previously reserved for exclusive operations by the client. After calling this, exclusive operations cannot be used with the glasses unless the glasses are again reserved and readied.

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

Parameters

[in] glasses - T5_Glasses returned by T5ApiSys::createGlasses()

Return values

T5_SUCCESS	Glasses released.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.

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

◆ t5SubmitEmptyCamImageBuffer()

T5_EXPORT T5_Result t5SubmitEmptyCamImageBuffer	(	T5_Glasses	glasses,
		T5_CamImage *	image
	)

Submit an empty image buffer to be filled by the camera frame stream.

Exclusive Connection: Requires an exclusive connection - established with makeExclusive().

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

The memory in the image buffer Must remain valid until the corresponding wrapper is returned by t5GetFilledCamImageBuffer or the buffer is canceled by t5CancelCamImageBuffer

Note, only the image buffer inside of T5_CamImage is required to be kept valid. The T5_CamImage wrapper is not.

Incoming image is expected to have 0 width, height, and stride, and a buffer size larger than the minimum image size.

Parameters

[in]	glasses	- T5_Glasses returned by T5ApiSys::createGlasses().
[in]	image	- T5_CamImage representing current camera image buffer to be filled.

Return values

T5_SUCCESS	Buffer submitted to service.
T5_ERROR_INVALID_ARGS	Nullptr was supplied for `image`.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_NOT_CONNECTED	Glasses aren't exclusively connected for this client. Use makeExclusive() first.
::T5_INVALID_BUFFER	The buffer does not have the requisite size for a camera image
T5_ERROR_INTERNAL	Internal error - not correctable.

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

◆ t5ValidateFrameInfo()

T5_EXPORT T5_Result t5ValidateFrameInfo	(	T5_Glasses	glasses,
		const T5_FrameInfo *	info,
		char *	detail,
		size_t *	detailSize
	)

Validate a provided T5_FrameInfo.

Determines if the provided T5_FrameInfo is likely valid. Note that this function does not validate the texture handles beyond checking that they are not null - the validity of the texture handles is graphics API dependent, and currently beyond the scope of this function.

If there are errors detected in the T5_FrameInfo, T5_ERROR_DECODE_ERROR is returned and a human readable error message will be written to the provided detail buffer explaining the errors (if there are multiple errors, each will be seperated by a newline).

In the event of a buffer overflow writing to the detail buffer, T5_ERROR_OVERFLOW is returned and the detail message is truncated - Note that in all cases, if detailSize is greater than 0, a null terminator is written, however if detailSize is 0 nothing is written to detail and callers should ensure that they do not attempt to use the (potentially invalid) string.

Note: While this function is lightweight, it is not recommended to call it for every frame since the validated parameters are unlikely to change between frames. It is also not necessary to call this function at all - it is a convenience function to sanity check your inputs.

Threading: Exclusivity group 3 & Graphic thread only - Functions in this group must not be called concurrently from different threads. The calling thread must be the thread that provided the graphics context.

Parameters

[in]	info	- T5_ParamGlasses to get value for.
[out]	detail	- A buffer to receive a null terminated C string detailing the error with the T5_FrameInfo. In the case of T5_SUCCESS, an empty string will be written.
[in,out]	detailSize	- On Call: Size of the buffer pointed to by `detail`. On Return: Size of the message returned in detail including the string null terminator. 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	The supplied frame info is likely valid.
T5_ERROR_NO_CONTEXT	`glasses` is invalid.
T5_ERROR_DECODE_ERROR	There were errors with the supplied frame info.
T5_ERROR_INVALID_ARGS	Null was supplied for info, detail or detailSize.
T5_ERROR_OVERFLOW	The detail message is larger than the supplied buffer.

Modules

Functions

Detailed Description

Function Documentation

◆ t5CancelCamImageBuffer()

◆ t5ConfigureCameraStreamForGlasses()

◆ t5GetFilledCamImageBuffer()

◆ t5GetProjection()

◆ t5ReleaseGlasses()

◆ t5SubmitEmptyCamImageBuffer()

◆ t5ValidateFrameInfo()