libctru  v2.4.1
qtmc.h
Go to the documentation of this file.
1 /**
2  * @file qtmc.h
3  * @brief QTM Hardware Check service.
4  *
5  * Allows direct control over the parallax barrier's pattern and polarity phase through the
6  * TI TCA6416A I2C->Parallel expander, as well as control over IR LED state even when camera
7  * is used by user.
8  *
9  * TI TCA6416A I2C->Parallel expander is located on bus I2C1 (PA 0x10161000) device ID 0x40.
10  *
11  * The top screen parallax barrier was covered by patent US20030234980A1.
12  */
13 #pragma once
14 
15 #include <3ds/types.h>
16 
17 /**
18  * @brief Initializes `qtm:c`.
19  * Only 3 sessions (2 until 9.3.0 sysupdate) for ALL services COMBINED, including the main
20  * services, can be open at a time.
21  */
23 
24 /// Exits `qtm:c`.
25 void qtmcExit(void);
26 
27 /// Returns a pointer to the current `qtm:c` session handle.
29 
30 /**
31  * @brief Starts the QTM Hardware Check API. This must be called before using any other `qtm:c` command,
32  * and causes barrier pattern to be overriden by what was last set in \ref QTMC_SetBarrierPattern,
33  * **even in 2D mode**. Also allows IR LED state to be overridden even if user uses the inner camera.
34  * @return `0xD82183F9` if already started, otherwise 0 (success).
35  */
37 
38 /**
39  * @brief Stops the QTM Hardware Check API. Restore normal barrier and IR LED management behavior.
40  * @return `0xD82183F8` if API not started, otherwise 0 (success).
41  */
43 
44 /**
45  * @brief Sets the parallax barrier's mask pattern and polarity phase (12+1 bits).
46  *
47  * Bit11 to 0 correspond to a repeating barrier mask pattern, 0 meaning the corresponding mask unit is
48  * transparent and 1 that it is opaque. The direction is: left->right corresponds to MSB->LSB.
49  *
50  * Bit12 is the polarity bit.
51  *
52  * QTM's expander management thread repeatedly writes (on every loop iteration) the current mask pattern
53  * plus polarity bit, whether it is normally set or overridden by `qtm:c`, then on the following set,
54  * negates both (it writes pattern ^ 0x1FFF). This is done at all times, even it 2D mode.
55  *
56  * The register being written to are regId 0x02 and 0x03 (output ports).
57  * TI TCA6416A I2C->Parallel expander is located on bus I2C1 (PA 0x10161000) device ID 0x40.
58  *
59  * This function has no effect on N2DSXL.
60  *
61  * @param pattern Barrier mask pattern (bit12: polarity, bit11-0: 12-bit mask pattern)
62  * @return `0xD82183F8` if API not started, otherwise 0 (success).
63  * @see Patent US20030234980A1 for a description of parallax barriers.
64  * @example The mask pattern used for super-stable 3D are as follows (position 0 to 11):
65  *
66  * 000011111100
67  * 000001111110
68  * 000000111111
69  * 100000011111
70  * 110000001111
71  * 111000000111
72  * 111100000011
73  * 111110000001
74  * 111111000000
75  * 011111100000
76  * 001111110000
77  * 000111111000
78  *
79  * When SS3D is disabled (ie. it tries to match O3DS behavior), then pattern becomes:
80  * 111100000111
81  * Notice that the slit width is reduced from 6 to 5 units there.
82  *
83  * For 2D it is all-zero:
84  * 000000000000
85  *
86  * 2D pattern is automatically set on QTM process init and exit.
87  */
88 Result QTMC_SetBarrierPattern(u32 pattern);
89 
90 /**
91  * @brief Waits for the expander management thread to (re)initalize the TI TCA6416A I2C->Parallel expander,
92  * then checks if that expander is behaving as expected (responds with the port direction config
93  * it has been configured with): it checks whether all ports have been configured as outputs.
94  *
95  * On N2DSXL, this function waits forever and never returns.
96  *
97  * In detail, the hardware init procedure for the expander is as follows (as done by the expander mgmt. thread):
98  * - configure enable expander pin on SoC: set GPIO3.bit11 to OUTPUT, then set to 1
99  * - on the expander (I2C1 deviceId 0x40), set all ports to OUTPUT (regId 0x06, 0x07)
100  * - on the expander, write 0 (all-transparent mask/2D) to the data registers (regId 0x02, 0x03)
101  *
102  * @param[out] outWorking Where to write the working status to. If true, expander is present working.
103  * If false, the expander is present but is misbehaving. If the function does not
104  * return, then expander is missing (e.g. on N2DSXL).
105  * @return `0xD82183F8` if API not started, otherwise 0 (success).
106  */
108 
109 /**
110  * @brief Temporarily overrides IR LED state. Requires "manual control" from `qtm:u` to be disabled, and has
111  * lower priority than it. Same implementation as \ref QTMS_SetIrLedStatusOverride.
112  *
113  * @param on Whether to turn the IR LED on or off.
114  * @return `0xD82183F8` if API not started, `0xC8A18005` if manual control was enabled or if the operation failed,
115  * or `0xC8A18009` if QTM is unavailable (in particular, QTM is always unavailable on N2DSXL). Otherwise, 0 (success).
116  */
Result QTMC_SetIrLedStatusOverride(bool on)
Temporarily overrides IR LED state.
Result qtmcInit(void)
Initializes qtm:c.
void qtmcExit(void)
Exits qtm:c.
Handle * qtmcGetSessionHandle(void)
Returns a pointer to the current qtm:c session handle.
Result QTMC_WaitAndCheckExpanderWorking(bool *outWorking)
Waits for the expander management thread to (re)initalize the TI TCA6416A I2C->Parallel expander,...
Result QTMC_StartHardwareCheck(void)
Starts the QTM Hardware Check API.
Result QTMC_StopHardwareCheck(void)
Stops the QTM Hardware Check API.
Various system types.
u32 Handle
Resource handle.
Definition: types.h:41
s32 Result
Function result.
Definition: types.h:42
uint32_t u32
32-bit unsigned integer
Definition: types.h:23