qtm.h

Go to the documentation of this file.

/**
 * @file qtm.h
 * @brief QTM services.
 *
 * QTM is responsible for the following:
 *      - tracking and predicting the position of the user's eyes. This is done by using the inner
 *        camera sampling at 320x240px at 30 FPS, and by using the gyroscope to predict the position
 *        of the eyes between two camera samples (effectively doubling the tracking rate).
 *        The API reporting eye tracking data is actually *console-agnostic*. This concept is most
 *        likely covered by patent US9098112B2
 *      - automatically managing the IR LED emitter used for eye tracking in low-light conditions
 *      - managing the state of the parallax barrier by controlling the positions of the barrier's
 *        mask (opaque/transparent state by repeating pattern of 12 units, plus polarity). This is
 *        done via a TI TCA6416A I2C->Parallel expander (highlighted in yellow in this teardown photo:
 *        https://guide-images.cdn.ifixit.com/igi/IKlW6WTZKKmapYkt.full, with the expected 12 traces
 *        being clearly visible near the ribbon cable slot)
 *      - updating the barrier position according to eye tracking data relative to an optimal setting
 *        stored in calibration data: this is what Nintendo calls "Super Stable 3D" (SS3D); not done
 *        when in 2D mode
 *
 * Head-tracking can be used even if SS3D is disabled.
 *
 * SS3D works as follows:
 *      - compute the raw X and Y pixel coordinates for the eye midpoint:
 *            `rawX = (leftEyeRawPxCoords.x + rightEyeRawPxCoords.x) / 2`
 *            `rawY = (leftEyeRawPxCoords.y + rightEyeRawPxCoords.y) / 2`
 *      - rotate the value around the optical Z-axis using the optimal eye-to-camera angle from
 *        calibration data, with a rotation matrix
 *      - normalize the X value:
 *            `xC = (rawX / 320) - 0.5`
 *      - transform into world space coordinate, using fovX from calibration (convert to radians first).
 *        Note that this fovX doesn't take lens distortion into account and is slightly different from
 *        the hardcoded angle used in \ref QTMU_GetTrackingData
 *            `x = xC * tan(fovX/2)`
 *      - multiply by length of adjacent side (eye-to-camera distance) to get the length of the opposite
 *        side. This is the eye horizontal deviation to camera lens in mm, which is then converted to
 *        number of iod/12 units:
 *            `delta = x * optimalDistance / (iod/12)`
 *      - we then obtain the new target position of the parallax barrier (expressed in iod/12 units,
 *        mod iod/12):
 *            `pos = centerPos + delta`
 *       - the value is then rounded to nearest integer. To avoid artifacts, if the rounded value is
 *         going to increase, then 0.01 is subtracted, and if it is going to decrease, then 0.01 is added.
 *         The value is rounded again to compute the final discrete value written to the expander (barrier
 *         position).
 *       - note: all calculation in QTM and otherwise assume interocular distance to be 62mm (the average).
 *         Assumedly, if the user's IOD is different, then "optimal distance to screen" effectively changes
 *         for that user.
 *
 * QTM services are not present on O3DS, thus caller must call \ref qtmCheckServicesRegistered to check
 * if the services are registered. Moreover, since QTM functionality might not always be available (due
 * to blacklist or console being N2DSXL), `qtm:u` users should check Result return values, and `qtm:s`
 * users can call \ref QTMS_SetQtmStatus to check the actual availability status.
 *
 * Considering that the eye tracking data reporting API is hardware-agnostic, it is advisable to
 * hardcode neither camera aspect ratio (even if it is 4/3 on real hardware) and resolution nor
 * field-of-view angle.
 *
 * There is a separate QTM service, `qtm:c` ("hardware check"), that lets you manipulate parallax barrier
 * pattern directly. It is covered in \ref qtmc.h instead.
 */
#pragma once
 
#include <3ds/types.h>
 
/// ID of QTM status data (fully enabled/SS3D disabled) in `cfg`
#define QTM_STATUS_CFG_BLK_ID   0x180000u
 
/// ID of QTM calibration data in `cfg`
#define QTM_CAL_CFG_BLK_ID      0x180001u
 
