Interface control document

1. Identification

This document is the contract required by audit findings VARJO-01 and VBRIDGE-01: before it, neither the managed module nor the bridge had an ICD specifying exports, buffer ownership, lifecycle, framing or error behaviour. The bridge has no ICD of its own by design; it is documented here, through the module that owns and ships it.

2. Scope

The product spans two repositories and one process. The managed module is loaded by HEAT Capture, P/Invokes into a native bridge DLL that is vendored inside the module package, and the bridge holds the Varjo session, drives the compositor frame loop, reads gaze, encodes per-eye video and serializes complete SimulationFrame messages. The managed module reparses those bytes and hands them to the Module SDK.

This document defines the managed-to-native ABI, the framing and ownership rules of the frame handoff, the lifecycle across both sides, the published data, timing, and error behaviour on both sides. It does not define the Varjo SDK itself; the authority for Varjo semantics is Varjo’s own documentation, and the SDK headers vendored in the bridge repository under varjo-sdk/include/.

3. Interface inventory

4. IF-CMVARJO-01 Bridge control ABI

4.1 Exports

The bridge exports exactly five functions, declared extern "C" with __declspec(dllexport) and no explicit calling-convention specifier (VarjoGazeBridge.h:6-12). There is one integer calling convention on Windows x64, and the managed side declares CallingConvention.Cdecl (VarjoInterop.cs:17-30).

The DLL is loaded by plain module name, VarjoGazeBridge.dll (VarjoInterop.cs:15), so the default Windows loader search applies. There is no export that reports a bridge version, build identity or ABI revision, and no handshake of any kind. See section 12.

outputWidth and outputHeight are accepted and ignored. The bridge derives its encode resolution from the Varjo view description instead (VarjoGazeBridge.cpp:696-697, :110-114, :184-193), and the managed side passes 0, 0 deliberately (VarjoGazeDataModule.cs:38-45).

4.2 Return values

The GetGazeTrackingStatus codes are the bridge’s own numbering, not Varjo’s; they are derived from four Varjo session properties in that fixed precedence order. The managed module logs the same mapping verbatim at session start (VarjoGazeDataModule.cs:54-55).

4.3 Buffer ownership

No bridge-allocated memory ever crosses the boundary, and there is no free or release function to call. Ownership is one-directional and total.

4.4 Thread affinity

Video setup, encoder activation, submit, drain and teardown all happen on the bridge’s capture thread, which establishes an MTA apartment for itself because hardware H.264 encoder MFTs fail to activate from an STA thread (VarjoGazeBridge.cpp:250-259, :96-101, :235-248). That is why Initialize defers video setup rather than doing it inline: its caller is a GUI thread.

The two session-touching queries in the last row are issued from the Module SDK’s threads while the capture thread is inside the Varjo frame loop. The Varjo SDK headers vendored in this revision state no thread-safety contract for a session handle, so this document cannot assert that the concurrent use is safe. It is recorded here as a property of the audited revision.

4.5 Enumeration mapping

CalibrationType is passed by value as a 32-bit enum. The two sides do not declare the same set.

None is a managed-only sentinel: the module skips the call entirely rather than passing 2 across the boundary (VarjoGazeDataModule.cs:56-61). A caller that did pass 2 would land on the native default: branch and get FAST (GazeTracking.cpp:36-42), silently. Treat None as “do not call this export”, not as a value the ABI accepts.

4.6 Authentication

None, on either interface. The ABI is an in-process function call. Any code in the HEAT Capture process can call the same exports, and the bridge accepts whichever Varjo session the local runtime hands it. Video capture requires a Varjo Pro licence, but neither side checks for one in code; enforcement, if any, is inside Varjo’s runtime.

5. IF-CMVARJO-02 Serialized frame handoff

5.1 Framing

There is no envelope, length prefix, sequence number or delimiter. A single GetFrame call delivers exactly one complete, self-delimiting serialized SimulationFrame message, and its return value is that message’s length. The unit of transfer is one message, so the managed side never has to reassemble or scan for a boundary.

The bytes are produced natively by the HEAT ProtoLib C API through HEAT::Proto::Builders::SimulationFrameBuilder::serialize (VarjoGazeBridge.cpp:326-331, :661-667) and reparsed by SimulationFrame.Parser.ParseFrom on the managed side (VarjoGazeDataModule.cs:95). Both sides must therefore be built against compatible ProtoLib schemas; see section 12.

5.2 Queue semantics

