QAR Streaming C# API

Quaternar.Qaros is the .NET binding of the QAROS streaming C API. It targets netstandard2.0, netstandard2.1 and net8.0, loads the same native qar-streaming-c library, and is the C# surface Unity uses too.

• Quaternar.Qaros (this reference) is the managed API: IDisposable handles, Result<T> return values, C# events and ...Async variants. Every public type is listed below.
• Quaternar.Qaros.Mathematics holds Vector3, Vector3d, Quaternion and Pose, apart from the main namespace so they do not clash with the UnityEngine or System.Numerics types of the same names. Add using Quaternar.Qaros.Mathematics; where you use them.
• Quaternar.Qaros.Interop is the internal P/Invoke layer the managed API is built on. It is not part of the public surface and is not documented here.

Concepts, threading rules and usage snippets live in the Developer Guide, next to the C examples.

Entry points

1. Library.Init loads the native library, once per process.
2. Runtime.Create creates the runtime. Its Onboard joins a session for the first time and returns an OnboardSession; Rejoin returns to a session joined before.
3. A Session exposes one control per area: Peers, GuiPanels, AppVolumes, RenderSenders and PrimarylessVideoSenders.
4. Calls return a Result<T>: check IsSuccess, or use ValueOrThrow(). Failures carry a StatusCode.

Library and runtime

Load the native library and create the runtime that onboards and rejoins sessions.

Type	Kind	Description
Library	class	Process-wide library state. Library.Init comes first, before any other call of this API; then Runtime.Create, then Runtime.Onboard or Runtime.Rejoin for a Session.
LibraryOptions	class	Arguments of Library.Init, which must run once per process before any other call. The defaults match qar_library_init_default().
LogSeverity	enum	Minimum severity the library logs; see LibraryOptions.LogSeverity.
Runtime	class	Hosts the identity slots a process onboards with and produces its sessions. Create it after Library.Init; every Session comes from Runtime.Onboard or Runtime.Rejoin on it.
RuntimeOptions	class	Arguments of Runtime.Create.
Structure	class	Base of the extension structures chained onto an options object with its WithExtension method. The options are copied into native memory for the duration of the call that takes them.
StructureType	enum	Native structure type tag of a Structure. Each extension class sets its own in its constructor.

Onboarding and sessions

Join a QAROS session for the first time, rejoin it later, invite devices and start target apps.

Type	Kind	Description
ActionProgress	struct
ActionSeverity	enum
ForgetOptions	class
GpuDeviceIdType	enum	How GraphicsDeviceId names the adapter.
GraphicsDeviceId	class	Extension: selects the graphics adapter the session's Vulkan and D3D11 devices, and with them every render sender's frame textures, are created on. Chain on OnboardOptions or RejoinOptions; absent, the library picks one. Windows accepts a LUID, other platforms a UUID. The C API currently supports NVIDIA adapters only.
OnboardCode	class	Onboarding mode extension behind OnboardOptions.UseCode; prefer that method.
OnboardHost	class	The hub to code-onboard against, behind OnboardOptions.WithHost; prefer that method.
OnboardingId	struct	The key of an identity slot, minted by the first Runtime.Onboard. It is the one thing an application persists: hand it back to Runtime.Rejoin on every start and to Runtime.Forget to unpair.
OnboardingInvite	class	A one-time onboarding invite minted by the hub: everything another instance needs to onboard with OnboardOptions.UseInvite, or a code to hand out by OnboardingInvite.GetCode.
OnboardingMethod	enum	Which onboarding path an onboarding invite carries. More may be added, so do not treat "not OnboardingMethod.Pake" as OnboardingMethod.Password.
OnboardInvite	class	Onboarding mode extension behind OnboardOptions.UseInvite; prefer that method. The invite is borrowed, not owned.
OnboardOptions	class	Options of Runtime.Onboard. Choose exactly one mode: OnboardOptions.UseCode or OnboardOptions.UseInvite; the last call wins.
OnboardPeerId	class	Extension: join the session under a caller-chosen peer id instead of a freshly minted one. Chain on OnboardOptions with OnboardOptions.WithPeerId. The id is persisted with the slot, so a later rejoin keeps it. A zero id is rejected with StatusCode.ArgumentNotSupported.
OnboardSession	struct	What Runtime.Onboard produces. Persist OnboardSession.OnboardingId before anything else; the caller owns and disposes OnboardSession.Session.
RejoinOptions	class	Options of Runtime.Rejoin.
RequestOnboardingCodesOptions	class	A request for a new set of one-time onboarding codes. Every request gets codes of its own; codes other callers hold and the hub's onboarding screen code stay valid.
RequestOnboardingInviteOptions	class
Session	class	An active session, the entry point to peers, GUI panels, app volumes and senders. Only Runtime.Onboard and Runtime.Rejoin produce one, and there is no getter for a "current" session: keep the instance.
SessionId	struct	A session's 16-byte UUID. Compared by content; default(SessionId) equals SessionId.Default.
TargetAppConnectionString	class	Builds the connection strings Session.InviteTargetApp accepts. A host is a hostname or an IP address; it must not be empty.

