Control interpupillary distance (IPD)

Note: you are currently viewing documentation for a beta or an older version of Varjo

Setting Interpupillary Distance Parameters

It is possible to set interpupillary distance (IPD) parameters of the Varjo headset by calling the function varjo_SetInterPupillaryDistanceParameters and passing an array of parameter keys and values.

/**
 * Sets interpupillary distance (IPD) parameters of the headset.
 *
 * #varjo_Error_InvalidParameter error will be set if parsing the provided parameters fails.
 *
 * @param session Varjo session handle.
 * @param parameters IPD key-value parameters.
 * @param parameterCount Number of parameters provided.
 */
VARJO_API void varjo_SetInterPupillaryDistanceParameters(
    struct varjo_Session* session,
    struct varjo_InterPupillaryDistanceParameters* parameters,
    int32_t parameterCount);

varjo_InterPupillaryDistanceParameters is a structure containing an IPD parameter key-value pair represented as two C strings:

/**
 * Parameters passed to #varjo_SetInterPupillaryDistanceParameters function.
 */
struct varjo_InterPupillaryDistanceParameters {
    const char* key;
    const char* value;
};
  • Set key to “AdjustmentMode” and value either to “Manual” to request a manual IPD control mode, or to “Automatic” to request an automatic IPD control mode.
  • Set key to “RequestedPositionInMM” and value to a string formatted floating point value representing the requested headset IPD position in millimeters with decimal point used as a separator (e.g. “64.5”).

Note that the parameter “RequestedPositionInMM” is supported only when the headset is connected and the “Manual” IPD adjustment mode is used or requested in the same call. When using this parameter, the caller should typically set the position value to be equal to the known IPD of the user, even if the value is out of the supported IPD range of the headset. The headset will then drive the IPD motor to the closest supported position.

Setting the parameter “RequestedPositionInMM” to a string representation of a negative, infinite, not-a-number or any other non-parsable value will result in error varjo_Error_InvalidParameter. Note that no other decimal separator except decimal point is supported, thus it is recommended to use a locale-independent method of converting a floating point value to a string on the caller side (e.g. std::to_chars in C++).

The accuracy of the “Manual” IPD adjustment mode via the API is nearly the same as via the user interface (UI) in Varjo Base, and thus there is little to no gain in setting a more accurate IPD value via the API (e.g. by passing more digits of the decimal fraction) than by setting the value via the UI, given the level of accuracy reached by setting it via the UI.

Reading Interpupillary Distance Parameters State

You can read the current state of the IPD parameters applied to the headset using Varjo properties.

  • The currently used IPD adjustment mode can be read from the property with key varjo_PropertyKey_IPDAdjustmentMode (string value).
  • The currently set headset IPD position in millimeters can be read from the property with key varjo_PropertyKey_IPDPosition (floating point value). This property exists only when the headset is connected.

Examples

Check the ”GazeTrackingExample” application that demonstrates the use of Varjo native SDK for gaze tracking and IPD control.