Overflow is a data-loss event with a visible consequence: the discarded entry may be a gaze frame or a video access unit, and the forced keyframe means the affected eye’s video shows a discontinuity rather than a delay.

5.3 Undersized buffer

If the oldest queued frame is larger than the buffer the caller supplied, popInto returns 0 and leaves that frame at the head of the queue (FrameQueue.cpp:26-28). The return value is therefore ambiguous by construction: 0 means either “queue empty” or “head entry does not fit”, and the caller cannot tell which.

The managed drain loop treats any non-positive return as end-of-queue and stops (VarjoGazeDataModule.cs:92). An oversized head entry consequently blocks the queue permanently for the rest of the session: nothing behind it can ever be delivered, no diagnostic is emitted on either side, and the module’s own parse-error counter does not move. The 4 MiB managed buffer is sized against an IDR access unit at the bridge’s ~8 Mbit/s per-eye CBR budget (VarjoGazeDataModule.cs:24-28, VarjoGazeBridge.cpp:51-53), so the condition is not expected in normal operation, but nothing in either side enforces the bound or detects it being exceeded.

5.4 Drain contract

The managed module drains the whole queue on every capture cycle rather than taking one frame per cycle (VarjoGazeDataModule.cs:78-118). Of the frames drained in one cycle, all but the last are published directly through the SDK’s Publish, and the last is returned from HandleCapture so the base class publishes it on the normal path (:112-115, :127). Every successfully parsed frame is published exactly once; nothing is coalesced or discarded on the managed side.

Draining a full queue in one cycle is required, not an optimisation. A single GetFrame per cycle cannot keep pace with the bridge’s producer rate, and the queue would sit at its overflow threshold permanently.

6. IF-CMVARJO-03 Varjo runtime session

6.1 Session setup

Initialize performs, in order: varjo_SessionInit; a session priority of 1 so the compositor layers the bridge above a target application at default priority 0; gaze tracking initialisation with the standard output filter and the maximum supported output frequency; adapter selection by matching the Varjo-reported LUID; D3D11 device creation with video and BGRA support; D3D11 multithread protection; discovery of the left and right context view indices; and creation of a 4x4 transparent swap chain (VarjoGazeBridge.cpp:698-773).

The transparent swap chain is submitted as a render layer on every tick for one reason: it keeps the compositor servicing the bridge’s session (:765, :637-679). It carries no visible content.

When video capture is enabled, the capture thread additionally starts Media Foundation, reads the native view size, creates a double-width mirror swap chain, registers both eyes’ viewports with varjo_SetMirrorConfig, creates two per-eye encode textures, and initialises two encoders (:104-232).

6.2 What the video actually is

The video is the compositor mirror: the fully composited scene as presented to each eye, captured through varjo_SetMirrorConfig (VarjoGazeBridge.cpp:128-149). It is not imagery of the user’s eyes. The bridge does not include Varjo_datastream.h and opens no Varjo data stream, so no eye-camera, colour-camera or environment-cubemap stream is read at this revision. The stream names eye.left and eye.right denote which eye’s view was rendered, not which camera was read.

6.3 Encoder configuration

The MFT backend sets no explicit NAL-packaging attribute, so its output packaging is whatever the selected Media Foundation H.264 encoder produces by default. A consumer must not assume the two backends are byte-identical in their parameter-set placement.

7. IF-CMVARJO-04 Frame publication and data model reference

7.1 Entity

Every frame the bridge produces carries exactly one entity, and the managed module republishes it untouched. It does not rebuild the frame, does not assign an entity id, and does not reinterpret any field.

7.2 Frame kinds

The bridge emits two independent kinds of frame into the same queue. They are distinguished only by which components the entity carries.

Gaze and video are fully decoupled producers. Gaze is published whether or not video capture is running, and is not gated on an encoder or on a metadata match.

A video frame’s gaze copy is the same sample already delivered on that tick’s gaze frame, stashed per tick so the encoder-delayed video carries temporally correct gaze (:479-497, :625-656). It is not a second, independent reading. Do not average or double-count the two.

7.3 Published fields

No other field of these components is populated. Notably absent: every *_quality field, has_glasses, gaze_point, gaze_screen_point, the combined eyelid_openness and pupil_diameter fields, and other_pupil_data. A consumer must not read an absent field as a measured zero.

left_eye_occluded and right_eye_occluded come from Varjo’s per-eye gaze validity status, not from an eyelid-openness threshold, and blink is derived from them. That is the reverse of the derivation order used by some other eye-tracking modules in this catalogue.

