App Volumes

Typedefs Index

typedef	void(* qar_app_volume_gesture_event_callback_t)(QarAppVolumeGesture *gesture, void *user_state)
	Receives one mapped gesture on a subscribed app volume. More...
typedef	void(* qar_app_volume_update_callback_t)(QarAppVolume *handle, void *user_state)

Functions Index

static QarResult	qar_app_volume_gesture_get_classification (QarAppVolumeGesture *gesture, QarGestureKind *out_kind, QarGesturePhase *out_phase)
	What this gesture is and where in its lifecycle it sits. More...
static QarResult	qar_app_volume_gesture_get_deltas (QarAppVolumeGesture *gesture, QarVector3 *out_translation_delta, QarQuaternion *out_rotation_delta, bool *out_was_mapped_to_app_transform)
	The rigid motion accumulated since the gesture started, and whether the library already applied it. More...
static QarResult	qar_app_volume_gesture_get_gesture_id (QarAppVolumeGesture *gesture, uint64_t *out_gesture_id)
	The gesture's lifecycle id. More...
static QarResult	qar_app_volume_gesture_get_handedness (QarAppVolumeGesture *gesture, QarHandedness *out_handedness)
	Which hand the gesture came from. More...
static QarResult	qar_app_volume_gesture_get_lifecycle (QarAppVolumeGesture *gesture, QarPeerId *out_source_peer_id, QarAppVolumeId *out_target_app_volume_id)
	The lifecycle this gesture belongs to: the peer and the target volume. More...
static QarResult	qar_app_volume_gesture_get_mode (QarAppVolumeGesture *gesture, QarAppVolumeGestureModeId *out_mode_id)
	The gesture mode whose rule mapped the gesture. More...
static QarResult	qar_app_volume_gesture_get_points (QarAppVolumeGesture *gesture, QarVector3 *out_action_point, bool *out_has_action_point, QarVector3 *out_start_point, bool *out_has_start_point)
	Where the gesture is acting now, and where its lifecycle began. More...
static QarResult	qar_app_volume_gesture_get_timestamp (QarAppVolumeGesture *gesture, QarTimePoint *out_timestamp)
	When the recogniser emitted this gesture, on its own clock. More...
static QarResult	qar_app_volume_get_active_gesture_mode (QarAppVolume *handle, const QarPeerId *peer, QarAppVolumeGestureModeId *out_mode_id)
	The gesture mode a peer's next gesture maps through. More...
static QarResult	qar_app_volume_get_app_pose (QarAppVolume *handle, QarPose *out_pose)
	Get app pose for an app volume handle. More...
static QarResult	qar_app_volume_get_app_scale (QarAppVolume *handle, float *out_scale)
	Get app scale for an app volume handle. More...
static QarResult	qar_app_volume_get_app_world_anchor (QarAppVolume *handle, QarAppWorldAnchor *out_anchor)
	Get app world anchor for an app volume handle. More...
static QarResult	qar_app_volume_get_display_name (QarAppVolume *handle, char *out_buffer, size_t buffer_size)
	Get the display name string for an app volume. More...
static QarResult	qar_app_volume_get_editing_status (QarAppVolume *handle, QarAppVolumeEditingStatus *out_status)
	Get current editing lock status and editor peer. More...
static QarResult	qar_app_volume_get_gesture_allowed_peers (QarAppVolume *handle, QarPeerId *out_peers, size_t peer_capacity, size_t *out_peer_count)
	The peers whose gestures may move or scale the app in this volume. More...
static QarResult	qar_app_volume_get_gesture_configuration (QarAppVolume *handle, QarAppVolumeGestureConfiguration *out_config)
	Get the default gesture mode's configuration for an app volume handle. More...
static QarResult	qar_app_volume_get_gesture_holder (QarAppVolume *handle, QarPeerId *out_peer, bool *out_is_held)
	Which peer is manipulating the app in this volume, if one is. More...
static QarResult	qar_app_volume_get_gesture_mode (QarAppVolume *handle, QarAppVolumeGestureModeId mode_id, QarAppVolumeGestureConfiguration *out_config)
	One gesture mode's rules. More...
static QarResult	qar_app_volume_get_gesture_mode_ids (QarAppVolume *handle, QarAppVolumeGestureModeId *out_mode_ids, size_t mode_capacity, size_t *out_mode_count)
	The ids of the gesture modes an app volume defines. More...
static QarResult	qar_app_volume_get_id (QarAppVolume *handle, QarAppVolumeId *out_id)
static QarResult	qar_app_volume_get_latest_app_pose (QarSession *session, const QarAppVolumeId *volume_id, QarPose *out_pose)
	Get the latest locally known fast-path app pose for this app volume. More...
static QarResult	qar_app_volume_get_latest_app_scale (QarSession *session, const QarAppVolumeId *volume_id, float *out_scale)
	Get the latest locally known fast-path app scale for this app volume. More...
static QarResult	qar_app_volume_get_latest_pose (QarSession *session, const QarAppVolumeId *volume_id, QarPose *out_pose)
	Get the latest locally known fast-path pose for this app volume. More...
static QarResult	qar_app_volume_get_latest_size (QarSession *session, const QarAppVolumeId *volume_id, QarAppVolumeSize *out_size)
	Get the latest locally known fast-path size for this app volume. More...
