Interface control document

1. Identification

At this revision the module does not use SRanipal. Eye data is obtained through HTC’s Vive Streaming SDK, whose managed declarations are in HTC Vive/VS_PC_SDK.cs. Any earlier reference to an SRanipal interface for this module is incorrect.

2. Scope

This document defines the native calls the module makes into VS_PC_SDK.dll, the callback interface the native library uses to deliver status transitions and eye-data payloads, the payload layout and its validity rules, and the gaze and pupillometry fields published to HEAT Capture.

The module is receive-only with respect to measurement data. Its only outbound native calls are library initialisation, release, callback registration, and start and stop of face tracking. It does not configure the headset, calibrate the eye tracker, or write anything back on behalf of HEAT Capture.

3. Interface inventory

4. IF-CMHTCGAZE-01 Vive Streaming SDK control

4.1 Transport and addressing

4.2 Entry points used

VS_SDKVersion is declared in HTC Vive/VS_PC_SDK.cs but never called at this revision, so the SDK version string is not logged or published.

4.3 Connection lifecycle

InitialiseModule runs the clean-up path first, so VS_StopFaceTracking (when a tracker was already initialised) and VS_Release are called before VS_Init. It then assigns the three callback delegates to fields, registers them, and calls VS_Init. On 0 it logs Init ViveStreamingSDK <version> success. followed by a trace-level Waiting for server., and allocates the sample buffer. On any other value it logs Init ViveStreamingSDK failed(<code>). and returns false, which fails module startup.

StartCapture logs Starting HTC Gaze Data Session and calls the tracking-start helper. That call is a no-op until the native library has reported the streaming state, because the helper returns immediately while no client connection is recorded. Tracking therefore begins from the status callback described in 5.2, not from capture start.

HandleCapture calls the tracking-start helper on every cycle. This is the retry mechanism: while the headset is connected and tracking has not yet produced data, each cycle may start one initialisation worker thread.

EndCapture runs the clean-up path only when the tracker initialisation flag is set. If tracking never produced data during the session, VS_Release is not called at capture end; the release happens on the next InitialiseModule instead.

The InitialiseModule and StartCapture calls are bounded by the SDK StartupTimeout of 5 seconds, which this module does not override. VS_Init is synchronous and runs inside that budget. The per-cycle HandleCapture call has no timeout. See the Module SDK ICD for the shared contract.

4.4 Tracking start, retry and stop

The worker’s outcome log is derived from the first-payload flag rather than the tracker initialisation flag, and that flag is never cleared for the lifetime of the module instance. After the first payload of a session, every later worker logs Face tracking started whether or not the attempt succeeded. Treat the outcome log as unreliable and use arriving frames as the evidence that tracking is live.

4.5 Authentication

None. The interface is an in-process native call into a library shipped with the module. There is no credential, token, pairing step or peer identity check in either direction.

5. IF-CMHTCGAZE-02 Status and eye-data callback

5.1 Transport

The native library invokes three managed delegates registered through VS_SetCallbackFunction:

Callbacks arrive on the native library’s own thread. In native-rate mode the module builds and publishes the frame inside the status callback, so publication happens on that thread rather than on the SDK capture cycle.

5.2 Status codes acted on

Server state values, as documented in the module source:

States 1, 3 and 4 produce no log line and no state change. A workstation stuck in any of them presents as a module that never delivers data.

The standby handler calls the native stop function directly instead of the stop helper, so the tracker initialisation flag stays set. Because the start helper only starts a worker when that flag is clear, tracking is never restarted when the server returns to state 0, and gaze delivery ends for the remainder of the session. This is audit finding HTC-01 and it is a property of this revision, not of the Vive Streaming SDK. Recovery requires restarting the module.

5.3 Wire format

An eye-data value is a single string of comma-separated decimal numbers. The module splits it on ,, parses each element positionally, and stores the result in a fresh 37-element float array. Position defines meaning; there is no field name, length prefix or version marker in the payload.

The twelve facial-expression fields at indices 21 and 23 to 33 are parsed into memory and never read out. They are not reachable through HEAT Capture at this revision.

5.4 Sample validity

The rejection path is documented in the source as keeping the previous value, but the array is newly allocated for each payload, so a rejected element is published as 0 rather than as the last good value. A consumer cannot distinguish a rejected element from a genuine zero.

There is no per-field validity or confidence flag in the payload and the module does not synthesise one. Blink state is the only quality-adjacent signal, and it is a blink flag rather than a tracking-validity flag.

5.5 Timing and cadence

In native-rate mode HandleCapture returns null every cycle, which publishes nothing for that cycle, so frames come only from the callback. Intermediate payloads are never buffered in either mode: polled mode discards everything except the latest payload at the moment of the cycle.

6. IF-CMHTCGAZE-03 Frame publication and data model reference

Each publication is a SimulationFrame containing exactly one entity.

6.1 Gaze component

Occlusion is the blink flag, not an occlusion measurement. Because the comparison is against exactly 1, any other non-zero blink encoding the native library might use would read as not blinking.