7.4 Publication envelope

Each published frame is wrapped by the Module SDK as a DataPacket whose TimestampUnixMs is UTC now at publication and whose Payload is the packed SimulationFrame, with NodeId when OverrideNodeId is set and -1 otherwise. See the SDK contract. A frame therefore carries two timestamps with different meanings: the bridge’s capture tick inside capture_time, and the host’s publication instant on the packet. They are not interchangeable, and the gap between them includes the queue dwell time, the encoder delay for video frames, and one poll interval.

8. Timing and cadence

Because only the newest gaze sample per tick survives, the effective published gaze rate is the compositor tick rate, not the requested maximum sampling rate. When the runtime samples faster than the compositor ticks, the intermediate samples are discarded silently and no counter records the loss. Anyone using this module for saccade-scale analysis needs to know that the published series is decimated, not raw.

9. Connection lifecycle

Both InitialiseModule and StartCapture are bounded by the SDK’s StartupTimeout, 5 seconds by default, which this module does not override. HandleCapture has no timeout.

There is no reconnect logic on either side. Nothing retries varjo_SessionInit, and nothing detects a session that dies mid-capture: the capture thread keeps calling into a session the runtime may have abandoned. Recovery is a capture restart, which is what makes the ordering below matter.

9.1 Failed start does not tear down

Initialize has four failure returns, and three of them occur after the Varjo session already exists: no matching DXGI adapter (VarjoGazeBridge.cpp:720), D3D11 device creation failure (:736-737), and transparent swap-chain creation failure (:773). None of them undoes the session, the gaze tracking object or any D3D object created up to that point.

On the managed side a 0 return logs Varjo Initialize failed and returns false without calling Shutdown (VarjoGazeDataModule.cs:47-52), and the SDK does not call EndCapture when StartCapture returns false (BaseDataModule.cs:123-128). The native session therefore stays alive with no owner. A subsequent start calls Initialize again, which overwrites the session handle with a fresh varjo_SessionInit (VarjoGazeBridge.cpp:698), so the previous session and its D3D objects are leaked for the lifetime of the process. Restart HEAT Capture rather than only the capture session after a failed Varjo start.

9.2 Video failure is silent to the managed side

Video setup runs on the capture thread after Initialize has already returned 1. Every failure in that path (Media Foundation startup, mirror swap chain, encode textures, DXGI device manager, either encoder) leaves g_mirrorEnabled false and is reported only to the bridge’s own log file (VarjoGazeBridge.cpp:104-232). Gaze continues normally and no video frame is ever produced. The managed module is never told, its videoEnabled debug indicator reflects the setting rather than the outcome (VarjoGazeDataModule.cs:174), and the only evidence is IF-CMVARJO-05.

10. Error behaviour

A single malformed frame is deliberately not fatal to the drain cycle. Aborting the drain would discard every other frame queued that cycle, gaze included.

11. Units and conventions

Two consequences follow from that table and both belong to the audited revision rather than to the Varjo protocol. ipd is published in millimetres into a field the ProtoLib schema documents as metres, so a consumer reading it as metres is off by a factor of 1000. And because direction vectors are Z-negated while origins and the head-pose position are not, an origin and its direction are not expressed in a single consistent handedness; a consumer that builds a world-space ray from the pair must decide which convention to trust rather than assume they agree.

Beyond the Z negation and the narrowing to float, no value is scaled, filtered, validated or range-checked. The authority for their meaning is Varjo’s own documentation.

12. Configuration affecting the interfaces

Calibration is requested at every capture start unless CalibrationType is None; the bridge always passes the automatic headset-alignment guidance mode and does not expose a choice (VarjoGazeBridge.cpp:844-848). See Manage capture modules for the generic settings.

13. Compatibility and versioning

The bridge and the managed module must be deployed as a matched pair. This is a hard requirement, and nothing enforces it.

There is no version export, no ABI revision constant and no handshake. A mismatched pair does not fail at load: it fails as a wrong-shaped call or as frames the managed parser rejects, and the only symptom is a sustained parse-error rate or absent data. The bridge repository’s README.md documents an export set that does not exist in this revision (InitializeGazeTracking, ShutdownGazeTracking, GetGazeData, GetPupillometryData); it is stale and must not be used as the ABI authority. This document is the authority.