/**
 * @brief QTM enablement status (when cameras not in use by user), set by `qtm:s`.
 * @note  Manual IR LED control, camera lux, and `qtm:c` commands remain available
 *        for use on N3DS and N3DSXL regardless.
 */
typedef enum QtmStatus {
    QTM_STATUS_ENABLED          = 0, ///< QTM is fully enabled.
    QTM_STATUS_SS3D_DISABLED    = 1, ///< QTM "super stable 3D" feature is disabled. Parallax barrier hardware state is configured to match O3DS.
 
    /**
     * @brief QTM is unavailable: either "blacklisted" (usually by NS) for the current title, **or console is a N2DSXL**.
     *
     *        In this state, all QTM functionality is disabled. This includes "super-stable 3D"
     *        (ie. auto barrier adjustment) including `qtm:s` manual barrier position setting functions,
     *        head tracking, IR LED control and camera luminance reporting (400.0 is returned instead).
     *
     * @note  `qtm:c` barrier hardware state setting function (\ref blah) bypasses this state.
     * @note  Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
     *        to be done, and is in fact never done by official software.
     */
    QTM_STATUS_UNAVAILABLE      = 2,
} QtmStatus;
 
/// QTM status data (fully enabled/SS3D disabled) in `cfg`. Usually all-zero on N2DSXL.
typedef struct QtmStatusCfgData {
    QtmStatus defaultStats; ///< QTM status at boot (fully enabled or SS3D disabled).
    /**
     * @brief "Global variable" (.data) section load mode? Unused.
     *        From CTRAging:
     *            - 0: "normal"
     *            - 1: "single reacq"
     *            - 2: "double reacq"
                  - 3/4/5: "w2w copy 1/10/100"
     */
    u8 gvLoadMode;
    u8 _padding[2];         ///< Padding.
} QtmStatusCfgData;
 
/// QTM calibration data (fully enabled/SS3D disabled) in `cfg`. Usually all-zero on N2DSXL.
typedef struct QtmCalibrationData {
    /**
     * @brief Neutral (center) barrier position/offset (with slit width of 6 units), when the user is
     *        facing directly facing the camera, that is to say, their eye midpoint normalized X coord
     *        in the camera's plane is 0, assuming the user's head is located at the expected viewing distance
     *        and at the expected eye-to-camera angle (as per the rest of this structure).
     *        This is expressed in terms of iod/12 units modulo iod/12 (thus, range is 0 to 11 included),
     *        with IOD (interocular distance) assumed to be 62mm.
     * @note  This field is floating-point for QTM auto-adjustment purposes, however the actual barrier
     *        position in hardware is an integer.
     * @note  This is the field that System Settings lets you add -1.0 to +1.0 to.
     * @note  Moreover, this field can be directly changed through \ref QTMS_SetCenterBarrierPosition.
     */
    float centerBarrierPosition;
 
    float translationX;     ///< Lens X coord in inner camera space? Very low value and seems to be unused.
    float translationY;     ///< Lens Y coord in inner camera space? Very low value and seems to be unused.
    float rotationZ;        ///< Optimal eye-to-camera angle, in radians, without accounting for lens distortion.
    float fovX;             ///< Camera's horizontal FoV in degrees, without accounting for lens distortion.
    float viewingDistance;  ///< Optimal viewing distance between user and top screen, assuming iod to be 62mm.
} QtmCalibrationData;
 
/// Left eye or right eye, for \ref QtmTrackingData and \ref QtmRawTrackingData
typedef enum QtmEyeSide {
    QTM_EYE_LEFT    = 0,    ///< Left eye.
    QTM_EYE_RIGHT   = 1,    ///< Right eye.
 
    QTM_EYE_NUM,            ///< Number of eyes.
} QtmEyeSide;
 