IPD, combined_eye_position, the per-eye position fields, every gaze quality field, has_glasses, gaze_point and gaze_screen_point are left at their protobuf defaults.

6.2 Pupillometry component

The combined eyelid_openness field, every quality field and other_pupil_data are left at their protobuf defaults. The mean pupil diameter is unweighted and does not exclude an eye that is blinking or untracked, so during a one-eyed blink it is roughly half the open eye’s diameter.

6.3 Packet envelope

The SDK wraps the frame as a DataPacket with TimestampUnixMs set to UTC now and the frame packed into Payload. It is published with NodeId when OverrideNodeId is set, otherwise -1. No EntityEvent is published by this module.

7. Units and conventions

No field is range-checked or clamped. The authority for the meaning, units and coordinate frame of every value is HTC’s own Vive Streaming SDK documentation.

8. Error behaviour

The frame builder contains a no-data guard that logs No Gaze data available and returns no frame. It is unreachable at this revision, because the sample buffer is allocated during initialisation and replaced, never cleared to null. An operator will not see that warning.

Loss of the eye tracker while the server stays in state 0 produces no log line and no state change. In native-rate mode, frames stop. In polled mode, the last payload is republished indefinitely with fresh capture timestamps, which a consumer cannot distinguish from a wearer holding a fixed gaze. Correlate with payload values changing rather than with frame arrival.

9. Configuration affecting the interface

SendAtNativeRate is read from the settings monitor at each decision point, so it takes effect without restarting the module. The settings identity registered for localisation is HtcVive, with the label key module.HtcVive.sendAtNativeRate.label; the configuration section name is HEAT.HTCGazeModule. See Manage capture modules for the generic settings.

The retry budget, the 3000 ms initialisation timeout, the 100 ms poll interval and the status codes are compile-time constants and are not configurable.

10. Compatibility and versioning

There is no version negotiation on either side of the native interface. VS_Init is called without a requested version, and the value returned by VS_Version is only logged. The module therefore accepts whatever VS_PC_SDK.dll is present in its own directory, and the shipped copy is the only version the module has been built against.

The eye-data payload is positional, unversioned and unlength-checked. A Vive Streaming SDK release that inserts, removes or reorders a field silently misattributes every value after the change point; a release that appends fields beyond index 36 raises an index-out-of-range exception on the callback thread. Revalidate the index table in 5.3 against HTC’s documentation before adopting a new SDK build.

Prerequisites for the interface to come up at all: Windows x64, .NET 10, SteamVR running and streaming, and HTC’s Vive Business Streaming driver installed. The module connects to the VBS service, not to the headset directly.

The package manifest produced by the module’s own packaging script names the module HEAT.HTCGazeModule with display name HTC Vive SDK. The central module registry records the same package with a trailing space, audit finding REG-03. Where a deployment matches packages by exact name, treat HEAT.HTCGazeModule as the authoritative identity and trim whitespace before comparing, otherwise the registry entry and the installed package can be seen as two products.

11. Security considerations

The interface is entirely local: an in-process native call into a bundled DLL, which in turn talks to the Vive Business Streaming service on the same workstation. There is no network endpoint, credential or encryption at this boundary, and the module performs no peer identity check. Because the DLL is resolved by name from the module’s own directory, write access to that directory is equivalent to code execution inside the module process; treat the installation directory as integrity-protected.

The module declares process.unrestricted, which is an explicit opt-out from HEAT Capture’s default per-module process restriction and widens what the module process can do relative to other modules. Gaze, blink and pupil diameter are biometric personal data and are directly identifying in combination with session metadata: restrict access to the workstation and to captured sessions according to the deployment’s own data-handling policy.

12. Conformance

1. With SteamVR streaming and the VBS driver installed, start a capture session. Confirm the log records Init ViveStreamingSDK <version> success., then Vive Streaming Server v<value> connected., then VS_PC_SDK: HMD connected..
2. Confirm one entity named HTC_Data appears in the captured data with both a GazeComponent and a PupillometryDataComponent.
3. With the headset worn, confirm gaze_direction and the per-eye directions change across successive frames, and that left_eyelid_openness and right_eyelid_openness are non-zero.
4. Blink deliberately and confirm blink, left_eye_occluded and right_eye_occluded assert.
5. Leave SendAtNativeRate at true and confirm frames arrive faster than the configured Interval. Set it to false and confirm the frame rate drops to one per Interval and that a static payload is republished with advancing capture timestamps.
6. Verify HTC-01 before relying on the session: put the streaming server into standby, confirm VS_PC_SDK: HMD disconnected., then return to streaming and check whether any new frame arrives. Until HTC-01 is fixed, no frame will arrive and the capture session must be restarted. Do not run a session where a standby transition is expected.
7. Confirm that a reading of 0 is not accepted as a measurement without corroboration, given the rejected-element behaviour in 5.4.

13. Revision history

HEAT Capture team. Last updated 2 October 2026.