static QarResult	qar_app_volume_get_lifetime_status (QarAppVolume *handle, QarAppVolumeLifetimeStatus *out_status)
	Get the lifetime status (active/closed). More...
static QarResult	qar_app_volume_get_pose (QarAppVolume *handle, QarPose *out_pose)
	Get the pose of an app volume. More...
static QarResult	qar_app_volume_get_size (QarAppVolume *handle, QarAppVolumeSize *out_size)
	Get the current size of an app volume. More...
static QarResult	qar_app_volume_get_used_by_peers (QarAppVolume *handle, QarPeerId *out_peers, size_t peers_buffer_size, size_t *out_peers_written)
	Enumerate peers using the volume into provided buffer. More...
static QarResult	qar_app_volume_get_used_by_peers_count (QarAppVolume *handle, size_t *out_peer_count)
	Get number of peers currently using this volume. More...
static void	qar_app_volume_handle_destroy (QarAppVolume *handle)
static bool	qar_app_volume_handle_is_valid (QarAppVolume *handle)
static QarResult	qar_app_volumes_change_app_pose (QarSession *session, const QarAppVolumeId *volume_id, const QarPose *app_pose)
	Update app pose for an existing app volume. More...
static QarResult	qar_app_volumes_change_app_scale (QarSession *session, const QarAppVolumeId *volume_id, float scale)
	Low-latency fast-path update for latest app scale. More...
static QarResult	qar_app_volumes_change_app_world_anchor (QarSession *session, const QarAppVolumeId *volume_id, const QarGeoAnchorFrame *anchor)
	Set app world anchor metadata. More...
static QarResult	qar_app_volumes_change_display_name (QarSession *session, const QarAppVolumeId *volume_id, const char *display_name)
static QarResult	qar_app_volumes_change_gesture_configuration (QarSession *session, const QarAppVolumeId *volume_id, const QarAppVolumeGestureConfiguration *config)
	Update the default gesture mode and the allowed peers of an existing app volume. More...
static QarResult	qar_app_volumes_change_gesture_mode (QarSession *session, const QarAppVolumeId *volume_id, QarAppVolumeGestureModeId mode_id, const QarAppVolumeGestureConfiguration *config)
	Define a gesture mode, or replace the mode with that id. More...
static QarResult	qar_app_volumes_change_pose (QarSession *session, const QarAppVolumeId *volume_id, const QarPose *pose)
	Low-latency fast-path update for latest pose. More...
static QarResult	qar_app_volumes_change_size (QarSession *session, const QarAppVolumeId *volume_id, const QarAppVolumeSize *size)
	Resize an app volume. More...
static QarResult	qar_app_volumes_clear_all_peer_gesture_modes (QarSession *session, const QarAppVolumeId *volume_id)
	Drop every peer's own gesture mode, so all follow the default. More...
static QarResult	qar_app_volumes_clear_app_world_anchor (QarSession *session, const QarAppVolumeId *volume_id)
	Clear app world anchor metadata. More...
static QarResult	qar_app_volumes_clear_peer_gesture_mode (QarSession *session, const QarAppVolumeId *volume_id, const QarPeerId *peer)
	Drop one peer's own gesture mode, so it follows the default again. More...
static QarResult	qar_app_volumes_close_volume (QarSession *session, const QarAppVolumeId *volume_id)
	Close an app volume. More...
static QarResult	qar_app_volumes_get_or_create (QarSession *session, const QarAppVolumeInit *init, QarAppVolumeId *out_volume)
	Get the app volume identified by init->common_name, creating it (via init) if it does not exist yet. More...
static QarResult	qar_app_volumes_remove_gesture_mode (QarSession *session, const QarAppVolumeId *volume_id, QarAppVolumeGestureModeId mode_id)
	Remove a gesture mode. More...
static QarResult	qar_app_volumes_select_gesture_mode (QarSession *session, const QarAppVolumeId *volume_id, const QarPeerId *peer, QarAppVolumeGestureModeId mode_id)
	Switch one peer, or every peer without its own mode, to a gesture mode. More...
static QarResult	qar_app_volumes_start_editing (QarSession *session, const QarAppVolumeId *volume_id)
	Request editing lock for the volume. More...
static QarResult	qar_app_volumes_stop_editing (QarSession *session, const QarAppVolumeId *volume_id)
	Release editing lock for the volume. More...
static QarResult	qar_app_volumes_subscribe_all_gesture_events (QarSession *session, const QarAppVolumeId *volume_id, qar_app_volume_gesture_event_callback_t callback, void *user_state, QarCancelToken *token)
	Subscribe to every gesture kind on one app volume, through one callback. More...
static QarResult	qar_app_volumes_subscribe_gesture_events (QarSession *session, const QarAppVolumeId *volume_id, QarGestureKind gesture_kind, qar_app_volume_gesture_event_callback_t callback, void *user_state, QarCancelToken *token)
	Subscribe to one kind of mapped gesture on a specific app volume. More...
static QarResult	qar_app_volumes_subscribe_updates (QarSession *session, qar_app_volume_update_callback_t callback, void *user_state, QarCancelToken *token)
	Subscribe to updates for app volumes. More...