/// QTM raw eye tracking data
typedef struct QtmRawTrackingData {
    /**
     * @brief Eye position detected or predicted, equals (confidenceLevel > 0).
     *        If false, QTM will attempt to make a guess based on gyro data.
     *        If the console isn't moving either, then QTM will assume the user's eyes are progressively
     *        moving back to face the screen.
     */
    bool eyesTracked;       ///< Eye position detected or predicted, equals (confidenceLevel > 0).
    u8 _padding[3];         ///< Padding.
    u32 singletonQtmPtr;    ///< Pointer to eye-tracking singleton pointer, in QTM's .bss, located in N3DS extra memory.
    float confidenceLevel;  ///< Eye tracking confidence level (0 to 1).
 
    /**
     * @brief Raw predicted or detected eye coordinates. Each eye is represented as one point.
     *        Fractional part is *not* necessarily zero.
     * @note  X coord is within 0 to 320.
     * @note  Y coord is within 0 to 240.
     */
    float rawEyeCameraCoordinates[QTM_EYE_NUM][2];
 
    float dPitch;           ///< Difference in gyro pitch from position at console boot.
    float dYaw;             ///< Difference in gyro yaw from position at console boot.
    float dRoll;            ///< Difference in gyro roll from position at console boot.
 
    s64   samplingTick;     ///< Time point the current measurements were made.
} QtmRawTrackingData;
 
/// QTM processed eye tracking data, suitable for 3D programming
typedef struct QtmTrackingData {
    bool eyesTracked;       ///< Eye position detected or tracked with some confidence, equals (confidenceLevel > 0). Even if false, QTM may make a guess
    bool faceDetected;      ///< Whether or not the entirety of the user's face has been detected with good confidence.
    bool eyesDetected;      ///< Whether or not the user's eyes have actually been detected with full confidence.
    u8 _unused;             ///< Unused.
    bool clamped;           ///< Whether or not the normalized eye coordinates have been clamped after accounting for lens distortion.
    u8 _padding[3];         ///< Padding.
 
    float confidenceLevel;  ///< Eye tracking confidence level (0 to 1).
 
    /**
     * @brief Normalized eye coordinates, for each eye, after accounting for lens distortion, centered around camera.
     *        X coord is in the -1 to 1 range, and Y coord range depends on inverse aspect ratio (-0.75 to 0.75 on real hardware).
     * @note  On real hardware, X coord equals `((rawX / 160.0) - 1.00) * 1.0639` before clamping.
     * @note  On real hardware, Y coord equals `((rawY / 160.0) - 0.75) * 1.0637` before clamping.
     */
    float eyeCameraCoordinates[QTM_EYE_NUM][2];
 
    /**
     * @brief Normalized eye coordinates, for each eye, in world space.
     *        Corresponds to \ref eyeCameraCoordinates multiplied by tangent of field of view.
     * @note  On real hardware, X coord equals `eyeCameraCoordinates.x * tan(64.9 deg / 2)`.
     * @note  On real hardware, Y coord equals `eyeCameraCoordinates.x * tan(51.0 deg / 2)`.
     */
    float eyeWorldCoordinates[QTM_EYE_NUM][2];
 
    float dPitch;           ///< Difference in gyro pitch from position at console boot.
    float dYaw;             ///< Difference in gyro yaw from position at console boot.
    float dRoll;            ///< Difference in gyro roll from position at console boot.
 
 
    s64   samplingTick;     ///< Time point the current measurements were made.
} QtmTrackingData;
 
/// QTM service name enum, excluding `qtm:c`
typedef enum QtmServiceName {
    /**
     * @brief `qtm:u`: has eye-tracking commands and IR LED control commands, but for some
     *        reason cannot fetch ambiant lux data from the camera's luminosity sensor.
     */
    QTM_SERVICE_USER            = 0,
 
    /**
     * @brief `qtm:s`: has access to all `qtm:u` commands, plus luminosity sensor, plus
     *        manual barrier position setting and calibration adjustment commands.
     *        Automatic barrier control is reenabled on session exit.
     */
    QTM_SERVICE_SYSTEM          = 1,
 
    /**
     * @brief `qtm:sp`: has access to all `qtm:s` (and `qtm:u`) commands, and merely has a
     *         few more commands that GSP uses to notify QTM of 2D<>3D mode switches and
     *         power events. Automatic barrier control is reenabled on session exit.
     *         GSP always keeps a `qtm:sp` sessions open (at least on latest system version),
     *         whereas NS opens then immediately closes a `qtm:sp` sessions only when dealing
     *         with a "blacklisted" application (that is, almost never).
     */
    QTM_SERVICE_SYSTEM_PROCESS  = 2,
} QtmServiceName;
 