Peers and hands

The peers in a session, their presentation and the hand-tracking data devices send.

Type	Kind	Description
AppState	enum	A peer's lifecycle state. A target app is ready to be rendered for only while it is AppState.Running.
DeviceHandsWithJoints	struct	The newest hands sample a device sent. From RenderSender.GetLastHands every pose, radius and velocity in it is in the bound app volume's app content space (right-handed, +Y up, -Z forward, app units), like the view poses.
Handedness	enum	Left or right: which hand made a gesture, and the handedness of the axes of a GeoAnchorFrame.
HandJoint	enum	XR_EXT_hand_tracking joint indices; HandJointLocation.JointId carries one.
HandJointLocation	struct	One XR_EXT_hand_tracking joint.
HandJointLocationFlags	enum	Bits of HandJointLocation.LocationFlags and HandJointVelocity.Flags.
HandJoints	struct	One hand's tracking state: 26 joint locations and velocities indexed by HandJoint.
HandJointVelocity	struct	Velocity of one joint.
PeerControl	class	The peers of a session: every participant, devices and applications alike, this process included. Reached through Session.Peers.
PeerId	struct	A peer's 16-byte UUID. Compared by content; default(PeerId) equals PeerId.Default.
PeerPresentationOptions	class	How this peer presents itself to the others. Never a storage key. A property left null keeps its persisted value, or gets a generated default on the first onboard.
PeerSpec	class	An immutable snapshot of one peer, taken when it was read or delivered; safe to keep. It does not change: read a new one, or watch PeerControl.SubscribeUpdates.
PeerSpecUpdatedEventArgs	class	One peer update; PeerSpecUpdatedEventArgs.Peer is a snapshot, safe to keep.

App volumes

The 3D volumes an application renders into, their gestures and world anchoring.

Type	Kind	Description
AppScaleSensitivityMode	enum
AppVolume	class	An immutable snapshot of one app volume: the box in the room a remote 3D application renders into, and how the application's content sits inside it.
AppVolumeAxisFlags	enum	Bitmask of the axes a mapping rule lets a gesture translate along or rotate about; see AppVolumeGestureMappingRule.TranslationAxes and AppVolumeGestureMappingRule.RotationAxes.
AppVolumeControl	class	The session's app volumes: the boxes in the room that remote 3D applications render into. Reached through Session.AppVolumes.
AppVolumeControllerRayLineStyle	enum
AppVolumeControllerRayStyle	struct	How the hand ray is drawn for gestures a mapping rule matches. The colour is RGBA, 0 to 255 per channel; AppVolumeControllerRayStyle.Default is a solid opaque white line.
AppVolumeEditingStatus	struct	Whether a peer holds the volume's editing lock (AppVolumeControl.StartEditing) to move or resize the box itself. A peer manipulating the app with a gesture is not editing it.
AppVolumeGestureConfiguration	class	A gesture mode's mapping rules, in descending priority order, plus the peers whose gestures may move or scale the app.
AppVolumeGestureEvent	struct	One mapped gesture on an app volume, copied out of the native callback.
AppVolumeGestureEventArgs	class
AppVolumeGestureMappingRule	class	How one gesture kind on an app volume is shaped and what it is applied to. Its priority is its position in AppVolumeGestureConfiguration.MappingRules, not a field.
AppVolumeGestureState	class	An app volume's gesture modes and who is using them, read with the volume snapshot.
AppVolumeId	struct	An app volume's 16-byte UUID, derived from the volume's common name by AppVolumeControl.GetOrCreate. Compared by content; default(AppVolumeId) equals AppVolumeId.Default.
AppVolumeLifetimeStatus	enum
AppVolumeOptions	class	Arguments of AppVolumeControl.GetOrCreate. The defaults match qar_app_volume_init_default(): identity poses, a 1 m cube, app scale 1, no world anchor and the default gesture configuration.
AppVolumeSize	struct	An app volume cuboid's extents in metres, centred on the volume's pose: it spans plus and minus half of each extent along app volume space X, Y and Z. Note the constructor order: width (X), length (Z), height (Y).
AppVolumeUpdatedEventArgs	class	One app volume update; AppVolumeUpdatedEventArgs.Volume is a snapshot, safe to keep.
AppWorldAnchor	struct	An app volume's world anchor, if it has one.
GeoAnchorFrame	struct	A local frame fully defined in world coordinates: its origin and unit axes in GeoAnchorFrame.WorldReferenceSystem (ECEF WGS84, metres, double precision), plus the handedness of those axes. Pins an app volume to the Earth.
GestureAppTransformMapping	enum	What the library applies a mapped gesture to by itself. Either way the gesture still reaches the volume's gesture subscribers; AppVolumeGestureEvent.WasMappedToAppTransform tells whether it was already applied.
GestureKind	enum	What a hand interaction with an app volume was recognised as.
GesturePhase	enum
WorldReferenceSystem	enum