static QarResult	qar_app_volumes_update_used_by_peers (QarSession *session, const QarAppVolumeId *volume_id, const QarPeerId *peer_additions, size_t additions_count, const QarPeerId *peer_removals, size_t removals_count)
	Update which peers use the volume. More...
static QarResult	qar_query_app_volumes (QarSession *session, QarAppVolume **out_handles, size_t handles_buffer_size, size_t *out_handles_written)
	Enumerate app volumes into provided array of handles. More...
static QarResult	qar_query_app_volumes_count (QarSession *session, size_t *out_count)
	Query number of app volumes known to the session. More...

Typedefs

qar_app_volume_gesture_event_callback_t

typedef void(* qar_app_volume_gesture_event_callback_t)(QarAppVolumeGesture *gesture, void *user_state)

Receives one mapped gesture on a subscribed app volume.

Documented on the public declaration in <qar_streaming_c/v0/api.h>.

gesture is an opaque handle to library-owned storage, valid only for the duration of this call. Read what you need through the qar_app_volume_gesture_get_*() accessors and copy anything the application keeps; the handle must not be stored. user_state is the pointer handed to the subscribe call. The callback runs on a library background thread, so it must not block and must not call back into a subscribe function.

It is a handle rather than a struct so the event can gain fields - a scale delta, a per-hand breakdown, a confidence - by appending an accessor, which is an additive change, instead of growing a struct, which would break every compiled consumer. This mirrors qar_gui_panel_gesture_event_callback_t.

Definition at line 3754 of file qar_streaming.h.

qar_app_volume_update_callback_t

typedef void(* qar_app_volume_update_callback_t)(QarAppVolume *handle, void *user_state)

Definition at line 3736 of file qar_streaming.h.

Functions

qar_app_volume_gesture_get_classification()

QarResult qar_app_volume_gesture_get_classification (QarAppVolumeGesture * gesture, QarGestureKind * out_kind, QarGesturePhase * out_phase)

inline static

What this gesture is and where in its lifecycle it sits.

Returned together because a consumer dispatches on both at once. Both are enums, so a future gesture kind or phase is a new enumerator rather than a change to this call. out_kind always equals the kind the subscription asked for; read it so one callback can serve several subscriptions.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_kind	Receives the gesture kind; must not be NULL.
out_phase	Receives started, updated, ended, canceled or instant; must not be NULL.

Definition at line 3881 of file qar_streaming.h.

qar_app_volume_gesture_get_deltas()

QarResult qar_app_volume_gesture_get_deltas (QarAppVolumeGesture * gesture, QarVector3 * out_translation_delta, QarQuaternion * out_rotation_delta, bool * out_was_mapped_to_app_transform)

inline static

The rigid motion accumulated since the gesture started, and whether the library already applied it.

out_translation_delta is a vector and out_rotation_delta a quaternion; together they are one rigid transform, which is why they are read as a pair. Both are in the target volume's app volume space - not app content space, unlike the points - and both are shaped by the volume's mapping rule: the translation is scaled by its precision and scale sensitivity, so it is in metres only for precision 1 with constant sensitivity, and both are masked by its axis flags. QAR_GESTURE_DUAL_POINTER_TRANSLATE_DISTANCE is the exception for the translation: it is the change of the distance between the hands as a vector along their separation in the user's head-yaw frame, whose length is that change, and it is not rotated into the volume.

out_was_mapped_to_app_transform belongs with them: it is true when the volume's QarGestureAppTransformMapping already folded this delta into the volume's app pose or app scale, so a consumer that applies it again moves the content twice. Reading a delta without it is a double-apply bug, which is why it is not a separate call.

A gesture kind that later gains a scale delta gets its own accessor rather than a fourth out-parameter here.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_translation_delta	Receives the accumulated translation; must not be NULL.
out_rotation_delta	Receives the accumulated rotation; must not be NULL.
out_was_mapped_to_app_transform	Receives whether the library already applied the delta; must not be NULL.

Definition at line 3957 of file qar_streaming.h.

qar_app_volume_gesture_get_gesture_id()

QarResult qar_app_volume_gesture_get_gesture_id (QarAppVolumeGesture * gesture, uint64_t * out_gesture_id)

inline static

The gesture's lifecycle id.

The same for a gesture's Started, Updated and Ended or Canceled, and unique within its source peer, so a consumer pairs a lifecycle by the source peer and this id. 0 for a QAR_GESTURE_PHASE_INSTANT gesture, which has no lifecycle.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_gesture_id	Receives the id; must not be NULL.

Returns

QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.

Definition at line 4006 of file qar_streaming.h.

qar_app_volume_gesture_get_handedness()

QarResult qar_app_volume_gesture_get_handedness (QarAppVolumeGesture * gesture, QarHandedness * out_handedness)

inline static

Which hand the gesture came from.

A gesture of one hand – hover, click, single-pointer 6DoF – names it: QAR_HANDEDNESS_LEFT or QAR_HANDEDNESS_RIGHT. A gesture of both hands together, QAR_GESTURE_DUAL_POINTER_TRANSLATE_DISTANCE and QAR_GESTURE_DUAL_POINTER_ROTATE, has none and reports QAR_HANDEDNESS_UNSPECIFIED. Two hovers that arrive together are the user's two rays, told apart by this.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_handedness	Receives the hand, or QAR_HANDEDNESS_UNSPECIFIED for a two-hand gesture; never left stale. Must not be NULL.