/**
 * @brief  Check whether or not QTM services are registered.
 * @return True on O3DS systems, false on N3DS systems.
 */
bool qtmCheckServicesRegistered(void);
 
/**
 * @brief Initializes QTM (except `qtm:c`).
 *        Excluding `qtm:c`, QTM has three main services.
 *        Only 3 sessions (2 until 9.3.0 sysupdate) for ALL services COMBINED, including `qtm:c`,
 *        can be open at a time.
 *        Refer to \ref QtmServiceName enum value descriptions to see which service to choose.
 *
 * @param serviceName QTM service name enum value (corresponding to `qtm:u`, `qtm:s` and `qtm:sp`
 *                    respectively).
 * @note  Result of \ref qtmCheckServicesRegistered should be checked before calling this function.
 */
Result qtmInit(QtmServiceName serviceName);
 
/// Exits QTM.
void qtmExit(void);
 
/// Checks whether or not a `qtm:u`, `qtm:s` or `qtm:sp` session is active.
bool qtmIsInitialized(void);
 
/// Returns a pointer to the current `qtm:u` / `qtm:s` / `qtm:sp` session handle.
Handle *qtmGetSessionHandle(void);
 
/**
 * @brief  Gets the current raw eye tracking data, with an optional prediction made for predictionTimePointOrZero = t+dt,
 *         or for the current time point (QTM makes predictions based on gyro data since inner camera runs at 30 FPS).
 *
 * @param[out] outData Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized).
 * @param predictionTimePointOrZero Either zero, or the time point (in system ticks) for which to make a prediction for.
 *                                  Maximum 1 frame (at 30 FPS) in the past, and up to 5 frames in the future.
 * @return `0xC8A18008` if camera is in use by user, or `0xC8A183EF` if QTM is unavailable (in particular, QTM is always
 *         unavailable on N2DSXL), Otherwise, 0 (success). Return value should be checked by caller.
 * @note   Consider using \ref QTMU_GetTrackingDataEx instead.
 */
Result QTMU_GetRawTrackingDataEx(QtmRawTrackingData *outData, s64 predictionTimePointOrZero);
 
/**
 * @brief  Gets the current raw eye tracking data.
 *
 * @param[out] outData Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized).
 * @return `0xC8A18008` if camera is in use by user, or `0xC8A183EF` if QTM is unavailable (in particular, QTM is always
 *         unavailable on N2DSXL), Otherwise, 0 (success). Return value should be checked by caller.
 * @note   Consider using \ref QTMU_GetTrackingData instead.
 */
static inline Result QTMU_GetRawTrackingData(QtmRawTrackingData *outData)
{
    return QTMU_GetRawTrackingDataEx(outData, 0LL);
}
 
/**
 * @brief  Gets the current normalized eye tracking data, made suitable for 3D programming with an optional prediction made
 *         for predictionTimePointOrZero = t+dt, or for the current time point (QTM makes predictions based on gyro data since
 *         inner camera runs at 30 FPS).
 *
 * @param[out] outData Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized).
 * @param predictionTimePointOrZero Either zero, or the time point (in system ticks) for which to make a prediction for.
 *                                  Maximum 1 frame (at 30 FPS) in the past, and up to 5 frames in the future.
 * @return `0xC8A18008` if camera is in use by user, or `0xC8A183EF` if QTM is unavailable (in particular, QTM is always
 *         unavailable on N2DSXL). Otherwise, 0 (success). Return value should be checked by caller.
 * @note   This can, for example, be used in games to allow the user to control the scene's camera with their own face.
 */
Result QTMU_GetTrackingDataEx(QtmTrackingData *outData, s64 predictionTimePointOrZero);
 
/**
 * @brief  Gets the current normalized eye tracking data, made suitable for 3D programming.
 *
 * @param[out] outData Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized).
 * @return `0xC8A18008` if camera is in use by user, or `0xC8A183EF` if QTM is unavailable (in particular, QTM is always
 *         unavailable on N2DSXL). Otherwise, 0 (success). Return value should be checked by caller.
 * @note   This can, for example, be used in games to allow the user to control the scene's camera with their own face.
 */
