ponkan-python 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ponkan_python-0.1.0.dist-info/METADATA +157 -0
- ponkan_python-0.1.0.dist-info/RECORD +39 -0
- ponkan_python-0.1.0.dist-info/WHEEL +4 -0
- ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
- ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
- ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
- py3dscapture/__init__.py +36 -0
- py3dscapture/artifacts.py +66 -0
- py3dscapture/capture.py +599 -0
- py3dscapture/devices/__init__.py +1 -0
- py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- py3dscapture/errors.py +120 -0
- py3dscapture/hardware_gate.py +143 -0
- py3dscapture/image/__init__.py +1 -0
- py3dscapture/image/frame.py +166 -0
- py3dscapture/protocol/__init__.py +1 -0
- py3dscapture/protocol/layout_3ds.py +60 -0
- py3dscapture/protocol/n3dsxl.py +249 -0
- py3dscapture/protocol/sizes.py +128 -0
- py3dscapture/py.typed +1 -0
- py3dscapture/streaming/__init__.py +1 -0
- py3dscapture/streaming/buffers.py +156 -0
- py3dscapture/streaming/engine.py +285 -0
- py3dscapture/streaming/policies.py +157 -0
- py3dscapture/streaming/stats.py +254 -0
- py3dscapture/tools/__init__.py +1 -0
- py3dscapture/tools/capture_raw.py +44 -0
- py3dscapture/tools/list_devices.py +68 -0
- py3dscapture/tools/raw_to_png.py +251 -0
- py3dscapture/tools/stream_n3dsxl.py +152 -0
- py3dscapture/transport/__init__.py +1 -0
- py3dscapture/transport/d3xx_backend.py +850 -0
- py3dscapture/transport/d3xx_native.py +268 -0
- py3dscapture/transport/d3xx_native_streaming.py +306 -0
- py3dscapture/transport/d3xx_streaming.py +202 -0
- py3dscapture/transport/ftd3_backend.py +275 -0
- py3dscapture/transport/ftd3_pipe.py +387 -0
- py3dscapture/transport/libusb_async.py +134 -0
- py3dscapture/transport/libusb_backend.py +357 -0
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""3DS RGB8 raw video layout decoders."""
|
|
2
|
+
|
|
3
|
+
import numpy as np
|
|
4
|
+
|
|
5
|
+
from py3dscapture.errors import DecodeError
|
|
6
|
+
from py3dscapture.image.frame import CaptureFrame
|
|
7
|
+
from py3dscapture.protocol.sizes import (
|
|
8
|
+
BOTTOM_WIDTH_3DS,
|
|
9
|
+
HEIGHT_3DS,
|
|
10
|
+
TOP_WIDTH_3DS,
|
|
11
|
+
video_size,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
APPROVED_N3DSXL_2D_DECODER_ID = "ftd3_cc3dsfs_2d"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def decode_rgb8_2d(raw_video: bytes | memoryview) -> CaptureFrame:
|
|
18
|
+
"""Decode 2D N3DSXL raw RGB8 bytes into top and bottom screens.
|
|
19
|
+
|
|
20
|
+
Args:
|
|
21
|
+
raw_video: Exact 2D RGB8 video region from an N3DSXL raw capture. The
|
|
22
|
+
input must not include audio, unused, or error-buffer bytes.
|
|
23
|
+
|
|
24
|
+
Returns:
|
|
25
|
+
A decoded RGB ``CaptureFrame`` with top and bottom screens populated.
|
|
26
|
+
|
|
27
|
+
Raises:
|
|
28
|
+
DecodeError: The input length does not match the 2D video payload size.
|
|
29
|
+
"""
|
|
30
|
+
raw_bytes = bytes(raw_video)
|
|
31
|
+
if len(raw_bytes) != video_size(mode_3d=False):
|
|
32
|
+
raise DecodeError
|
|
33
|
+
|
|
34
|
+
stacked = np.frombuffer(raw_bytes, dtype=np.uint8).reshape(
|
|
35
|
+
(TOP_WIDTH_3DS + BOTTOM_WIDTH_3DS, HEIGHT_3DS, 3)
|
|
36
|
+
)
|
|
37
|
+
top_source, bottom_source = _split_ftd3_2d_source(stacked)
|
|
38
|
+
return CaptureFrame(
|
|
39
|
+
top=_transform_2d_source(top_source),
|
|
40
|
+
bottom=_transform_2d_source(bottom_source),
|
|
41
|
+
top_right=None,
|
|
42
|
+
timestamp_ns=None,
|
|
43
|
+
source_model="new_3ds_xl",
|
|
44
|
+
mode_3d=False,
|
|
45
|
+
colorspace="RGB",
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _split_ftd3_2d_source(source: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
|
|
50
|
+
width_delta = TOP_WIDTH_3DS - BOTTOM_WIDTH_3DS
|
|
51
|
+
top_source = np.empty((TOP_WIDTH_3DS, HEIGHT_3DS, 3), dtype=np.uint8)
|
|
52
|
+
bottom_source = np.empty((BOTTOM_WIDTH_3DS, HEIGHT_3DS, 3), dtype=np.uint8)
|
|
53
|
+
top_source[:width_delta] = source[:width_delta]
|
|
54
|
+
bottom_source[:] = source[width_delta::2]
|
|
55
|
+
top_source[width_delta:] = source[width_delta + 1 :: 2]
|
|
56
|
+
return top_source, bottom_source
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _transform_2d_source(source: np.ndarray) -> np.ndarray:
|
|
60
|
+
return np.rot90(source, k=1).copy()
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
"""N3DSXL protocol orchestration."""
|
|
2
|
+
|
|
3
|
+
from time import sleep
|
|
4
|
+
from typing import Protocol
|
|
5
|
+
|
|
6
|
+
from py3dscapture.capture import RawCapture
|
|
7
|
+
from py3dscapture.devices.n3dsxl_ftd3 import DeviceCandidate
|
|
8
|
+
from py3dscapture.errors import UnsupportedDevice, UnsupportedOperation
|
|
9
|
+
from py3dscapture.protocol.sizes import (
|
|
10
|
+
N3DSXL_BULK_IN_ENDPOINT,
|
|
11
|
+
N3DSXL_BULK_OUT_ENDPOINT,
|
|
12
|
+
capture_size,
|
|
13
|
+
video_size,
|
|
14
|
+
)
|
|
15
|
+
from py3dscapture.transport.ftd3_pipe import FTD3_COMMAND_TIMEOUT_MS
|
|
16
|
+
|
|
17
|
+
N3DSXL_CFG_WAIT_MS = 200
|
|
18
|
+
N3DSXL_RAW_FRAME_READ_ATTEMPTS = 8
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class N3DSXLPipe(Protocol):
|
|
22
|
+
"""FTD3 operations used by the N3DSXL protocol layer.
|
|
23
|
+
|
|
24
|
+
Implementations may wrap libusb command payloads or the native FTDI D3XX
|
|
25
|
+
API, but they must expose the same pipe-level behavior to the protocol
|
|
26
|
+
sequence.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
backend_kind: str
|
|
30
|
+
|
|
31
|
+
def create_pipe(self) -> None:
|
|
32
|
+
"""Create the FTD3 command pipe.
|
|
33
|
+
|
|
34
|
+
Raises:
|
|
35
|
+
Ftd3CommandError: The backend cannot create or emulate the command
|
|
36
|
+
pipe.
|
|
37
|
+
"""
|
|
38
|
+
...
|
|
39
|
+
|
|
40
|
+
def abort_pipe(self, pipe: int) -> None:
|
|
41
|
+
"""Abort one FTD3 pipe.
|
|
42
|
+
|
|
43
|
+
Args:
|
|
44
|
+
pipe: Bulk pipe or endpoint ID to abort.
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
Ftd3CommandError: The backend reports a pipe abort failure.
|
|
48
|
+
"""
|
|
49
|
+
...
|
|
50
|
+
|
|
51
|
+
def set_stream_pipe(self, pipe: int, length: int) -> None:
|
|
52
|
+
"""Set the stream pipe transfer length.
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
pipe: Bulk pipe or endpoint ID to configure.
|
|
56
|
+
length: Transfer length in bytes for streaming reads.
|
|
57
|
+
|
|
58
|
+
Raises:
|
|
59
|
+
Ftd3CommandError: The backend rejects the stream configuration.
|
|
60
|
+
"""
|
|
61
|
+
...
|
|
62
|
+
|
|
63
|
+
def read_pipe(self, pipe: int, length: int, timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS) -> bytes:
|
|
64
|
+
"""Read from one FTD3 pipe.
|
|
65
|
+
|
|
66
|
+
Args:
|
|
67
|
+
pipe: Bulk pipe or endpoint ID to read.
|
|
68
|
+
length: Maximum number of bytes to read.
|
|
69
|
+
timeout_ms: Backend read timeout in milliseconds.
|
|
70
|
+
|
|
71
|
+
Returns:
|
|
72
|
+
Bytes transferred by the backend.
|
|
73
|
+
|
|
74
|
+
Raises:
|
|
75
|
+
Ftd3CommandError: The backend read or required prepare step fails.
|
|
76
|
+
"""
|
|
77
|
+
...
|
|
78
|
+
|
|
79
|
+
def write_pipe(
|
|
80
|
+
self,
|
|
81
|
+
pipe: int,
|
|
82
|
+
payload: bytes,
|
|
83
|
+
timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS,
|
|
84
|
+
) -> int:
|
|
85
|
+
"""Write to one FTD3 pipe.
|
|
86
|
+
|
|
87
|
+
Args:
|
|
88
|
+
pipe: Bulk pipe or endpoint ID to write.
|
|
89
|
+
payload: Bytes to send.
|
|
90
|
+
timeout_ms: Backend write timeout in milliseconds.
|
|
91
|
+
|
|
92
|
+
Returns:
|
|
93
|
+
Number of payload bytes transferred.
|
|
94
|
+
|
|
95
|
+
Raises:
|
|
96
|
+
Ftd3CommandError: The backend write or required prepare step fails.
|
|
97
|
+
"""
|
|
98
|
+
...
|
|
99
|
+
|
|
100
|
+
def reconnect_after_drain(self) -> None:
|
|
101
|
+
"""Reconnect after the initial drain when the backend requires it.
|
|
102
|
+
|
|
103
|
+
D3XX follows cc3dsfs by closing and reopening after the initial drain;
|
|
104
|
+
libusb keeps the current session.
|
|
105
|
+
"""
|
|
106
|
+
...
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class N3DSXLSessionIdentity(Protocol):
|
|
110
|
+
"""Opened session identity needed for raw metadata.
|
|
111
|
+
|
|
112
|
+
Attributes:
|
|
113
|
+
candidate: Accepted N3DSXL candidate for artifact metadata.
|
|
114
|
+
"""
|
|
115
|
+
|
|
116
|
+
candidate: DeviceCandidate
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class N3DSXLProtocol:
|
|
120
|
+
"""N3DSXL connect sequence over an accepted device and FTD3 pipe.
|
|
121
|
+
|
|
122
|
+
The protocol assumes device classification and human hardware-command
|
|
123
|
+
approval have already happened outside this class.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
def __init__(self, device: N3DSXLSessionIdentity, pipe: N3DSXLPipe) -> None:
|
|
127
|
+
"""Create protocol orchestration for one safe device session.
|
|
128
|
+
|
|
129
|
+
Args:
|
|
130
|
+
device: Opened session identity with an accepted N3DSXL candidate.
|
|
131
|
+
pipe: FTD3 pipe implementation used for command and bulk transfer.
|
|
132
|
+
|
|
133
|
+
Raises:
|
|
134
|
+
UnsupportedDevice: ``device.candidate`` is not an accepted
|
|
135
|
+
``DeviceCandidate``.
|
|
136
|
+
"""
|
|
137
|
+
if not isinstance(device.candidate, DeviceCandidate):
|
|
138
|
+
raise UnsupportedDevice
|
|
139
|
+
self.device = device
|
|
140
|
+
self.pipe = pipe
|
|
141
|
+
|
|
142
|
+
def connect(self, *, mode_3d: bool = False) -> None:
|
|
143
|
+
"""Run the 2D default connect and stream setup sequence.
|
|
144
|
+
|
|
145
|
+
Args:
|
|
146
|
+
mode_3d: Requested capture mode. 3D mode is outside the current MVP
|
|
147
|
+
and is rejected.
|
|
148
|
+
|
|
149
|
+
Raises:
|
|
150
|
+
UnsupportedOperation: ``mode_3d`` is true.
|
|
151
|
+
Ftd3CommandError: Any FTD3 setup command or transfer fails.
|
|
152
|
+
"""
|
|
153
|
+
if mode_3d:
|
|
154
|
+
raise UnsupportedOperation
|
|
155
|
+
|
|
156
|
+
self.pipe.create_pipe()
|
|
157
|
+
self._drain_data()
|
|
158
|
+
self.pipe.reconnect_after_drain()
|
|
159
|
+
self.pipe.abort_pipe(N3DSXL_BULK_IN_ENDPOINT)
|
|
160
|
+
self.pipe.create_pipe()
|
|
161
|
+
self._spi_3ds_cc_stuff()
|
|
162
|
+
self._load_3ds_cc_firmware(firmware_id=1)
|
|
163
|
+
self._read_3ds_config_3d()
|
|
164
|
+
self._set_2d_stream_pipe()
|
|
165
|
+
|
|
166
|
+
def read_raw_frame(self, *, mode_3d: bool = False) -> RawCapture:
|
|
167
|
+
"""Read one raw frame after connect.
|
|
168
|
+
|
|
169
|
+
Args:
|
|
170
|
+
mode_3d: Requested capture mode. 3D mode is outside the current MVP
|
|
171
|
+
and is rejected.
|
|
172
|
+
|
|
173
|
+
Returns:
|
|
174
|
+
Raw capture payload with N3DSXL identity metadata attached.
|
|
175
|
+
|
|
176
|
+
Raises:
|
|
177
|
+
UnsupportedOperation: ``mode_3d`` is true.
|
|
178
|
+
Ftd3CommandError: Bulk read through the selected backend fails.
|
|
179
|
+
DecodeError: The resulting raw capture is shorter than the expected
|
|
180
|
+
video region.
|
|
181
|
+
TransferOverflow: The backend reports more than the 2D capture size.
|
|
182
|
+
"""
|
|
183
|
+
if mode_3d:
|
|
184
|
+
raise UnsupportedOperation
|
|
185
|
+
transfer_size = capture_size(mode_3d=False)
|
|
186
|
+
expected_video_size = video_size(mode_3d=False)
|
|
187
|
+
payload = b""
|
|
188
|
+
for _ in range(N3DSXL_RAW_FRAME_READ_ATTEMPTS):
|
|
189
|
+
payload = self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, transfer_size)
|
|
190
|
+
if len(payload) >= expected_video_size:
|
|
191
|
+
break
|
|
192
|
+
return RawCapture(
|
|
193
|
+
model="new_3ds_xl",
|
|
194
|
+
mode_3d=False,
|
|
195
|
+
payload=payload,
|
|
196
|
+
transferred=len(payload),
|
|
197
|
+
video_size=expected_video_size,
|
|
198
|
+
capture_size=transfer_size,
|
|
199
|
+
timestamp_ns=None,
|
|
200
|
+
sequence=None,
|
|
201
|
+
metadata={
|
|
202
|
+
"product_string": self.device.candidate.product_string,
|
|
203
|
+
"product_string_status": self.device.candidate.product_string_status,
|
|
204
|
+
"backend_kind": self.pipe.backend_kind,
|
|
205
|
+
"vid": f"0x{self.device.candidate.info.vendor_id:04x}",
|
|
206
|
+
"pid": f"0x{self.device.candidate.info.product_id:04x}",
|
|
207
|
+
},
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
def _drain_data(self) -> None:
|
|
211
|
+
self._set_spi_access(enabled=True)
|
|
212
|
+
self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x100000, timeout_ms=N3DSXL_CFG_WAIT_MS)
|
|
213
|
+
|
|
214
|
+
def _spi_3ds_cc_stuff(self) -> None:
|
|
215
|
+
self._set_spi_access(enabled=True)
|
|
216
|
+
self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x80, 0x01, 0xAB, 0x00]))
|
|
217
|
+
self.pipe.write_pipe(
|
|
218
|
+
N3DSXL_BULK_OUT_ENDPOINT,
|
|
219
|
+
bytes([0x90, 0x08, 0x03, 0x02, 0x00, 0x00, 0x00, 0x00]),
|
|
220
|
+
)
|
|
221
|
+
self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x10)
|
|
222
|
+
self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x80, 0x01, 0xAB, 0x00]))
|
|
223
|
+
self._set_spi_access(enabled=False)
|
|
224
|
+
|
|
225
|
+
def _load_3ds_cc_firmware(self, *, firmware_id: int) -> None:
|
|
226
|
+
firmware_to_use = min(firmware_id, 1)
|
|
227
|
+
self._set_spi_access(enabled=True)
|
|
228
|
+
self.pipe.write_pipe(
|
|
229
|
+
N3DSXL_BULK_OUT_ENDPOINT,
|
|
230
|
+
bytes([0x42 + firmware_to_use, 0x00, 0x00, 0x00]),
|
|
231
|
+
)
|
|
232
|
+
sleep(N3DSXL_CFG_WAIT_MS / 1000)
|
|
233
|
+
self._set_spi_access(enabled=False)
|
|
234
|
+
|
|
235
|
+
def _read_3ds_config_3d(self) -> None:
|
|
236
|
+
self._set_spi_access(enabled=True)
|
|
237
|
+
self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x98, 0x05, 0x9F, 0x00]))
|
|
238
|
+
self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x10)
|
|
239
|
+
self._set_spi_access(enabled=False)
|
|
240
|
+
|
|
241
|
+
def _set_2d_stream_pipe(self) -> None:
|
|
242
|
+
length = capture_size(mode_3d=False)
|
|
243
|
+
self.pipe.set_stream_pipe(N3DSXL_BULK_IN_ENDPOINT, length)
|
|
244
|
+
self.pipe.abort_pipe(N3DSXL_BULK_IN_ENDPOINT)
|
|
245
|
+
self.pipe.set_stream_pipe(N3DSXL_BULK_IN_ENDPOINT, length)
|
|
246
|
+
|
|
247
|
+
def _set_spi_access(self, *, enabled: bool) -> None:
|
|
248
|
+
second_byte = 0x80 if enabled else 0x00
|
|
249
|
+
self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x40, second_byte, 0x00, 0x00]))
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
"""N3DSXL capture constants and raw frame size calculations."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Final
|
|
5
|
+
|
|
6
|
+
N3DSXL_VENDOR_ID: Final = 0x0403
|
|
7
|
+
ACCEPTED_N3DSXL_PRODUCT_IDS: Final[frozenset[int]] = frozenset(
|
|
8
|
+
{0x601E, 0x601F, 0x602A, 0x602B, 0x602C, 0x602D, 0x602F}
|
|
9
|
+
)
|
|
10
|
+
ACCEPTED_N3DSXL_PRODUCT_STRINGS: Final[frozenset[str]] = frozenset({"N3DSXL", "N3DSXL.2"})
|
|
11
|
+
|
|
12
|
+
N3DSXL_COMMAND_INTERFACE: Final = 0
|
|
13
|
+
N3DSXL_BULK_INTERFACE: Final = 1
|
|
14
|
+
N3DSXL_BULK_OUT_ENDPOINT: Final = 0x02
|
|
15
|
+
N3DSXL_BULK_IN_ENDPOINT: Final = 0x82
|
|
16
|
+
N3DSXL_FTD3_COMMAND_PIPE_ID: Final = 0x01
|
|
17
|
+
N3DSXL_DEFAULT_CONFIGURATION: Final = 1
|
|
18
|
+
|
|
19
|
+
TOP_WIDTH_3DS: Final = 400
|
|
20
|
+
BOTTOM_WIDTH_3DS: Final = 320
|
|
21
|
+
HEIGHT_3DS: Final = 240
|
|
22
|
+
RGB8_CHANNELS: Final = 3
|
|
23
|
+
|
|
24
|
+
N3DSXL_SAMPLES_IN: Final = 1096 * 16
|
|
25
|
+
AUDIO_SAMPLE_BYTES: Final = 2
|
|
26
|
+
AUDIO_SIZE_BYTES: Final = N3DSXL_SAMPLES_IN * AUDIO_SAMPLE_BYTES
|
|
27
|
+
UNUSED_BUFFER_SIZE_BYTES: Final = 1024
|
|
28
|
+
ERROR_BUFFER_SIZE_BYTES: Final = 1024
|
|
29
|
+
USB_CAPTURE_ALIGNMENT_BYTES: Final = 1024
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True, slots=True)
|
|
33
|
+
class CaptureSizes:
|
|
34
|
+
"""Calculated raw capture sizes for one transfer mode.
|
|
35
|
+
|
|
36
|
+
Attributes:
|
|
37
|
+
mode_3d: Whether these values describe the N3DSXL 3D transfer layout.
|
|
38
|
+
video_size: RGB8 video payload bytes at the start of a transfer.
|
|
39
|
+
audio_size: Audio buffer bytes present in the cc3dsfs structure.
|
|
40
|
+
struct_total_before_1024_floor: Size before the cc3dsfs 1024-byte floor
|
|
41
|
+
operation.
|
|
42
|
+
capture_size: Bulk transfer size after 1024-byte alignment flooring.
|
|
43
|
+
max_non_error_transferred: Largest transfer length that does not overlap
|
|
44
|
+
the error buffer.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
mode_3d: bool
|
|
48
|
+
video_size: int
|
|
49
|
+
audio_size: int
|
|
50
|
+
struct_total_before_1024_floor: int
|
|
51
|
+
capture_size: int
|
|
52
|
+
max_non_error_transferred: int
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def video_size(mode_3d: bool) -> int:
|
|
56
|
+
"""Return RGB8 video payload bytes for 2D or 3D mode.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
mode_3d: Include the right-eye top screen when true.
|
|
60
|
+
|
|
61
|
+
Returns:
|
|
62
|
+
Number of RGB8 video bytes before audio, unused, and error buffers.
|
|
63
|
+
"""
|
|
64
|
+
stacked_screen_width = TOP_WIDTH_3DS + BOTTOM_WIDTH_3DS
|
|
65
|
+
if mode_3d:
|
|
66
|
+
stacked_screen_width += TOP_WIDTH_3DS
|
|
67
|
+
return HEIGHT_3DS * stacked_screen_width * RGB8_CHANNELS
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def struct_total_before_1024_floor(mode_3d: bool) -> int:
|
|
71
|
+
"""Return the C capture struct size before cc3dsfs' 1024-byte floor operation.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
mode_3d: Include the right-eye top screen when true.
|
|
75
|
+
|
|
76
|
+
Returns:
|
|
77
|
+
Sum of video, audio, unused, and error-buffer bytes before USB transfer
|
|
78
|
+
alignment is applied.
|
|
79
|
+
"""
|
|
80
|
+
return (
|
|
81
|
+
video_size(mode_3d) + AUDIO_SIZE_BYTES + UNUSED_BUFFER_SIZE_BYTES + ERROR_BUFFER_SIZE_BYTES
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def capture_size(mode_3d: bool) -> int:
|
|
86
|
+
"""Return the transfer size after the 1024-byte floor operation.
|
|
87
|
+
|
|
88
|
+
Args:
|
|
89
|
+
mode_3d: Include the right-eye top screen when true.
|
|
90
|
+
|
|
91
|
+
Returns:
|
|
92
|
+
Bulk transfer length used by the N3DSXL read path.
|
|
93
|
+
"""
|
|
94
|
+
total = struct_total_before_1024_floor(mode_3d)
|
|
95
|
+
return (total // USB_CAPTURE_ALIGNMENT_BYTES) * USB_CAPTURE_ALIGNMENT_BYTES
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def max_non_error_transferred(mode_3d: bool) -> int:
|
|
99
|
+
"""Return the largest transfer length that does not enter the error buffer.
|
|
100
|
+
|
|
101
|
+
Args:
|
|
102
|
+
mode_3d: Include the right-eye top screen when true.
|
|
103
|
+
|
|
104
|
+
Returns:
|
|
105
|
+
Transfer byte count threshold before the cc3dsfs error buffer starts.
|
|
106
|
+
"""
|
|
107
|
+
return capture_size(mode_3d) - ERROR_BUFFER_SIZE_BYTES
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def capture_sizes(mode_3d: bool) -> CaptureSizes:
|
|
111
|
+
"""Return all calculated size values for one transfer mode.
|
|
112
|
+
|
|
113
|
+
Args:
|
|
114
|
+
mode_3d: Include the right-eye top screen when true.
|
|
115
|
+
|
|
116
|
+
Returns:
|
|
117
|
+
Immutable grouped size values for metadata and characterization tests.
|
|
118
|
+
"""
|
|
119
|
+
total = struct_total_before_1024_floor(mode_3d)
|
|
120
|
+
transfer_size = capture_size(mode_3d)
|
|
121
|
+
return CaptureSizes(
|
|
122
|
+
mode_3d=mode_3d,
|
|
123
|
+
video_size=video_size(mode_3d),
|
|
124
|
+
audio_size=AUDIO_SIZE_BYTES,
|
|
125
|
+
struct_total_before_1024_floor=total,
|
|
126
|
+
capture_size=transfer_size,
|
|
127
|
+
max_non_error_transferred=transfer_size - ERROR_BUFFER_SIZE_BYTES,
|
|
128
|
+
)
|
py3dscapture/py.typed
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Streaming engine components."""
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Raw streaming buffer pool."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass, field
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
@dataclass(slots=True)
|
|
7
|
+
class RawFrameSlot:
|
|
8
|
+
"""One reusable raw transfer slot.
|
|
9
|
+
|
|
10
|
+
Attributes:
|
|
11
|
+
index: Stable slot index used by backend callbacks.
|
|
12
|
+
buffer: Mutable byte storage owned by the pool.
|
|
13
|
+
view: Stable memoryview over ``buffer`` for zero-copy backend writes.
|
|
14
|
+
in_use: Whether the slot is checked out by an in-flight transfer.
|
|
15
|
+
submitted_ns: Optional monotonic timestamp when the transfer was queued.
|
|
16
|
+
backend_started_ns: Optional monotonic timestamp when the backend worker
|
|
17
|
+
started the actual read.
|
|
18
|
+
completed_ns: Optional monotonic timestamp when the transfer completed.
|
|
19
|
+
transferred: Bytes reported by the backend.
|
|
20
|
+
sequence: Optional streaming sequence assigned at submission time.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
index: int
|
|
24
|
+
buffer: bytearray
|
|
25
|
+
view: memoryview = field(init=False)
|
|
26
|
+
in_use: bool = False
|
|
27
|
+
submitted_ns: int | None = None
|
|
28
|
+
backend_started_ns: int | None = None
|
|
29
|
+
completed_ns: int | None = None
|
|
30
|
+
transferred: int = 0
|
|
31
|
+
sequence: int | None = None
|
|
32
|
+
|
|
33
|
+
def __post_init__(self) -> None:
|
|
34
|
+
"""Create a stable memoryview for the slot buffer.
|
|
35
|
+
|
|
36
|
+
The view is reused for the lifetime of the slot so callbacks can refer
|
|
37
|
+
to the same memory without allocating a new memoryview per transfer.
|
|
38
|
+
"""
|
|
39
|
+
self.view = memoryview(self.buffer)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@dataclass(frozen=True, slots=True)
|
|
43
|
+
class RawFrameResult:
|
|
44
|
+
"""Completed raw transfer metadata.
|
|
45
|
+
|
|
46
|
+
Attributes:
|
|
47
|
+
slot_index: Slot that produced this result.
|
|
48
|
+
view: Memoryview containing the completed raw bytes.
|
|
49
|
+
transferred: Number of bytes reported by the backend.
|
|
50
|
+
status: Backend completion status, where zero means success.
|
|
51
|
+
submitted_ns: Monotonic submission timestamp when available.
|
|
52
|
+
backend_started_ns: Monotonic backend read-start timestamp when
|
|
53
|
+
available.
|
|
54
|
+
completed_ns: Monotonic completion timestamp.
|
|
55
|
+
sequence: Streaming sequence assigned when the read was submitted.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
slot_index: int
|
|
59
|
+
view: memoryview
|
|
60
|
+
transferred: int
|
|
61
|
+
status: int
|
|
62
|
+
submitted_ns: int | None
|
|
63
|
+
backend_started_ns: int | None
|
|
64
|
+
completed_ns: int
|
|
65
|
+
sequence: int
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class BufferPool:
|
|
69
|
+
"""Preallocated raw slot pool.
|
|
70
|
+
|
|
71
|
+
The pool keeps raw buffers stable so async backends can write into memory
|
|
72
|
+
owned by the streaming engine without allocating per transfer.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
def __init__(self, *, raw_slots: int, raw_slot_size: int) -> None:
|
|
76
|
+
"""Create fixed raw slots.
|
|
77
|
+
|
|
78
|
+
Args:
|
|
79
|
+
raw_slots: Number of reusable slots to allocate.
|
|
80
|
+
raw_slot_size: Byte size for each raw transfer buffer.
|
|
81
|
+
|
|
82
|
+
Raises:
|
|
83
|
+
ValueError: Either value is not positive.
|
|
84
|
+
"""
|
|
85
|
+
if raw_slots <= 0 or raw_slot_size <= 0:
|
|
86
|
+
raise ValueError
|
|
87
|
+
self._slots = tuple(
|
|
88
|
+
RawFrameSlot(index=index, buffer=bytearray(raw_slot_size)) for index in range(raw_slots)
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
@property
|
|
92
|
+
def slots(self) -> tuple[RawFrameSlot, ...]:
|
|
93
|
+
"""Return all slots.
|
|
94
|
+
|
|
95
|
+
Returns:
|
|
96
|
+
Tuple of pool slots in stable index order.
|
|
97
|
+
"""
|
|
98
|
+
return self._slots
|
|
99
|
+
|
|
100
|
+
def checkout(self, index: int) -> RawFrameSlot:
|
|
101
|
+
"""Mark one slot in use.
|
|
102
|
+
|
|
103
|
+
Args:
|
|
104
|
+
index: Slot index to reserve.
|
|
105
|
+
|
|
106
|
+
Returns:
|
|
107
|
+
The reserved slot.
|
|
108
|
+
|
|
109
|
+
Raises:
|
|
110
|
+
RuntimeError: The slot is already checked out.
|
|
111
|
+
IndexError: ``index`` is outside the pool.
|
|
112
|
+
"""
|
|
113
|
+
slot = self._slots[index]
|
|
114
|
+
if slot.in_use:
|
|
115
|
+
raise RuntimeError
|
|
116
|
+
slot.in_use = True
|
|
117
|
+
return slot
|
|
118
|
+
|
|
119
|
+
def release(self, index: int) -> None:
|
|
120
|
+
"""Release one slot.
|
|
121
|
+
|
|
122
|
+
Args:
|
|
123
|
+
index: Slot index to release and reset.
|
|
124
|
+
|
|
125
|
+
Raises:
|
|
126
|
+
IndexError: ``index`` is outside the pool.
|
|
127
|
+
"""
|
|
128
|
+
slot = self._slots[index]
|
|
129
|
+
slot.in_use = False
|
|
130
|
+
slot.submitted_ns = None
|
|
131
|
+
slot.backend_started_ns = None
|
|
132
|
+
slot.completed_ns = None
|
|
133
|
+
slot.transferred = 0
|
|
134
|
+
slot.sequence = None
|
|
135
|
+
|
|
136
|
+
def get(self, index: int) -> RawFrameSlot:
|
|
137
|
+
"""Return one slot by index.
|
|
138
|
+
|
|
139
|
+
Args:
|
|
140
|
+
index: Slot index to return.
|
|
141
|
+
|
|
142
|
+
Returns:
|
|
143
|
+
The slot with the requested index.
|
|
144
|
+
|
|
145
|
+
Raises:
|
|
146
|
+
IndexError: ``index`` is outside the pool.
|
|
147
|
+
"""
|
|
148
|
+
return self._slots[index]
|
|
149
|
+
|
|
150
|
+
def in_use_count(self) -> int:
|
|
151
|
+
"""Return the number of checked-out slots.
|
|
152
|
+
|
|
153
|
+
Returns:
|
|
154
|
+
Count of slots currently marked in use.
|
|
155
|
+
"""
|
|
156
|
+
return sum(1 for slot in self._slots if slot.in_use)
|