Returns

QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.

Definition at line 3990 of file qar_streaming.h.

qar_app_volume_gesture_get_lifecycle()

QarResult qar_app_volume_gesture_get_lifecycle (QarAppVolumeGesture * gesture, QarPeerId * out_source_peer_id, QarAppVolumeId * out_target_app_volume_id)

inline static

The lifecycle this gesture belongs to: the peer and the target volume.

They are returned together because they are one key. This event carries no gesture id, so a consumer that stores lifecycles keys on this pair plus the kind from qar_app_volume_gesture_get_classification(); a peer runs at most one gesture of a kind against a volume at a time.

The peer is the one whose hand or controller produced the gesture - NOT the peer that recognised it. A mixer runs under its own peer id and publishes for the target peer it serves. The volume is always the one the subscription named, so a callback serving one volume can read it from its user_state instead.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_source_peer_id	Receives the producing peer; must not be NULL.
out_target_app_volume_id	Receives the volume acted on; must not be NULL.

Definition at line 3862 of file qar_streaming.h.

qar_app_volume_gesture_get_mode()

QarResult qar_app_volume_gesture_get_mode (QarAppVolumeGesture * gesture, QarAppVolumeGestureModeId * out_mode_id)

inline static

The gesture mode whose rule mapped the gesture.

The source peer's mode when the gesture began: a running gesture keeps it through a mode switch, so its Started, Updated and Ended all report the same mode. Lets an application act on the same gesture differently per mode, such as a click that selects in one mode and measures in another.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_mode_id	Receives the mode; must not be NULL.

Returns

QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.

Definition at line 4022 of file qar_streaming.h.

qar_app_volume_gesture_get_points()

QarResult qar_app_volume_gesture_get_points (QarAppVolumeGesture * gesture, QarVector3 * out_action_point, bool * out_has_action_point, QarVector3 * out_start_point, bool * out_has_start_point)

inline static

Where the gesture is acting now, and where its lifecycle began.

Both are in app content space - the space the source app renders in - and in app units, under the app pose and scale the gesture began with. Both are optional: each point comes with its own validity flag rather than a sentinel value, because the origin is a legal position.

• The start point is the hand: where it was when the gesture began, and for a hover where it is now. A two-hand gesture starts midway between the hands.
• The action point is the intersection the gesture acts on, or the start point when nothing was intersected, so it is absent only when the start point is too. For a drag it is the content the gesture grabbed.
• An absent point is zeroed, never left stale.

Returned together because they are read together: from the start point to the action point is the ray the user is pointing along, which an app can draw itself. The travel of a gesture is its delta, not their difference.

Parameters

gesture	Gesture handed to the callback; must not be NULL.
out_action_point	Receives the point the gesture is applied to; must not be NULL.
out_has_action_point	Receives whether out_action_point was filled; must not be NULL.
out_start_point	Receives where this lifecycle began; must not be NULL.
out_has_start_point	Receives whether out_start_point was filled; must not be NULL.

Definition at line 3916 of file qar_streaming.h.

qar_app_volume_gesture_get_timestamp()

QarResult qar_app_volume_gesture_get_timestamp (QarAppVolumeGesture * gesture, QarTimePoint * out_timestamp)

inline static

When the recogniser emitted this gesture, on its own clock.

Not the device's sample time: device clocks are neither comparable nor monotonic across producers, so this is comparable only within one source peer id.

Definition at line 3971 of file qar_streaming.h.

qar_app_volume_get_active_gesture_mode()

QarResult qar_app_volume_get_active_gesture_mode (QarAppVolume * handle, const QarPeerId * peer, QarAppVolumeGestureModeId * out_mode_id)

inline static

The gesture mode a peer's next gesture maps through.

The peer's own mode when it has one, the default otherwise. With a NULL peer, the default. A mode that is no longer defined reads as QAR_APP_VOLUME_GESTURE_MODE_DEFAULT, which is also what the mapper uses.

Parameters

handle	The app volume; must be valid.
peer	The peer, or NULL for the default.
out_mode_id	Receives the mode; must not be NULL.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, or QAR_STATUS_APP_VOLUME_INVALID_ID for an invalid handle.

Definition at line 4338 of file qar_streaming.h.

qar_app_volume_get_app_pose()

QarResult qar_app_volume_get_app_pose (QarAppVolume * handle, QarPose * out_pose)

inline static

Get app pose for an app volume handle.

Definition at line 4116 of file qar_streaming.h.

qar_app_volume_get_app_scale()

QarResult qar_app_volume_get_app_scale (QarAppVolume * handle, float * out_scale)

inline static

Get app scale for an app volume handle.

Definition at line 4119 of file qar_streaming.h.

qar_app_volume_get_app_world_anchor()

QarResult qar_app_volume_get_app_world_anchor (QarAppVolume * handle, QarAppWorldAnchor * out_anchor)

inline static

Get app world anchor for an app volume handle.