Pairing is established by vendoring, not by resolution. The module repository commits three prebuilt native binaries under bridge/ (VarjoGazeBridge.dll, VarjoLib.dll, heat_protolib_capi.dll) and marks each CopyToOutputDirectory Always (HEAT.VarjoGazeModule.csproj:18-30), so a given module commit ships whichever bridge build was committed alongside it. The bridge is not separately installable and must not be replaced in a deployed module directory.

Schema compatibility is a third axis. The frame is built by ProtoLib’s native C API on one side and parsed by HEAT.Proto.Simulation from HEAT.Capture.ModuleSDK 2.0.5 on the other. A ProtoLib schema change that renumbers or retypes a field surfaces as parse failures or as silently missing components, not as a load error.

Release validation must therefore pin and verify a specific bridge and managed pair together, as required by audit finding VBRIDGE-01. Audit finding VARJO-02 makes that harder than it should be: the module’s release workflow selects the full prerelease SemVer for the package version (module-release.yml:75-106) but publishes the release and the manifest download location at the stable base tag v{majorMinorPatch} (:126-134, :150-161). A prerelease and its eventual stable release can therefore occupy the same tag, so a tag alone does not identify a bridge and managed pair. Pin by commit until VARJO-02 is fixed.

14. Security considerations

Both interfaces are local and in-process. There is no network transport, no authentication and no encryption, and no privilege boundary between the module and the bridge: any code in the HEAT Capture process can call the same exports and drain the same queue.

Gaze, pupillometry and eyelid data are biometric personal data. The per-eye video is the composited scene as presented to the user (see 6.2), so it can contain whatever the target application displays, including material that has nothing to do with eye tracking. Treat a captured session as containing both biometric measurements and a screen recording, and restrict access accordingly.

15. IF-CMVARJO-05 Bridge diagnostic log

The bridge appends diagnostics to VarjoBridge.log in the directory named by the TEMP environment variable, falling back to the process working directory when TEMP is unset (VarjoGazeBridge.cpp:75-96). Each line is prefixed with the epoch time in milliseconds.

The file is opened, appended and closed per line under a mutex. It is never rotated, truncated or deleted, so it grows for as long as the workstation keeps running capture sessions. Its content is adapter identity, encoder selection and activation results, per-tick heartbeats, mirror acquisition errors, drain sizes and queue depth. No gaze value, pose value or video payload is written to it.

The code comment marks this log as temporary and to be removed once video capture is confirmed working; it is still present and still unconditional in the audited revision. Treat it as the only diagnostic channel for video setup failures (see 9.2), and as an unbounded file that deployment housekeeping has to account for.

16. Conformance

1. Start the Varjo Base runtime with a headset connected, then start a capture session. Confirm the log records Initialize returned 1 and a GazeTrackingStatus line.
2. Confirm the reported status is 4 (calibrated). Any other value is a documented condition, not a fault, and produces no gaze frames.
3. Confirm one entity, id 0x56415246 and name Varjo_Data, appears in the captured data.
4. Confirm GazeComponent and PupillometryDataComponent values change across successive frames while the headset is worn, and that removing the headset stops frames rather than producing frames with zeroed fields.
5. Check the published ipd value. Until the unit mismatch in section 11 is resolved, confirm it is in the tens (millimetres) and not a fraction of one (metres), and that downstream consumers apply the conversion.
6. With EnableVideoCapture on, confirm two VideoSource streams named eye.left and eye.right appear, each with codec H264, and confirm from the bridge log that g_mirrorEnabled=1 (video ACTIVE). A gaze-only session with the setting on means video setup failed silently; the log is the only evidence.
7. Confirm the encode resolution reported on the VideoSource matches the bridge log’s encode size line, and that its larger dimension does not exceed 1088.
8. Decode one eye’s access units in receive order and confirm a keyframe arrives at least once per second of wall clock.
9. Raise Interval well above its default, confirm the bridge log shows a rising queueDepth and then a video discontinuity, and restore the default. This exercises the documented overflow policy, not a fault.
10. Stop the capture session. Confirm Varjo session ended is logged and that the bridge heartbeat lines stop.
11. Validate the release pair, not the sides separately: record a session with the exact bridge and managed build under test, confirm a clean start and stop trace on both sides, and confirm the module’s parse-error counter stays at zero. A non-zero counter on a healthy headset indicates a mismatched pair.
12. Pin the pair by commit rather than by tag while VARJO-02 is open.

17. Revision history

HEAT Capture team. Last updated 2 October 2026.