GUI Panels
Typedefs Index
| typedef | void(* qar_gui_panel_gesture_event_callback_t)(QarGuiPanelGesture *gesture, void *user_state) |
|
Receives one recognised gesture on a subscribed GUI panel. More... | |
| typedef | void(* qar_gui_panel_update_callback_t)(QarGuiPanel *handle, void *user_state) |
Functions Index
| static QarResult | qar_gui_panel_gesture_get_classification (QarGuiPanelGesture *gesture, QarGuiPanelGestureKind *out_kind, QarGesturePhase *out_phase) |
|
What this gesture is and where in its lifecycle it sits. More... | |
| static QarResult | qar_gui_panel_gesture_get_handedness (QarGuiPanelGesture *gesture, QarHandedness *out_handedness) |
|
Which hand of the producing peer made the contact. More... | |
| static QarResult | qar_gui_panel_gesture_get_lifecycle (QarGuiPanelGesture *gesture, QarPeerId *out_source_peer_id, uint64_t *out_gesture_id) |
|
The lifecycle this gesture belongs to: the peer and the gesture id. More... | |
| static QarResult | qar_gui_panel_gesture_get_panel_id (QarGuiPanelGesture *gesture, QarGuiPanelId *out_panel_id) |
|
The panel this gesture landed on. More... | |
| static QarResult | qar_gui_panel_gesture_get_positions (QarGuiPanelGesture *gesture, QarGuiPanelPoint *out_position, QarGuiPanelPoint *out_start_position) |
|
Where the contact is now, and where its lifecycle began. More... | |
| static QarResult | qar_gui_panel_gesture_get_tap_count (QarGuiPanelGesture *gesture, uint8_t *out_tap_count) |
|
How many taps in this run, for QAR_GUI_PANEL_GESTURE_KIND_TAP. More... | |
| static QarResult | qar_gui_panel_gesture_get_timestamp (QarGuiPanelGesture *gesture, QarTimePoint *out_timestamp) |
|
When the recogniser emitted this gesture, on its own clock. More... | |
| static QarResult | qar_gui_panel_get_content_stream_id (QarGuiPanel *handle, QarStreamId *out_stream_id) |
| static QarResult | qar_gui_panel_get_content_type (QarGuiPanel *handle, QarGuiPanelContentType *out_type) |
| static QarResult | qar_gui_panel_get_content_uri (QarGuiPanel *handle, char *out_uri, size_t buffer_size) |
| static QarResult | qar_gui_panel_get_display_name (QarGuiPanel *handle, char *out_buffer, size_t buffer_size) |
| static QarResult | qar_gui_panel_get_id (QarGuiPanel *handle, QarGuiPanelId *out_id) |
| static QarResult | qar_gui_panel_get_pose (QarGuiPanel *handle, QarPose *out_pose) |
| static QarResult | qar_gui_panel_get_size (QarGuiPanel *handle, QarGuiPanelSize *out_size) |
| static QarResult | qar_gui_panel_get_state (QarGuiPanel *handle, QarGuiPanelState *out_state) |
| static QarResult | qar_gui_panel_get_visible_to_peers (QarGuiPanel *handle, QarPeerId *out_peers, size_t peers_buffer_size, size_t *out_peers_written) |
|
The peers the panel is narrowed to. An empty list means the panel is visible to every peer, not to none. More... | |
| static QarResult | qar_gui_panel_get_visible_to_peers_count (QarGuiPanel *handle, size_t *out_count) |
|
Number of peers in the panel's visible-to list. 0 means the panel is visible to every peer (see qar_gui_panels_update_visible_to()). More... | |
| static void | qar_gui_panel_handle_destroy (QarGuiPanel *handle) |
| static bool | qar_gui_panel_handle_is_valid (QarGuiPanel *handle) |
| static QarResult | qar_gui_panels_change_size (QarSession *session, const QarGuiPanelId *id, const QarGuiPanelSize *size) |
|
Change panel size and content scale. More... | |
| static QarResult | qar_gui_panels_close_panel (QarSession *session, const QarGuiPanelId *id) |
|
Close and remove a panel. More... | |
| static QarResult | qar_gui_panels_get_or_create (QarSession *session, const QarGuiPanelInit *init, QarGuiPanelId *out_panel_id) |
|
Get the panel identified by init->common_name, creating it (via init) if it does not exist yet. QarGuiPanelInit supports QarGuiPanelUrlExt for browser content and QarGuiPanelStreamIdExt for logical-stream content. Chain exactly one through QarGuiPanelInit::header.next. With neither extension, the panel starts with the default website content. Stream receiver resolution is taken from the session-owned sender identified by QarGuiPanelStreamIdExt::stream_id. More... | |
| static QarResult | qar_gui_panels_navigate_to_uri (QarSession *session, const QarGuiPanelId *id, const char *uri) |
|
Navigate an existing website panel to a URI. More... | |
| static QarResult | qar_gui_panels_set_state (QarSession *session, const QarGuiPanelId *id, QarGuiPanelState state) |
| static QarResult | qar_gui_panels_set_stream (QarSession *session, const QarGuiPanelId *id, const QarStreamId *stream_id) |
| static QarResult | qar_gui_panels_subscribe_all_gesture_events (QarSession *session, const QarGuiPanelId *id, qar_gui_panel_gesture_event_callback_t callback, void *user_state, QarCancelToken *token) |
|
Subscribe to every gesture kind on one panel, through one callback. More... | |
| static QarResult | qar_gui_panels_subscribe_gesture_events (QarSession *session, const QarGuiPanelId *id, QarGuiPanelGestureKind gesture_kind, qar_gui_panel_gesture_event_callback_t callback, void *user_state, QarCancelToken *token) |
|
Subscribe to the gestures the rendering peers report for one panel. More... | |
| static QarResult | qar_gui_panels_subscribe_panel_updates (QarSession *session, const QarGuiPanelId *id, qar_gui_panel_update_callback_t callback, void *user_state, QarCancelToken *token) |
|
Subscribe to updates for a specific panel. More... | |
| static QarResult | qar_gui_panels_subscribe_updates (QarSession *session, qar_gui_panel_update_callback_t callback, void *user_state, QarCancelToken *token) |
|
Subscribe to updates for all panels. More... | |
| static QarResult | qar_gui_panels_update_pose (QarSession *session, const QarGuiPanelId *id, const QarPose *pose) |
|
Update the pose of a panel. More... | |
| static QarResult | qar_gui_panels_update_visible_to (QarSession *session, const QarGuiPanelId *id, const QarPeerId **peer_ids_additions, size_t additions_count, const QarPeerId **peer_ids_removals, size_t removals_count) |
|
Update which peers can see the panel. More... | |
| static QarResult | qar_query_gui_panels (QarSession *session, QarGuiPanel **out_handles, size_t handles_buffer_size, size_t *out_handles_written) |
| static QarResult | qar_query_gui_panels_count (QarSession *session, size_t *out_count) |
Typedefs
qar_gui_panel_gesture_event_callback_t
|
Receives one recognised gesture on a subscribed GUI panel.
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_gui_panel_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 contact's depth off the glass, a pressure, a viewport rect - by appending an accessor, which is an additive change, instead of growing a struct, which would break every compiled consumer.
Definition at line 3375 of file qar_streaming.h.
qar_gui_panel_update_callback_t
|
Definition at line 3331 of file qar_streaming.h.
Functions
qar_gui_panel_gesture_get_classification()
| 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 hover, tap, long press or drag; must not be NULL.
out_phase Receives started, updated, ended, canceled or instant; must not be NULL.
Definition at line 3514 of file qar_streaming.h.
qar_gui_panel_gesture_get_handedness()
| inline static |
Which hand of the producing peer made the contact.
Diagnostic: only one hand of a peer is active at a time, so a consumer does not need this to arbitrate.
- Parameters
-
gesture Gesture handed to the callback; must not be NULL.
out_handedness Receives QAR_HANDEDNESS_LEFT or QAR_HANDEDNESS_RIGHT; must not be NULL.
- Returns
QAR_STATUS_SUCCESS, or QAR_STATUS_LOGIC_ERROR for a NULL argument.
Definition at line 3576 of file qar_streaming.h.
qar_gui_panel_gesture_get_lifecycle()
| inline static |
The lifecycle this gesture belongs to: the peer and the gesture id.
They are returned together because they are one key. The gesture id is unique only within out_source_peer_id, so a consumer that stores lifecycles must key on the pair. The id is non-zero and stable for one hover or drag lifecycle, and 0 for tap and long press, which are instant.
The peer is the one whose hand 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.
- Parameters
-
gesture Gesture handed to the callback; must not be NULL.
out_source_peer_id Receives the producing peer; must not be NULL.
out_gesture_id Receives the lifecycle id; must not be NULL.
Definition at line 3495 of file qar_streaming.h.
qar_gui_panel_gesture_get_panel_id()
| inline static |
The panel this gesture landed on.
Always the panel the subscription named, so a callback serving one panel can skip this and read it from its user_state instead.
Definition at line 3550 of file qar_streaming.h.
qar_gui_panel_gesture_get_positions()
| inline static |
Where the contact is now, and where its lifecycle began.
Returned together because they are read together: a drag's travel is out_position minus out_start_position, and a frame-to-frame delta is the difference against the previous event of the same lifecycle. For instant kinds - tap and long press - the two are equal.
Both are in panel-content-space pixels; see QarGuiPanelPoint. A contact outside the letterboxed content rectangle cannot start a lifecycle, but a live one follows the clamped pixel to the edge and stays there, so a drag that overshoots commits its end value.
- Parameters
-
gesture Gesture handed to the callback; must not be NULL.
out_position Receives the current contact position; must not be NULL.
out_start_position Receives where this lifecycle began; must not be NULL.
Definition at line 3538 of file qar_streaming.h.
qar_gui_panel_gesture_get_tap_count()
| inline static |
How many taps in this run, for QAR_GUI_PANEL_GESTURE_KIND_TAP.
1, 2, 3 ... for taps close enough together in time and space. 0 for every other kind.
Definition at line 3586 of file qar_streaming.h.
qar_gui_panel_gesture_get_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 3561 of file qar_streaming.h.
qar_gui_panel_get_content_stream_id()
| inline static |
Definition at line 3625 of file qar_streaming.h.
qar_gui_panel_get_content_type()
| inline static |
Definition at line 3621 of file qar_streaming.h.
qar_gui_panel_get_content_uri()
| inline static |
Definition at line 3617 of file qar_streaming.h.
qar_gui_panel_get_display_name()
| inline static |
Definition at line 3607 of file qar_streaming.h.
qar_gui_panel_get_id()
| inline static |
Definition at line 3605 of file qar_streaming.h.
qar_gui_panel_get_pose()
| inline static |
Definition at line 3612 of file qar_streaming.h.
qar_gui_panel_get_size()
| inline static |
Definition at line 3615 of file qar_streaming.h.
qar_gui_panel_get_state()
| inline static |
Definition at line 3630 of file qar_streaming.h.
qar_gui_panel_get_visible_to_peers()
| inline static |
The peers the panel is narrowed to. An empty list means the panel is visible to every peer, not to none.
Definition at line 3644 of file qar_streaming.h.
qar_gui_panel_get_visible_to_peers_count()
| inline static |
Number of peers in the panel's visible-to list. 0 means the panel is visible to every peer (see qar_gui_panels_update_visible_to()).
Definition at line 3636 of file qar_streaming.h.
qar_gui_panel_handle_destroy()
| inline static |
Definition at line 3602 of file qar_streaming.h.
qar_gui_panel_handle_is_valid()
| inline static |
Definition at line 3600 of file qar_streaming.h.
qar_gui_panels_change_size()
| inline static |
Change panel size and content scale.
Definition at line 3274 of file qar_streaming.h.
qar_gui_panels_close_panel()
| inline static |
Close and remove a panel.
Definition at line 3284 of file qar_streaming.h.
qar_gui_panels_get_or_create()
| inline static |
Get the panel identified by init->common_name, creating it (via init) if it does not exist yet. QarGuiPanelInit supports QarGuiPanelUrlExt for browser content and QarGuiPanelStreamIdExt for logical-stream content. Chain exactly one through QarGuiPanelInit::header.next. With neither extension, the panel starts with the default website content. Stream receiver resolution is taken from the session-owned sender identified by QarGuiPanelStreamIdExt::stream_id.
Definition at line 3262 of file qar_streaming.h.
qar_gui_panels_navigate_to_uri()
| inline static |
Navigate an existing website panel to a URI.
Stream panels return QAR_STATUS_GUI_PANEL_CHANGE_NOT_PERMITTED because a panel's content type is fixed at creation.
Definition at line 3292 of file qar_streaming.h.
qar_gui_panels_set_state()
| inline static |
Definition at line 3278 of file qar_streaming.h.
qar_gui_panels_set_stream()
| inline static |
Replace an existing stream panel's StreamId. The ID must identify a video sender owned by this session; its current layout determines receiver resolution. Website panels return QAR_STATUS_GUI_PANEL_CHANGE_NOT_PERMITTED.
Definition at line 3301 of file qar_streaming.h.
qar_gui_panels_subscribe_all_gesture_events()
| inline static |
Subscribe to every gesture kind on one panel, through one callback.
The unfiltered counterpart of qar_gui_panels_subscribe_gesture_events(): same stream, same handle, no kind filter. It is a separate function rather than a sentinel value in QarGuiPanelGestureKind, because that enum is also what qar_gui_panel_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 a hover and the drag that grows out of the same contact keep the order the producer published them in. Several per-kind subscriptions are separate readers and have no order relative to each other. Dispatch on the kind from qar_gui_panel_gesture_get_classification().
- Parameters
-
session Session owning the panel; must not be NULL.
id Panel to observe; must not be NULL, and the default all-zero id is rejected with QAR_STATUS_GUI_PANEL_INVALID_ID.
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 ending the subscription, or NULL to keep it alive until the session is destroyed. See Ending a subscription.
- Returns
QarResult Success once the subscription is running.
Definition at line 3471 of file qar_streaming.h.
qar_gui_panels_subscribe_gesture_events()
| inline static |
Subscribe to the gestures the rendering peers report for one panel.
Panel input is one stream of gestures: hover, tap, long press and drag, each carrying the QarGesturePhase lifecycle and a gesture id that pairs a started phase with its updates and its end. The peer that draws the panel recognises them from its user's hand joints - the thresholds are physical, in millimetres of hand travel against tracking jitter, which a consumer seeing only content pixels cannot reproduce. The consumer decides for itself whether a drag is a slider or a scroll.
One subscription delivers one kind, the same way qar_app_volumes_subscribe_gesture_events() does. A consumer that wants several kinds subscribes several times. Every kind still travels on the one panel topic and the filtering happens on the receiving side, so a subscription never misses an event of its kind; what it does not get is an order guarantee between its subscriptions. Where that matters - a hover and a drag from the same contact - take both kinds on one subscription's worth of state and reconcile them on the gesture id, which is shared across kinds within a source peer.
Several producers publish here. Recognition happens once per user, in the mixer that serves that user, so a panel several users can see carries one publisher per user on this single topic. Therefore:
- The gesture id is unique only within a source peer id. Key lifecycles on the pair that qar_gui_panel_gesture_get_lifecycle() returns together: two users' first drags both carry gesture id 1. A consumer that keys on the gesture id alone works perfectly until a second user joins.
- Ordering holds within one producer's stream, not across producers. That is sufficient, because no lifecycle spans two producers.
- A source peer id never seen before is a new user, not an error, and per-user interaction state - a slider's value while it is being dragged - is held per peer so two users do not fight over one.
- A live lifecycle is republished every 250 ms even when nothing changed. Treat one silent for three of those intervals as cancelled. That, and not the peer list, is what recovers a producer that crashed: the source peer id is the headset, while the process that can die is the mixer, which the event does not name.
- A started phase that was never seen is recoverable, because every update carries its start position.
Every panel reports gestures, QAR_GUI_PANEL_CONTENT_TYPE_WEBSITE_URI panels included: nothing branches on content type on the publish path.
- Parameters
-
session Session owning the panel; must not be NULL.
id Panel to observe; must not be NULL, and the default all-zero id is rejected with QAR_STATUS_GUI_PANEL_INVALID_ID.
gesture_kind The single gesture kind this subscription delivers; subscribe again for another kind.
callback Invoked for every gesture event of that kind; must not be NULL.
user_state Opaque pointer passed back to callback; may be NULL.
token Cancel token ending the subscription, or NULL to keep it alive until the session is destroyed. See Ending a subscription.
- Returns
QarResult Success once the subscription is running.
Definition at line 3436 of file qar_streaming.h.
qar_gui_panels_subscribe_panel_updates()
| inline static |
Subscribe to updates for a specific panel.
token is required; see Ending asubscription" for when callbacks stop and how long user_state must live.
Definition at line 3352 of file qar_streaming.h.
qar_gui_panels_subscribe_updates()
| inline static |
Subscribe to updates for all panels.
token is required; see Ending asubscription" for when callbacks stop and how long user_state must live.
Definition at line 3340 of file qar_streaming.h.
qar_gui_panels_update_pose()
| inline static |
Update the pose of a panel.
Definition at line 3269 of file qar_streaming.h.
qar_gui_panels_update_visible_to()
| inline static |
Update which peers can see the panel.
The visible-to list narrows who sees the panel. An empty list means the panel is visible to every peer: a new panel starts empty, and removing the last peer from the list makes the panel visible to everyone again, never to no one. To hide a panel from everyone, change its state instead.
- Parameters
-
session Session that owns the panel.
id Panel to change.
peer_ids_additions Peers to add; may be NULL when additions_count is 0.
additions_count Number of entries in peer_ids_additions.
peer_ids_removals Peers to remove; may be NULL when removals_count is 0.
removals_count Number of entries in peer_ids_removals.
- Returns
Success, or the panel error (e.g. QAR_STATUS_GUI_PANEL_INVALID_ID).
Definition at line 3323 of file qar_streaming.h.
qar_query_gui_panels()
| inline static |
Definition at line 3593 of file qar_streaming.h.
qar_query_gui_panels_count()
| inline static |
Definition at line 3591 of file qar_streaming.h.
Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.