Definition at line 4121 of file qar_streaming.h.

qar_app_volume_get_display_name()

QarResult qar_app_volume_get_display_name (QarAppVolume * handle, char * out_buffer, size_t buffer_size)

inline static

Get the display name string for an app volume.

Definition at line 4033 of file qar_streaming.h.

qar_app_volume_get_editing_status()

QarResult qar_app_volume_get_editing_status (QarAppVolume * handle, QarAppVolumeEditingStatus * out_status)

inline static

Get current editing lock status and editor peer.

Definition at line 4047 of file qar_streaming.h.

qar_app_volume_get_gesture_allowed_peers()

QarResult qar_app_volume_get_gesture_allowed_peers (QarAppVolume * handle, QarPeerId * out_peers, size_t peer_capacity, size_t * out_peer_count)

inline static

The peers whose gestures may move or scale the app in this volume.

Empty means every peer's may. Copies at most peer_capacity peers into out_peers and reports how many there are in out_peer_count, so a call with a capacity of 0 and a NULL out_peers asks for the count alone. Set with QarAppVolumeGestureAllowedPeersExt.

Parameters

handle	The app volume; must be valid.
out_peers	Receives up to peer_capacity peers; may be NULL when peer_capacity is 0.
peer_capacity	How many peers out_peers holds.
out_peer_count	Receives how many peers are allowed, which may exceed peer_capacity; must not be NULL.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, or QAR_STATUS_APP_VOLUME_INVALID_ID for an invalid handle.

Definition at line 4067 of file qar_streaming.h.

qar_app_volume_get_gesture_configuration()

QarResult qar_app_volume_get_gesture_configuration (QarAppVolume * handle, QarAppVolumeGestureConfiguration * out_config)

inline static

Get the default gesture mode's configuration for an app volume handle.

Returns the rules of QAR_APP_VOLUME_GESTURE_MODE_DEFAULT; read another mode's with qar_app_volume_get_gesture_mode(). Mapping rules are returned in priority order. Earlier entries in mapping_rules have higher priority than later entries.

Definition at line 4152 of file qar_streaming.h.

qar_app_volume_get_gesture_holder()

QarResult qar_app_volume_get_gesture_holder (QarAppVolume * handle, QarPeerId * out_peer, bool * out_is_held)

inline static

Which peer is manipulating the app in this volume, if one is.

One peer at a time moves or scales the app with a gesture: the first whose manipulation binds holds the volume until it ends, and every other peer's manipulations are refused meanwhile. Their hover and click still arrive.

Parameters

handle	The app volume; must be valid.
out_peer	Receives the holder; the default peer id when none holds it. Must not be NULL.
out_is_held	Receives whether a peer holds it; must not be NULL.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, or QAR_STATUS_APP_VOLUME_INVALID_ID for an invalid handle.

Definition at line 4088 of file qar_streaming.h.

qar_app_volume_get_gesture_mode()

QarResult qar_app_volume_get_gesture_mode (QarAppVolume * handle, QarAppVolumeGestureModeId mode_id, QarAppVolumeGestureConfiguration * out_config)

inline static

One gesture mode's rules.

Parameters

handle	The app volume; must be valid.
mode_id	The mode to read.
out_config	Receives the mode's rules in priority order, with header.next NULL. Must not be NULL.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, QAR_STATUS_APP_VOLUME_INVALID_ID for an invalid handle, or QAR_STATUS_APP_VOLUME_GESTURE_MODE_UNKNOWN for a mode the volume does not have.

Definition at line 4319 of file qar_streaming.h.

qar_app_volume_get_gesture_mode_ids()

QarResult qar_app_volume_get_gesture_mode_ids (QarAppVolume * handle, QarAppVolumeGestureModeId * out_mode_ids, size_t mode_capacity, size_t * out_mode_count)

inline static

The ids of the gesture modes an app volume defines.

Always includes QAR_APP_VOLUME_GESTURE_MODE_DEFAULT. Copies at most mode_capacity ids into out_mode_ids and reports how many there are in out_mode_count, so a call with a capacity of 0 and a NULL out_mode_ids asks for the count alone.

Parameters

handle	The app volume; must be valid.
out_mode_ids	Receives up to mode_capacity ids; may be NULL when mode_capacity is 0.
mode_capacity	How many ids out_mode_ids holds.
out_mode_count	Receives how many modes there are, which may exceed mode_capacity; must not be NULL.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, or QAR_STATUS_APP_VOLUME_INVALID_ID for an invalid handle.

Definition at line 4300 of file qar_streaming.h.

qar_app_volume_get_id()

QarResult qar_app_volume_get_id (QarAppVolume * handle, QarAppVolumeId * out_id)

inline static

Definition at line 4031 of file qar_streaming.h.

qar_app_volume_get_latest_app_pose()

QarResult qar_app_volume_get_latest_app_pose (QarSession * session, const QarAppVolumeId * volume_id, QarPose * out_pose)

inline static

Get the latest locally known fast-path app pose for this app volume.

Definition at line 4126 of file qar_streaming.h.

qar_app_volume_get_latest_app_scale()

QarResult qar_app_volume_get_latest_app_scale (QarSession * session, const QarAppVolumeId * volume_id, float * out_scale)