static inline Result QTMU_GetTrackingData(QtmTrackingData *outData)
{
    return QTMU_GetTrackingDataEx(outData, 0LL);
}
 
/**
 * @brief Computes an approximation of the horizontal angular field of view of the camera based on eye tracking data.
 *
 * @param data Eye tracking data, obtained from \ref QTMU_GetTrackingData or \ref QTMU_GetTrackingDataEx.
 * @return Horizontal angular field of view in radians. Corresponds to 64.9 degrees on real hardware.
 */
float qtmComputeFovX(const QtmTrackingData *data);
 
/**
 * @brief Computes an approximation of the vertical angular field of view of the camera based on eye tracking data.
 *
 * @param data Eye tracking data, obtained from \ref QTMU_GetTrackingData or \ref QTMU_GetTrackingDataEx.
 * @return Vertical angular field of view in radians. Corresponds to 51.0 degrees on real hardware.
 */
float qtmComputeFovY(const QtmTrackingData *data);
 
/**
 * @brief Computes a rough approximation of the inverse of the aspect ration of the camera based on eye tracking data.
 *
 * @param data Eye tracking data, obtained from \ref QTMU_GetTrackingData or \ref QTMU_GetTrackingDataEx.
 * @return Rough approximation of the inverse of the aspect ratio of the camera. Aspect ratio is exactly 0.75 on real hardware.
 */
float qtmComputeInverseAspectRatio(const QtmTrackingData *data);
 
/**
 * @brief  Computes the user's head tilt angle, that is, the angle between the line through both eyes and the camera's
 *         horizontal axis in camera space.
 *
 * @param data Eye tracking data, obtained from \ref QTMU_GetTrackingData or \ref QTMU_GetTrackingDataEx.
 * @return Horizontal head angle relative to camera, in radians.
 */
float qtmComputeHeadTiltAngle(const QtmTrackingData *data);
 
/**
 * @brief  Estimates the distance between the user's eyes and the camera, based on
 *         eye tracking data. This may be a little bit inaccurate, as this assumes
 *         interocular distance of 62mm (like all 3DS software does), and that both
 *         eyes are at the same distance from the screen.
 *
 * @param data Eye tracking data, obtained from \ref QTMU_GetTrackingData or \ref QTMU_GetTrackingDataEx.
 * @return Eye-to-camera distance in millimeters.
 */
float qtmEstimateEyeToCameraDistance(const QtmTrackingData *data);
 
/**
 * @brief  Temporarily enables manual control of the IR LED by user, disabling its automatic control.
 *         If not already done, this also turns off the IR LED. This setting is cleared when user closes the console's shell.
 * @return Always 0 (success).
 */
Result QTMU_EnableManualIrLedControl(void);
 
/**
 * @brief  Temporarily disables manual control of the IR LED by user, re-enabling its automatic control.
 *         If not already done, this also turns off the IR LED.
 * @return Always 0 (success).
 */
Result QTMU_DisableManualIrLedControl(void);
 
/**
 * @brief  Turns the IR LED on or off during manual control. \ref QTMU_EnableManualIrLedControl must have been called.
 *
 * @param on Whether to turn the IR LED on or off.
 * @return `0xC8A18005` if manual control was not enabled or if the operation failed, `0xC8A18008` if camera is in use
 *         by user, or `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL).
 *         Otherwise, 0 (success).
 */
Result QTMU_SetIrLedStatus(bool on);
 
/**
 * @brief  Attempts to clear IR LED overrides from any of the relevant commands in `qtm:u`, `qtm:s` (and `qtm:c`) commands
 *         by calling \ref QTMU_EnableManualIrLedControl followed by \ref QTMU_DisableManualIrLedControl, so that auto IR LED
 *         management takes place again.
 * @return The value returned by \ref QTMU_DisableManualIrLedControl.
 */
Result qtmClearIrLedOverrides(void);
 
