libctru
v2.4.1
|
QTM services. More...
#include <3ds/types.h>
Go to the source code of this file.
Data Structures | |
struct | QtmStatusCfgData |
QTM status data (fully enabled/SS3D disabled) in cfg . Usually all-zero on N2DSXL. More... | |
struct | QtmCalibrationData |
QTM calibration data (fully enabled/SS3D disabled) in cfg . Usually all-zero on N2DSXL. More... | |
struct | QtmRawTrackingData |
QTM raw eye tracking data. More... | |
struct | QtmTrackingData |
QTM processed eye tracking data, suitable for 3D programming. More... | |
Macros | |
#define | QTM_STATUS_CFG_BLK_ID 0x180000u |
ID of QTM status data (fully enabled/SS3D disabled) in cfg | |
#define | QTM_CAL_CFG_BLK_ID 0x180001u |
ID of QTM calibration data in cfg | |
Enumerations | |
enum | QtmStatus { QTM_STATUS_ENABLED = 0 , QTM_STATUS_SS3D_DISABLED = 1 , QTM_STATUS_UNAVAILABLE = 2 } |
QTM enablement status (when cameras not in use by user), set by qtm:s . More... | |
enum | QtmEyeSide { QTM_EYE_LEFT = 0 , QTM_EYE_RIGHT = 1 , QTM_EYE_NUM } |
Left eye or right eye, for QtmTrackingData and QtmRawTrackingData. More... | |
enum | QtmServiceName { QTM_SERVICE_USER = 0 , QTM_SERVICE_SYSTEM = 1 , QTM_SERVICE_SYSTEM_PROCESS = 2 } |
QTM service name enum, excluding qtm:c More... | |
Functions | |
bool | qtmCheckServicesRegistered (void) |
Check whether or not QTM services are registered. More... | |
Result | qtmInit (QtmServiceName serviceName) |
Initializes QTM (except qtm:c ). More... | |
void | qtmExit (void) |
Exits QTM. | |
bool | qtmIsInitialized (void) |
Checks whether or not a qtm:u , qtm:s or qtm:sp session is active. | |
Handle * | qtmGetSessionHandle (void) |
Returns a pointer to the current qtm:u / qtm:s / qtm:sp session handle. | |
Result | QTMU_GetRawTrackingDataEx (QtmRawTrackingData *outData, s64 predictionTimePointOrZero) |
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). More... | |
static Result | QTMU_GetRawTrackingData (QtmRawTrackingData *outData) |
Gets the current raw eye tracking data. More... | |
Result | QTMU_GetTrackingDataEx (QtmTrackingData *outData, s64 predictionTimePointOrZero) |
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). More... | |
static Result | QTMU_GetTrackingData (QtmTrackingData *outData) |
Gets the current normalized eye tracking data, made suitable for 3D programming. More... | |
float | qtmComputeFovX (const QtmTrackingData *data) |
Computes an approximation of the horizontal angular field of view of the camera based on eye tracking data. More... | |
float | qtmComputeFovY (const QtmTrackingData *data) |
Computes an approximation of the vertical angular field of view of the camera based on eye tracking data. More... | |
float | qtmComputeInverseAspectRatio (const QtmTrackingData *data) |
Computes a rough approximation of the inverse of the aspect ration of the camera based on eye tracking data. More... | |
float | qtmComputeHeadTiltAngle (const QtmTrackingData *data) |
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. More... | |
float | qtmEstimateEyeToCameraDistance (const QtmTrackingData *data) |
Estimates the distance between the user's eyes and the camera, based on eye tracking data. More... | |
Result | QTMU_EnableManualIrLedControl (void) |
Temporarily enables manual control of the IR LED by user, disabling its automatic control. More... | |
Result | QTMU_DisableManualIrLedControl (void) |
Temporarily disables manual control of the IR LED by user, re-enabling its automatic control. More... | |
Result | QTMU_SetIrLedStatus (bool on) |
Turns the IR LED on or off during manual control. More... | |
Result | qtmClearIrLedOverrides (void) |
Attempts to clear IR LED overrides from any of the relevant commands in qtm:u , qtm:s (and qtm:c ) commands by calling QTMU_EnableManualIrLedControl followed by QTMU_DisableManualIrLedControl, so that auto IR LED management takes place again. More... | |
Result | QTMU_IsCurrentAppBlacklisted (bool *outBlacklisted) |
Checks whether or not QTM has been blacklisted, ie. More... | |
Result | QTMS_SetCenterBarrierPosition (float position) |
Sets the neutral (center) barrier position/offset in calibration, without saving it to cfg . More... | |
Result | QTMS_GetCameraLuminance (float *outLuminanceLux) |
Gets the average ambient luminance as perceived by the inner camera (in lux). More... | |
Result | QTMS_EnableAutoBarrierControl (void) |
Enables automatic barrier control when in 3D mode with "super stable 3D" enabled. More... | |
Result | QTMS_DisableAutoBarrierControl (void) |
Temporarily disables automatic barrier control (when in 3D mode with "super stable 3D" enabled). More... | |
Result | QTMS_SetBarrierPosition (u8 position) |
Temporarily sets the parallax barrier's position (offset in iod/12 units, assuming slit width of 6 units). More... | |
Result | QTMS_GetCurrentBarrierPosition (u8 *outPosition) |
Gets the current position of the parallax barrier (offset in iod/12 units, slit width of 6 units). More... | |
Result | QTMS_SetIrLedStatusOverride (bool on) |
Temporarily overrides IR LED state. More... | |
Result | QTMS_SetCalibrationData (const QtmCalibrationData *cal, bool saveCalToCfg) |
Sets calibration data, taking effect immediately, and optionally saves it to cfg . More... | |
Result | QTMS_GetQtmStatus (QtmStatus *outQtmStatus) |
Gets the current QTM status (enabled/ss3d disabled/unavailable). More... | |
Result | QTMS_SetQtmStatus (QtmStatus qtmStatus) |
Gets the current QTM status (enabled/ss3d disabled/unavailable). More... | |
Result | QTMSP_NotifyTopLcdModeChange (u8 newMode) |
Called by GSP's LCD driver to signal 2D<>3D mode change. More... | |
Result | QTMSP_NotifyTopLcdPowerOn (void) |
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. More... | |
Result | QTMSP_IsExpanderInUse (bool *outActive) |
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. More... | |
Result | QTMSP_NotifyTopLcdPowerOff (void) |
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). More... | |
QTM services.
QTM is responsible for the following:
Head-tracking can be used even if SS3D is disabled.
SS3D works as follows:
rawX = (leftEyeRawPxCoords.x + rightEyeRawPxCoords.x) / 2
rawY = (leftEyeRawPxCoords.y + rightEyeRawPxCoords.y) / 2
xC = (rawX / 320) - 0.5
x = xC * tan(fovX/2)
delta = x * optimalDistance / (iod/12)
pos = centerPos + delta
QTM services are not present on O3DS, thus caller must call 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 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 qtmc.h instead.
enum QtmEyeSide |
Left eye or right eye, for QtmTrackingData and QtmRawTrackingData.
Enumerator | |
---|---|
QTM_EYE_LEFT | Left eye. |
QTM_EYE_RIGHT | Right eye. |
QTM_EYE_NUM | Number of eyes. |
enum QtmServiceName |
QTM service name enum, excluding qtm:c
enum QtmStatus |
QTM enablement status (when cameras not in use by user), set by qtm:s
.
qtm:c
commands remain available for use on N3DS and N3DSXL regardless. Enumerator | |
---|---|
QTM_STATUS_ENABLED | QTM is fully enabled. |
QTM_STATUS_SS3D_DISABLED | QTM "super stable 3D" feature is disabled. Parallax barrier hardware state is configured to match O3DS. |
QTM_STATUS_UNAVAILABLE | 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).
|
bool qtmCheckServicesRegistered | ( | void | ) |
Check whether or not QTM services are registered.
Result qtmClearIrLedOverrides | ( | void | ) |
Attempts to clear IR LED overrides from any of the relevant commands in qtm:u
, qtm:s
(and qtm:c
) commands by calling QTMU_EnableManualIrLedControl followed by QTMU_DisableManualIrLedControl, so that auto IR LED management takes place again.
float qtmComputeFovX | ( | const QtmTrackingData * | data | ) |
Computes an approximation of the horizontal angular field of view of the camera based on eye tracking data.
data | Eye tracking data, obtained from QTMU_GetTrackingData or QTMU_GetTrackingDataEx. |
float qtmComputeFovY | ( | const QtmTrackingData * | data | ) |
Computes an approximation of the vertical angular field of view of the camera based on eye tracking data.
data | Eye tracking data, obtained from QTMU_GetTrackingData or QTMU_GetTrackingDataEx. |
float qtmComputeHeadTiltAngle | ( | const QtmTrackingData * | data | ) |
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.
data | Eye tracking data, obtained from QTMU_GetTrackingData or QTMU_GetTrackingDataEx. |
float qtmComputeInverseAspectRatio | ( | const QtmTrackingData * | data | ) |
Computes a rough approximation of the inverse of the aspect ration of the camera based on eye tracking data.
data | Eye tracking data, obtained from QTMU_GetTrackingData or QTMU_GetTrackingDataEx. |
float qtmEstimateEyeToCameraDistance | ( | const QtmTrackingData * | data | ) |
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.
data | Eye tracking data, obtained from QTMU_GetTrackingData or QTMU_GetTrackingDataEx. |
Result qtmInit | ( | QtmServiceName | serviceName | ) |
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 QtmServiceName enum value descriptions to see which service to choose.
serviceName | QTM service name enum value (corresponding to qtm:u , qtm:s and qtm:sp respectively). |
Result QTMS_DisableAutoBarrierControl | ( | void | ) |
Temporarily disables automatic barrier control (when in 3D mode with "super stable 3D" enabled).
qtm:s
and qtm:sp
session exit. 0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise 0 (success). Result QTMS_EnableAutoBarrierControl | ( | void | ) |
Enables automatic barrier control when in 3D mode with "super stable 3D" enabled.
qtm:s
and qtm:sp
session exit. 0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise 0 (success). Result QTMS_GetCameraLuminance | ( | float * | outLuminanceLux | ) |
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.
[out] | outLuminanceLux | Where to write the luminance to. Always 400.0 on N2DSXL. |
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.
[out] | outPosition | Where to write the barrier's position to. |
0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise 0 (success). outPosition
. When in 2D mode, the returned position is not updated. outPosition
. Gets the current QTM status (enabled/ss3d disabled/unavailable).
[out] | outQtmStatus | Where to write the QTM status to. |
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.
position | Parallax barrier position (offset in units), must be between 0 and 11 (both included) |
0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), 0xE0E18002 if position
is not in range, otherwise 0 (success). Result QTMS_SetCalibrationData | ( | const QtmCalibrationData * | cal, |
bool | saveCalToCfg | ||
) |
Sets calibration data, taking effect immediately, and optionally saves it to cfg
.
cal | Pointer to calibration data. |
saveCalToCfg | Whether or not to persist the calibration data in cfg . |
0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise whatever cfg:s
commands return (if used), or 0 (success). cfg
. Result QTMS_SetCenterBarrierPosition | ( | float | position | ) |
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).
position | Center barrier position, in terms of iod/12 units modulo iod/12. |
0xC8A18009
if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL), otherwise 0 (success). Result QTMS_SetIrLedStatusOverride | ( | bool | on | ) |
Temporarily overrides IR LED state.
Requires "manual control" from qtm:u
to be disabled, and has lower priority than it.
on | Whether to turn the IR LED on or off. |
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). Gets the current QTM status (enabled/ss3d disabled/unavailable).
Also sets or clear the "blacklisted" flag returned by QTMU_IsCurrentAppBlacklisted.
qtmStatus | QTM status to set. If equal to QTM_STATUS_UNAVAILABLE, sets the "blacklisted" flag, otherwise clears it. |
0xE0E18002
if enum value is invalid, otherwise 0 (success). Result QTMSP_IsExpanderInUse | ( | bool * | outActive | ) |
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.
[out] | outActive | Where to write the "in use" status to. |
Called by GSP's LCD driver to signal 2D<>3D mode change.
newMode | 0 for 2D, 1 for 800px 2D (unused for this function, same as 0), 2 for 3D |
Result QTMSP_NotifyTopLcdPowerOff | ( | void | ) |
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.
Result QTMSP_NotifyTopLcdPowerOn | ( | void | ) |
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.
Result QTMU_DisableManualIrLedControl | ( | void | ) |
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.
Result QTMU_EnableManualIrLedControl | ( | void | ) |
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.
|
inlinestatic |
Gets the current raw eye tracking data.
[out] | outData | Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized). |
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. Result QTMU_GetRawTrackingDataEx | ( | QtmRawTrackingData * | outData, |
s64 | predictionTimePointOrZero | ||
) |
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).
[out] | outData | Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized). |
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. |
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.
|
inlinestatic |
Gets the current normalized eye tracking data, made suitable for 3D programming.
[out] | outData | Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized). |
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. Result QTMU_GetTrackingDataEx | ( | QtmTrackingData * | outData, |
s64 | predictionTimePointOrZero | ||
) |
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).
[out] | outData | Where to write the raw tracking data to. Cleared to all-zero on failure (instead of being left uninitialized). |
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. |
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. Result QTMU_IsCurrentAppBlacklisted | ( | bool * | outBlacklisted | ) |
Checks whether or not QTM has been blacklisted, ie.
that it has been made unavailable. In detail, this means that the last call to QTMS_SetQtmStatus was made with argument QTM_STATUS_UNAVAILABLE, usually by NS. This feature seems to only be used for some internal test titles.
[out] | outBlacklisted | Whether or not QTM is unavailable. Always true on N2DSXL. |
Result QTMU_SetIrLedStatus | ( | bool | on | ) |
Turns the IR LED on or off during manual control.
QTMU_EnableManualIrLedControl must have been called.
on | Whether to turn the IR LED on or off. |
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).