inline static

Get the latest locally known fast-path app scale for this app volume.

Definition at line 4131 of file qar_streaming.h.

qar_app_volume_get_latest_pose()

QarResult qar_app_volume_get_latest_pose (QarSession * session, const QarAppVolumeId * volume_id, QarPose * out_pose)

inline static

Get the latest locally known fast-path pose for this app volume.

Definition at line 4135 of file qar_streaming.h.

qar_app_volume_get_latest_size()

QarResult qar_app_volume_get_latest_size (QarSession * session, const QarAppVolumeId * volume_id, QarAppVolumeSize * out_size)

inline static

Get the latest locally known fast-path size for this app volume.

Definition at line 4139 of file qar_streaming.h.

qar_app_volume_get_lifetime_status()

QarResult qar_app_volume_get_lifetime_status (QarAppVolume * handle, QarAppVolumeLifetimeStatus * out_status)

inline static

Get the lifetime status (active/closed).

Definition at line 4043 of file qar_streaming.h.

qar_app_volume_get_pose()

QarResult qar_app_volume_get_pose (QarAppVolume * handle, QarPose * out_pose)

inline static

Get the pose of an app volume.

Definition at line 4038 of file qar_streaming.h.

qar_app_volume_get_size()

QarResult qar_app_volume_get_size (QarAppVolume * handle, QarAppVolumeSize * out_size)

inline static

Get the current size of an app volume.

Definition at line 4041 of file qar_streaming.h.

qar_app_volume_get_used_by_peers()

QarResult qar_app_volume_get_used_by_peers (QarAppVolume * handle, QarPeerId * out_peers, size_t peers_buffer_size, size_t * out_peers_written)

inline static

Enumerate peers using the volume into provided buffer.

Definition at line 4097 of file qar_streaming.h.

qar_app_volume_get_used_by_peers_count()

QarResult qar_app_volume_get_used_by_peers_count (QarAppVolume * handle, size_t * out_peer_count)

inline static

Get number of peers currently using this volume.

Definition at line 4093 of file qar_streaming.h.

qar_app_volume_handle_destroy()

void qar_app_volume_handle_destroy (QarAppVolume * handle)

inline static

Definition at line 4029 of file qar_streaming.h.

qar_app_volume_handle_is_valid()

bool qar_app_volume_handle_is_valid (QarAppVolume * handle)

inline static

Definition at line 4028 of file qar_streaming.h.

qar_app_volumes_change_app_pose()

QarResult qar_app_volumes_change_app_pose (QarSession * session, const QarAppVolumeId * volume_id, const QarPose * app_pose)

inline static

Update app pose for an existing app volume.

Definition at line 3707 of file qar_streaming.h.

qar_app_volumes_change_app_scale()

QarResult qar_app_volumes_change_app_scale (QarSession * session, const QarAppVolumeId * volume_id, float scale)

inline static

Low-latency fast-path update for latest app scale.

Definition at line 3713 of file qar_streaming.h.

qar_app_volumes_change_app_world_anchor()

QarResult qar_app_volumes_change_app_world_anchor (QarSession * session, const QarAppVolumeId * volume_id, const QarGeoAnchorFrame * anchor)

inline static

Set app world anchor metadata.

Returns

QAR_STATUS_ARGUMENT_NOT_SUPPORTED when anchor's handedness is QAR_HANDEDNESS_UNSPECIFIED.

Definition at line 3722 of file qar_streaming.h.

qar_app_volumes_change_display_name()

QarResult qar_app_volumes_change_display_name (QarSession * session, const QarAppVolumeId * volume_id, const char * display_name)

inline static

Definition at line 3673 of file qar_streaming.h.

qar_app_volumes_change_gesture_configuration()

QarResult qar_app_volumes_change_gesture_configuration (QarSession * session, const QarAppVolumeId * volume_id, const QarAppVolumeGestureConfiguration * config)

inline static

Update the default gesture mode and the allowed peers of an existing app volume.

Replaces the rules of QAR_APP_VOLUME_GESTURE_MODE_DEFAULT and the allowed peers (QarAppVolumeGestureAllowedPeersExt, empty when not chained). Every other mode is kept; define those with qar_app_volumes_change_gesture_mode().

The order of config->mapping_rules defines runtime priority. Earlier rules have higher priority and can suppress lower-priority gestures when both are active at the same time for the same app volume and source peer.

Returns

QarResult QAR_STATUS_APP_VOLUME_GESTURE_CONFIGURATION_INVALID when a rule could never work – an enabled DualPointerRotate rule that moves the app with rotation_axes set to none, which would take two-hand gestures over and turn nothing. The volume keeps its previous configuration. Adding a volume with such a configuration fails the same way.

Definition at line 4172 of file qar_streaming.h.

qar_app_volumes_change_gesture_mode()

QarResult qar_app_volumes_change_gesture_mode (QarSession * session, const QarAppVolumeId * volume_id, QarAppVolumeGestureModeId mode_id, const QarAppVolumeGestureConfiguration * config)

inline static

Define a gesture mode, or replace the mode with that id.