GUI panels

Flat 2D panels placed in the room and the gestures users make on them.

Type	Kind	Description
GuiPanel	class	An immutable snapshot of one GUI panel, safe to keep. Get a newer one from GuiPanelControl.SubscribeUpdates.
GuiPanelContentType	enum	What a GUI panel shows. Fixed at creation: GuiPanelControl.NavigateToUri on a stream panel fails with StatusCode.GuiPanelChangeNotPermitted.
GuiPanelControl	class	The session's GUI panels: shared 2D surfaces in the room showing a web page or a video stream. Reached through Session.GuiPanels.
GuiPanelGestureEvent	struct	One recognised gesture on a GUI panel, copied out of the native callback.
GuiPanelGestureEventArgs	class
GuiPanelGestureKind	enum	What a contact on a GUI panel was recognised as.
GuiPanelId	struct	A GUI panel's 16-byte UUID, derived from the panel's common name by GuiPanelControl.GetOrCreate. Compared by content; default(GuiPanelId) equals GuiPanelId.Default.
GuiPanelOptions	class	Arguments of GuiPanelControl.GetOrCreate.
GuiPanelPoint	struct	A position on a GUI panel in panel-content-space pixels: origin top-left as the viewer sees it, +X right, +Y down.
GuiPanelSize	struct	A GUI panel's surface size in metres and the zoom of the content drawn on it. The surface spans panel-space X from -Width/2 to +Width/2 and hangs down from the pose to -Height.
GuiPanelState	enum
GuiPanelUpdatedEventArgs	class	One GUI panel update; GuiPanelUpdatedEventArgs.Panel is a snapshot, safe to keep.

Rendering

Render senders stream frames for a target peer: frame begin/show, views, stream parameters per graphics API.

Type	Kind	Description
DXGIKeyedMutexSync	struct	The keyed mutex of one shared D3D11 texture and the keys for its AcquireSync and ReleaseSync. Needed only when StreamParamsD3D11.AcquireKeyedMutexSync is false and the application drives the key chain itself.
Fov	struct	Field of view of one render view, in view space: angles in radians from the view's -Z axis, with OpenXR signs - left and down negative, right and up positive.
FrameLayout	enum	How the views of one video frame are packed into textures.
GraphicsAPI	enum	The graphics backend a sender's frame textures live on. Every GPU value requires exactly the matching stream-parameter extension on the options; GraphicsAPI.Cpu takes none.
ImageSize	struct	An image size in pixels.
NearFar	struct	Near and far clip distances along a view's -Z, in the units of the poses the view was rendered with: app units for a render sender. A near plane greater than the far plane declares reverse-Z.
OpenGlContextCallbacks	struct	Raw C function pointers overriding how the library binds an OpenGL context; see QarOpenGlContextCallbacks in types.h. Every one is optional and called on the library's internal graphics thread; zero uses the library's own platform implementation for that step.
PixelFormat	enum
RenderFrameInfo	class	Per-frame information from a successful begin-frame. Everything it hands out is in the bound app volume's app content space.
RenderFrameShow	class	Arguments of RenderSender.ShowFrame: the projection metadata the frame was rendered with. The defaults match qar_render_frame_show_default(): near 0.1, far 100, depth scale 1.
RenderFrameShowViewOverrides	class	Extension of RenderFrameShow: the pose or field of view a view was really rendered with, when it differs from what RenderSender.BeginFrame handed out. RenderFrameShow.WithViewOverrides chains one.
RenderFrameView	struct	One view declared in RenderSenderOptions.FrameViews.
RenderFrameViewOverride	struct	The pose and/or field of view one view was really rendered with, when it deviates from what RenderSender.BeginFrame handed out. Only the parts whose flag is set are used.
RenderSender	class	Streams the application's rendered frames to one target peer, displayed in the bound app volume. Create one per target with RenderSenderControl.Create.
RenderSenderControl	class	Creates render senders and delivers render stream requests for a session; reached through Session.RenderSenders.
RenderSenderOptions	class	Arguments of a render sender: one stream rendered for one target peer, displayed in one app volume. The defaults match qar_render_sender_init_default().
RenderStreamRequest	struct
RenderStreamRequestEventArgs	class
StreamId	struct	A logical video stream's 16-byte UUID, generated by the library for each PrimarylessVideoSender (PrimarylessVideoSender.GetStreamId). Compared by content; default(StreamId) equals StreamId.Default.
StreamParamsD3D11	class	Extension: adopt the application's D3D11.1 device, so the sender's frame textures are shared D3D11 textures it renders into directly, with no CPU copy. Windows only.
StreamParamsOpenGl	class	Base of the three OpenGL stream-parameter extensions. Pick the one matching the context the application owns; requires a library built with QAR_ENABLE_OPENGL.
StreamParamsOpenGlEgl	class	Extension: adopt an existing EGL context.
StreamParamsOpenGlGlx	class	Extension: adopt an existing GLX context.
StreamParamsOpenGlWgl	class	Extension: adopt an existing WGL context.
StreamParamsVulkan	class	Extension: adopt an existing Vulkan device. Requires a library built with QAR_ENABLE_VULKAN.
SyncFrameD3D11	struct
TextureSize	struct	One texture of a frame layout; width and height in pixels.