/**
 * @brief  Checks whether or not QTM has been blacklisted, ie. that it has been made unavailable.
 *         In detail, this means that the last call to \ref QTMS_SetQtmStatus was made with argument \ref QTM_STATUS_UNAVAILABLE,
 *         usually by NS. This feature seems to only be used for some internal test titles.
 *
 * @param[out] outBlacklisted Whether or not QTM is unavailable. Always true on N2DSXL.
 * @return Always 0 (success).
 * @note   On N2DSXL, even though status is always supposed to be \ref QTM_STATUS_UNAVAILABLE, this function often returns true
 *         (because NS doesn't change QTM's status if title isn't blacklisted). Do not rely on this for N2DSXL detection.
 * @note   Refer to https://www.3dbrew.org/wiki/NS_CFA for a list of title UIDs this is used for.
 */
Result QTMU_IsCurrentAppBlacklisted(bool *outBlacklisted);
 
/**
 * @brief  Sets the neutral (center) barrier position/offset in calibration, _without_ saving it to `cfg`.
 *         Takes effect immediately. SS3D works by calculating the position of the eye midpoint, rotated
 *         by the ideal eye-to-camera angle, expressed in (iod/12 units, iod assumed to be 62mm).
 *
 * @param position Center barrier position, in terms of iod/12 units modulo iod/12.
 * @note   This field is floating-point for QTM auto-adjustment purposes, however the actual barrier position
 *         in hardware is an integer.
 * @note   This is the field that System Settings lets you add -1.0 to +1.0 to.
 * @note   There is no "get" counterpart for this.
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise
           0 (success).
 */
Result QTMS_SetCenterBarrierPosition(float position);
 
/**
 * @brief  Gets the average ambient luminance as perceived by the inner camera (in lux).
 *         If QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), returns 400.0 instead
 *         of the actual luminance.
 *
 * @param[out] outLuminanceLux Where to write the luminance to. Always 400.0 on N2DSXL.
 * @note   Camera exposure, and in particular auto-exposure affects the returned luminance value. This must be
 *         taken into consideration, because this value can thus surge when user covers the inner camera.
 * @return Always 0 (success).
 */
Result QTMS_GetCameraLuminance(float *outLuminanceLux);
 
/**
 * @brief  Enables automatic barrier control when in 3D mode with "super stable 3D" enabled.
 *
 * @note   This is automatically called upon `qtm:s` and `qtm:sp` session exit.
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise
           0 (success).
 * @note   Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
 *         to be done, and is in fact never done by official software. If that is regardless the case,
 *         this function here does nothing.
 */
Result QTMS_EnableAutoBarrierControl(void);
 
/**
 * @brief  Temporarily disables automatic barrier control (when in 3D mode with "super stable 3D" enabled).
 *
 * @note   This is automatically called upon `qtm:s` and `qtm:sp` session exit.
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise
           0 (success).
 * @note   Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
 *         to be done, and is in fact never done by official software. If that is regardless the case,
 *         this function here does nothing.
 */
Result QTMS_DisableAutoBarrierControl(void);
 
/**
 * @brief  Temporarily sets the parallax barrier's position (offset in iod/12 units, assuming slit width of 6 units).
 *         Does nothing in 2D mode and/or if "super stable 3D" is disabled.
 *
 * @param position Parallax barrier position (offset in units), must be between 0 and 11 (both included)
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), 0xE0E18002
 *         if \p position is not in range, otherwise 0 (success).
 * @note   Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
 *         to be done, and is in fact never done by official software. If that is regardless the case,
 *         this function here does nothing.
 * @note   No effect when the screen is in 2D mode.
 * @see    QTMC_SetBarrierPattern
 */
Result QTMS_SetBarrierPosition(u8 position);
 
/**
 * @brief  Gets the current position of the parallax barrier (offset in iod/12 units, slit width of 6 units).
 *         When "super stable 3D" is disabled, returns 13 instead.
 *
 * @param[out] outPosition Where to write the barrier's position to.
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise
           0 (success).
 * @note   When SS3D is disabled, this returns 13 to \p outPosition . When in 2D mode, the returned position is not
           updated.
 * @note   Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
 *         to be done, and is in fact never done by official software. If that is regardless the case,
 *         this function here returns 13 to \p outPosition .
 * @see    QTMC_SetBarrierPattern
 */