A mode is a set of mapping rules – what each gesture does and how its ray looks – that peers can be switched to with qar_app_volumes_select_gesture_mode(), so a user's gestures and rays change with one small call instead of a whole configuration. Every volume has QAR_APP_VOLUME_GESTURE_MODE_DEFAULT; any other id is the application's to choose. Other modes and the allowed peers are kept.

Parameters

session	Session that owns the volume; must not be NULL.
volume_id	The app volume; must not be NULL.
mode_id	The mode to define or replace.
config	The mode's rules, in priority order. Its header.next must be NULL: the allowed peers are the volume's, for every mode, and are set with qar_app_volumes_change_gesture_configuration().

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, QAR_STATUS_ARGUMENT_NOT_SUPPORTED for a chained extension, or QAR_STATUS_APP_VOLUME_GESTURE_CONFIGURATION_INVALID for a rule that could never work, as with qar_app_volumes_change_gesture_configuration().

Definition at line 4200 of file qar_streaming.h.

qar_app_volumes_change_pose()

QarResult qar_app_volumes_change_pose (QarSession * session, const QarAppVolumeId * volume_id, const QarPose * pose)

inline static

Low-latency fast-path update for latest pose.

Definition at line 3732 of file qar_streaming.h.

qar_app_volumes_change_size()

QarResult qar_app_volumes_change_size (QarSession * session, const QarAppVolumeId * volume_id, const QarAppVolumeSize * size)

inline static

Resize an app volume.

Definition at line 3679 of file qar_streaming.h.

qar_app_volumes_clear_all_peer_gesture_modes()

QarResult qar_app_volumes_clear_all_peer_gesture_modes (QarSession * session, const QarAppVolumeId * volume_id)

inline static

Drop every peer's own gesture mode, so all follow the default.

Parameters

session	Session that owns the volume; must not be NULL.
volume_id	The app volume; must not be NULL.

Returns

QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.

Definition at line 4279 of file qar_streaming.h.

qar_app_volumes_clear_app_world_anchor()

QarResult qar_app_volumes_clear_app_world_anchor (QarSession * session, const QarAppVolumeId * volume_id)

inline static

Clear app world anchor metadata.

Definition at line 3728 of file qar_streaming.h.

qar_app_volumes_clear_peer_gesture_mode()

QarResult qar_app_volumes_clear_peer_gesture_mode (QarSession * session, const QarAppVolumeId * volume_id, const QarPeerId * peer)

inline static

Drop one peer's own gesture mode, so it follows the default again.

Does nothing for a peer that has none.

Parameters

session	Session that owns the volume; must not be NULL.
volume_id	The app volume; must not be NULL.
peer	The peer; must not be NULL.

Returns

QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.

Definition at line 4268 of file qar_streaming.h.

qar_app_volumes_close_volume()

QarResult qar_app_volumes_close_volume (QarSession * session, const QarAppVolumeId * volume_id)

inline static

Close an app volume.

Definition at line 3685 of file qar_streaming.h.

qar_app_volumes_get_or_create()

QarResult qar_app_volumes_get_or_create (QarSession * session, const QarAppVolumeInit * init, QarAppVolumeId * out_volume)

inline static

Get the app volume identified by init->common_name, creating it (via init) if it does not exist yet.

Fails with QAR_STATUS_ARGUMENT_NOT_SUPPORTED when init->has_app_world_anchor is set and init->app_world_anchor.handedness is QAR_HANDEDNESS_UNSPECIFIED.

Definition at line 3668 of file qar_streaming.h.

qar_app_volumes_remove_gesture_mode()

QarResult qar_app_volumes_remove_gesture_mode (QarSession * session, const QarAppVolumeId * volume_id, QarAppVolumeGestureModeId mode_id)

inline static

Remove a gesture mode.

A peer switched to the removed mode, or the default selection naming it, falls back to QAR_APP_VOLUME_GESTURE_MODE_DEFAULT. A gesture already running in it finishes in it.

Parameters

session	Session that owns the volume; must not be NULL.
volume_id	The app volume; must not be NULL.
mode_id	The mode to remove.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, QAR_STATUS_APP_VOLUME_GESTURE_CONFIGURATION_INVALID for QAR_APP_VOLUME_GESTURE_MODE_DEFAULT, which cannot be removed, or QAR_STATUS_APP_VOLUME_GESTURE_MODE_UNKNOWN for a mode the volume does not have.

Definition at line 4223 of file qar_streaming.h.

qar_app_volumes_select_gesture_mode()

QarResult qar_app_volumes_select_gesture_mode (QarSession * session, const QarAppVolumeId * volume_id, const QarPeerId * peer, QarAppVolumeGestureModeId mode_id)

inline static

Switch one peer, or every peer without its own mode, to a gesture mode.

With peer, that peer's gestures map through mode_id from now on, whatever the default is. With a NULL peer, mode_id becomes the default every peer without its own mode follows; peers switched individually stay in theirs (clear them with qar_app_volumes_clear_peer_gesture_mode() or qar_app_volumes_clear_all_peer_gesture_modes()).

A gesture already running keeps the mode it began in, so a drag never changes its mapping halfway; the switch applies from the next gesture. The peer's rays take the new mode's styles as its next gesture is mapped.

Parameters