Video senders and frames

Video streams without a primary render target, and the frame and texture types every sender hands out.

Type	Kind	Description
PrimarylessVideoSender	class	Application-owned video stream, such as GUI panel content, that exists before any receiver connects and is delivered to every receiver that requests its stream id.
PrimarylessVideoSenderControl	class	Creates PrimarylessVideoSenders for a session; reached through Session.PrimarylessVideoSenders.
PrimarylessVideoSenderOptions	class	Arguments of PrimarylessVideoSender: application-owned video, such as GUI panel content, under a library-generated StreamId. Unlike a render sender it answers no receiver request and may exist before any receiver connects.
VideoFrameCpu	struct	A snapshot of a sender's CPU frame: its views and textures, in layout order. The pixel memory stays the sender's.
VideoFrameD3D11	struct	A snapshot of a sender's D3D11 frame: its views, its shared textures and their keyed-mutex synchronization. The textures stay the sender's; render into them only inside a frame cycle. A render sender's frame is readable from creation, before the first begin-frame.
VideoFrameLayout	class	The views of a video frame and the textures backing them.
VideoFrameOpenGl	struct	A snapshot of a sender's OpenGL frame: its views and textures. The textures stay the sender's; render into them only inside a frame cycle. A render sender's frame is readable from creation, before the first begin-frame.
VideoFrameView	struct	Where one view of a video frame lives: a pixel rectangle in one texture (and array layer). The end coordinates are exclusive and may be smaller than the start ones, which flips the view.
VideoFrameViewEye	enum
VideoFrameViewType	enum
VideoFrameVulkan	class	Access to a sender-owned Vulkan frame. The library owns the native frame; this object is valid until the next GetVulkanFrame call on the same sender or the sender's disposal. Before showing a frame, write the layouts and queue families the images were left in and the synchronization objects with VideoFrameVulkan.SetTextureState and VideoFrameVulkan.SetSynchronization.
VideoTextureCpu	struct	One sender-owned CPU texture. The pixel memory is not copied: VideoTextureCpu.TextureData points into the sender.
VideoTextureD3D11	struct
VideoTextureOpenGl	struct
VideoTextureVulkan	struct	One sender-owned Vulkan image and the state it is in.

Results and errors

Every call returns a Result<T> instead of throwing; these types carry the outcome.

Type	Kind	Description
NativeCallException	class	A native failure turned into an exception on request, by Result<T>.ValueOrThrow or EnsureSuccess. NativeCallException.Result carries the status code.
Result<T>	struct	A value or a failure. A native failure is returned, never thrown: check Result<T>.IsSuccess, or opt into an exception with Result<T>.ValueOrThrow or Result<T>.EnsureSuccess.
ResultInfo	struct	The outcome of a native call: a ResultInfo.StatusCode and a diagnostic message.
StatusCode	enum	Status codes the C API exposes (QarStatusCode), with the same values. Any internal code outside this set reaches callers as StatusCode.Unclassified.
Unit	struct	The value of a Result<T> whose operation returns nothing.

Math and time

Value types shared by every area.

Type	Kind	Description
Pose	struct	Position plus orientation (x, y, z, w). A pose carries no space of its own: every member that holds one names the space it is in. The bindings convert no coordinates; each value is exactly what the native library produced.
Quaternion	struct	Rotation quaternion, Hamilton convention, stored and constructed in x, y, z, w order (w last). default(Quaternion) is all zeros, not a rotation; use Quaternion.Identity.
TimePoint	struct	Wall-clock instant: nanoseconds since the Unix epoch (UTC). Instants stamped on different hosts are only as comparable as those hosts' clocks are synchronized. Converts to a UTC DateTime implicitly or with TimePoint.ToDateTime, truncated to its 100 ns tick.
Vector3	struct	A 3D vector. It carries no space of its own; the member holding it names the space (see Pose).
Vector3d	struct	Double-precision 3D vector, used for Earth-fixed world coordinates in GeoAnchorFrame.