Result QTMS_GetCurrentBarrierPosition(u8 *outPosition);
 
/**
 * @brief  Temporarily overrides IR LED state. Requires "manual control" from `qtm:u` to be disabled, and has
 *         lower priority than it.
 *
 * @param on Whether to turn the IR LED on or off.
 * @return `0xC8A18005` if manual control was enabled or if the operation failed, `0xC8A18008` if camera is in use
 *         by user (unless "hardware check" API enabled), or `0xC8A18009` if QTM is unavailable (in particular,
 *         QTM is always unavailable on N2DSXL). Otherwise, 0 (success).
 */
Result QTMS_SetIrLedStatusOverride(bool on);
 
/**
 * @brief  Sets calibration data, taking effect immediately, and optionally saves it to `cfg`.
 *
 * @param cal Pointer to calibration data.
 * @param saveCalToCfg Whether or not to persist the calibration data in `cfg`.
 * @return `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise
           whatever `cfg:s` commands return (if used), or 0 (success).
 * @note   There is no "get" counterpart for this function, and there is no way to see the current calibration data
           in use unless it has been saved to `cfg`.
 * @note   Due to an oversight, \ref QTMS_SetQtmStatus allows changing QTM state on N2DSXL. This is not intended
 *         to be done, and is in fact never done by official software. If that is regardless the case,
 *         this function here doesn't apply calibrations parameters (they may still be saved, however,
 *         even though QTM calibration blocks are always normally 0 on N2DSXL).
 */
Result QTMS_SetCalibrationData(const QtmCalibrationData *cal, bool saveCalToCfg);
 
/**
 * @brief  Gets the current QTM status (enabled/ss3d disabled/unavailable).
 *
 * @param[out] outQtmStatus Where to write the QTM status to.
 * @return Always 0.
 */
Result QTMS_GetQtmStatus(QtmStatus *outQtmStatus);
 
/**
 * @brief   Gets the current QTM status (enabled/ss3d disabled/unavailable). Also sets or clear the
 *          "blacklisted" flag returned by \ref QTMU_IsCurrentAppBlacklisted.
 *
 * @param qtmStatus QTM status to set. If equal to \ref QTM_STATUS_UNAVAILABLE, sets the "blacklisted" flag,
 *                  otherwise clears it.
 * @return  `0xE0E18002` if enum value is invalid, otherwise 0 (success).
 * @note    System settings uses this to disable super-stable 3D, and NS to "blacklist" (make QTM unavailable)
 *          specific applications.
 */
Result QTMS_SetQtmStatus(QtmStatus qtmStatus);
 
/**
 * @brief  Called by GSP's LCD driver to signal 2D<>3D mode change
 * @param newMode 0 for 2D, 1 for 800px 2D (unused for this function, same as 0), 2 for 3D
 * @return Always 0 (success).
 */
Result QTMSP_NotifyTopLcdModeChange(u8 newMode);
 
/**
 * @brief  Called by GSP's LCD driver during top LCD power-on to signal to QTM that it may power on
 *         and/or reconfigure then use the TI TCA6416A expander. In the process, QTM re-creates its
 *         expander thread.
 * @return Always 0 (success).
 */
Result QTMSP_NotifyTopLcdPowerOn(void);
 
/**
 * @brief  Called by GSP's LCD driver to know whether or not QTM's expander thread is using
 *         the TI TCA6416A expander; it is waiting for this to become true/false during LCD
 *         power on/power off to proceed. Always false on N2DSXL.
 * @param[out] outActive Where to write the "in use" status to.
 * @return  Always 0 (success).
 */
Result QTMSP_IsExpanderInUse(bool *outActive);
 
/**
 * @brief  Called by GSP's LCD driver during top LCD power-on to signal to QTM that it needs to
 *         switch the parallax barrier state to a 2D state (all-transparent mask). Causes QTM's
 *         expander thread to exit, relinquishing its `i2c::QTM` session with it.
 * @return Always 0 (success).
 */
Result QTMSP_NotifyTopLcdPowerOff(void);