session	Session that owns the volume; must not be NULL.
volume_id	The app volume; must not be NULL.
peer	The peer to switch, or NULL for the default.
mode_id	The mode to switch to; the volume must define it.

Returns

QAR_STATUS_SUCCESS, QAR_STATUS_LOGIC_ERROR for a NULL argument, or QAR_STATUS_APP_VOLUME_GESTURE_MODE_UNKNOWN for a mode the volume does not have.

Definition at line 4251 of file qar_streaming.h.

qar_app_volumes_start_editing()

QarResult qar_app_volumes_start_editing (QarSession * session, const QarAppVolumeId * volume_id)

inline static

Request editing lock for the volume.

Definition at line 3698 of file qar_streaming.h.

qar_app_volumes_stop_editing()

QarResult qar_app_volumes_stop_editing (QarSession * session, const QarAppVolumeId * volume_id)

inline static

Release editing lock for the volume.

Definition at line 3702 of file qar_streaming.h.

qar_app_volumes_subscribe_all_gesture_events()

QarResult qar_app_volumes_subscribe_all_gesture_events (QarSession * session, const QarAppVolumeId * volume_id, qar_app_volume_gesture_event_callback_t callback, void * user_state, QarCancelToken * token)

inline static

Subscribe to every gesture kind on one app volume, through one callback.

The unfiltered counterpart of qar_app_volumes_subscribe_gesture_events(): same stream, same handle, no kind filter. It is a separate function rather than a sentinel value in QarGestureKind, because that enum is also what qar_app_volume_gesture_get_classification() returns and a value that is not a kind has no meaning there.

Prefer this when you take more than one kind. Everything arrives on one reader, so gestures a peer performs against the volume keep the order the producer published them in; several per-kind subscriptions are separate readers with no order relative to each other. Dispatch on the kind from qar_app_volume_gesture_get_classification().

Only the volume's mapping rules decide what is published at all - this removes the C API's kind filter, not the volume's QarAppVolumeGestureConfiguration.

Parameters

session	Session owning the volume; must not be NULL.
volume_id	Volume to observe; must not be NULL.
callback	Invoked for every gesture event of every kind; must not be NULL.
user_state	Opaque pointer passed back to callback; may be NULL.
token	Cancel token owning the subscription; must not be NULL. See Ending a subscription.

Returns

QarResult Success once the subscription is running.

Definition at line 3835 of file qar_streaming.h.

qar_app_volumes_subscribe_gesture_events()

QarResult qar_app_volumes_subscribe_gesture_events (QarSession * session, const QarAppVolumeId * volume_id, QarGestureKind gesture_kind, qar_app_volume_gesture_event_callback_t callback, void * user_state, QarCancelToken * token)

inline static

Subscribe to one kind of mapped gesture on a specific app volume.

The gestures a peer performs against the volume are recognised by the peer that renders it and mapped through the volume's QarAppVolumeGestureConfiguration before they arrive here, so what the callback receives is already expressed in the target volume's frame and already filtered by that volume's mapping rules.

Several producers publish here. Recognition happens once per user, so a volume several users can reach carries one publisher per user on this topic. There is no gesture id: a peer runs at most one gesture of a kind against a volume at a time, so the lifecycle key is the source peer and the target volume from qar_app_volume_gesture_get_lifecycle() together with the kind from qar_app_volume_gesture_get_classification(). Ordering holds within one producer's stream, not across producers, which is sufficient because no lifecycle spans two producers. A source peer id never seen before is a new user, not an error, so per-user interaction state is held per peer.

Parameters

session	Session owning the volume; must not be NULL.
volume_id	Volume to observe; must not be NULL.
gesture_kind	The single gesture kind this subscription delivers.
callback	Invoked for every matching gesture event; must not be NULL.
user_state	Opaque pointer passed back to callback; may be NULL.
token	Cancel token owning the subscription; must not be NULL. See Ending a subscription.

Returns

QarResult Success once the subscription is running.

Definition at line 3797 of file qar_streaming.h.

qar_app_volumes_subscribe_updates()

QarResult qar_app_volumes_subscribe_updates (QarSession * session, qar_app_volume_update_callback_t callback, void * user_state, QarCancelToken * token)

inline static

Subscribe to updates for app volumes.

token is required; see Ending asubscription" for when callbacks stop and how long user_state must live.

Definition at line 3763 of file qar_streaming.h.

qar_app_volumes_update_used_by_peers()

QarResult qar_app_volumes_update_used_by_peers (QarSession * session, const QarAppVolumeId * volume_id, const QarPeerId * peer_additions, size_t additions_count, const QarPeerId * peer_removals, size_t removals_count)

inline static

Update which peers use the volume.

Definition at line 3689 of file qar_streaming.h.

qar_query_app_volumes()

QarResult qar_query_app_volumes (QarSession * session, QarAppVolume ** out_handles, size_t handles_buffer_size, size_t * out_handles_written)

inline static

Enumerate app volumes into provided array of handles.

Definition at line 4107 of file qar_streaming.h.

qar_query_app_volumes_count()

QarResult qar_query_app_volumes_count (QarSession * session, size_t * out_count)

inline static

Query number of app volumes known to the session.

Definition at line 4105 of file qar_streaming.h.

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.