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,268 @@
|
|
|
1
|
+
"""Explicit native FTDI D3XX DLL surface for fast-path streaming."""
|
|
2
|
+
|
|
3
|
+
import ctypes
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from typing import ClassVar, Protocol, cast
|
|
6
|
+
|
|
7
|
+
from py3dscapture.errors import CaptureError
|
|
8
|
+
from py3dscapture.transport.d3xx_backend import D3xxBackendError
|
|
9
|
+
|
|
10
|
+
FT_OK = 0
|
|
11
|
+
FT_TIMEOUT = 19
|
|
12
|
+
FT_IO_PENDING = 24
|
|
13
|
+
FT_IO_INCOMPLETE = 25
|
|
14
|
+
|
|
15
|
+
FT_STATUS = ctypes.c_uint32
|
|
16
|
+
FT_HANDLE = ctypes.c_void_p
|
|
17
|
+
UCHAR = ctypes.c_ubyte
|
|
18
|
+
ULONG = ctypes.c_uint32
|
|
19
|
+
BOOL = ctypes.c_int32
|
|
20
|
+
DWORD = ctypes.c_uint32
|
|
21
|
+
HANDLE = ctypes.c_void_p
|
|
22
|
+
PULONG = ctypes.POINTER(ULONG)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class D3xxNativeHandleProvider(Protocol):
|
|
26
|
+
"""Surface used to adapt an opened D3XX handle to the native API layer."""
|
|
27
|
+
|
|
28
|
+
def pyd3xx_native_dll(self) -> object | None:
|
|
29
|
+
"""Return the loaded PyD3XX DLL object when available."""
|
|
30
|
+
...
|
|
31
|
+
|
|
32
|
+
def pyd3xx_native_handle(self) -> object:
|
|
33
|
+
"""Return the native FT_HANDLE-compatible object."""
|
|
34
|
+
...
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class NativeFunction(Protocol):
|
|
38
|
+
"""ctypes function surface used by the native API wrapper."""
|
|
39
|
+
|
|
40
|
+
argtypes: list[object]
|
|
41
|
+
restype: object
|
|
42
|
+
|
|
43
|
+
def __call__(self, *args: object) -> int:
|
|
44
|
+
"""Call the native function."""
|
|
45
|
+
...
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class D3xxNativeApiUnavailable(CaptureError): # noqa: N818
|
|
49
|
+
"""Raised when the required native D3XX DLL surface is unavailable."""
|
|
50
|
+
|
|
51
|
+
@classmethod
|
|
52
|
+
def missing_dll(cls) -> "D3xxNativeApiUnavailable":
|
|
53
|
+
"""Create an error for a missing native DLL provider."""
|
|
54
|
+
return cls("D3XX native DLL surface is unavailable")
|
|
55
|
+
|
|
56
|
+
@classmethod
|
|
57
|
+
def missing_function(cls, name: str) -> "D3xxNativeApiUnavailable":
|
|
58
|
+
"""Create an error for a missing native DLL function."""
|
|
59
|
+
return cls(f"{name} is unavailable")
|
|
60
|
+
|
|
61
|
+
@classmethod
|
|
62
|
+
def null_handle(cls) -> "D3xxNativeApiUnavailable":
|
|
63
|
+
"""Create an error for a null native handle."""
|
|
64
|
+
return cls("native D3XX handle is null")
|
|
65
|
+
|
|
66
|
+
@classmethod
|
|
67
|
+
def missing_handle(cls) -> "D3xxNativeApiUnavailable":
|
|
68
|
+
"""Create an error for a missing native handle provider."""
|
|
69
|
+
return cls("native D3XX handle is unavailable")
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class _NativeOffsetPair(ctypes.Structure):
|
|
73
|
+
_fields_: ClassVar[list[tuple[str, object]]] = [
|
|
74
|
+
("Offset", DWORD),
|
|
75
|
+
("OffsetHigh", DWORD),
|
|
76
|
+
]
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class _NativeOffsetUnion(ctypes.Union):
|
|
80
|
+
_fields_: ClassVar[list[tuple[str, object]]] = [
|
|
81
|
+
("offset_pair", _NativeOffsetPair),
|
|
82
|
+
("Pointer", ctypes.c_void_p),
|
|
83
|
+
]
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
class NativeOverlapped(ctypes.Structure):
|
|
87
|
+
"""Windows OVERLAPPED layout used by FTD3XX asynchronous pipe APIs."""
|
|
88
|
+
|
|
89
|
+
_fields_: ClassVar[list[tuple[str, object]]] = [
|
|
90
|
+
("Internal", ctypes.c_size_t),
|
|
91
|
+
("InternalHigh", ctypes.c_size_t),
|
|
92
|
+
("u", _NativeOffsetUnion),
|
|
93
|
+
("hEvent", HANDLE),
|
|
94
|
+
]
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@dataclass(frozen=True, slots=True)
|
|
98
|
+
class NativeTransferResult:
|
|
99
|
+
"""D3XX native transfer status and byte count."""
|
|
100
|
+
|
|
101
|
+
status: int
|
|
102
|
+
transferred: int
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class D3xxNativeApi:
|
|
106
|
+
"""Typed native D3XX DLL function surface.
|
|
107
|
+
|
|
108
|
+
This class owns the direct DLL calling convention. It may be constructed
|
|
109
|
+
from a PyD3XX-backed handle, but callers use this explicit API instead of
|
|
110
|
+
reaching into PyD3XX private module attributes.
|
|
111
|
+
"""
|
|
112
|
+
|
|
113
|
+
def __init__(self, dll: object, handle: object) -> None:
|
|
114
|
+
"""Create a native API wrapper over one open FT_HANDLE.
|
|
115
|
+
|
|
116
|
+
Args:
|
|
117
|
+
dll: Loaded D3XX DLL object, normally a ``ctypes.WinDLL``.
|
|
118
|
+
handle: FT_HANDLE-compatible value from the opened device.
|
|
119
|
+
|
|
120
|
+
Raises:
|
|
121
|
+
D3xxNativeApiUnavailable: Required functions or handle are missing.
|
|
122
|
+
"""
|
|
123
|
+
self._dll = dll
|
|
124
|
+
self._handle = _coerce_handle(handle)
|
|
125
|
+
self._ft_read_pipe_ex = self._bind_function(
|
|
126
|
+
"FT_ReadPipeEx",
|
|
127
|
+
[FT_HANDLE, UCHAR, ctypes.c_void_p, ULONG, PULONG, ctypes.c_void_p],
|
|
128
|
+
)
|
|
129
|
+
self._ft_get_overlapped_result = self._bind_function(
|
|
130
|
+
"FT_GetOverlappedResult",
|
|
131
|
+
[FT_HANDLE, ctypes.c_void_p, PULONG, BOOL],
|
|
132
|
+
)
|
|
133
|
+
self._ft_initialize_overlapped = self._bind_function(
|
|
134
|
+
"FT_InitializeOverlapped",
|
|
135
|
+
[FT_HANDLE, ctypes.c_void_p],
|
|
136
|
+
)
|
|
137
|
+
self._ft_release_overlapped = self._bind_function(
|
|
138
|
+
"FT_ReleaseOverlapped",
|
|
139
|
+
[FT_HANDLE, ctypes.c_void_p],
|
|
140
|
+
)
|
|
141
|
+
self._ft_abort_pipe = self._bind_function(
|
|
142
|
+
"FT_AbortPipe",
|
|
143
|
+
[FT_HANDLE, UCHAR],
|
|
144
|
+
)
|
|
145
|
+
self._ft_set_stream_pipe = self._bind_function(
|
|
146
|
+
"FT_SetStreamPipe",
|
|
147
|
+
[FT_HANDLE, BOOL, BOOL, UCHAR, ULONG],
|
|
148
|
+
)
|
|
149
|
+
|
|
150
|
+
@classmethod
|
|
151
|
+
def from_pyd3xx_handle(cls, provider: D3xxNativeHandleProvider) -> "D3xxNativeApi":
|
|
152
|
+
"""Create a native API wrapper from an opened PyD3XX-backed handle.
|
|
153
|
+
|
|
154
|
+
Args:
|
|
155
|
+
provider: Opened handle exposing the limited native provider
|
|
156
|
+
surface.
|
|
157
|
+
|
|
158
|
+
Returns:
|
|
159
|
+
Native API wrapper for the same open D3XX handle.
|
|
160
|
+
|
|
161
|
+
Raises:
|
|
162
|
+
D3xxNativeApiUnavailable: PyD3XX does not expose the required DLL
|
|
163
|
+
or handle.
|
|
164
|
+
"""
|
|
165
|
+
dll = provider.pyd3xx_native_dll()
|
|
166
|
+
if dll is None:
|
|
167
|
+
raise D3xxNativeApiUnavailable.missing_dll()
|
|
168
|
+
try:
|
|
169
|
+
handle = provider.pyd3xx_native_handle()
|
|
170
|
+
except D3xxBackendError as exc:
|
|
171
|
+
raise D3xxNativeApiUnavailable(str(exc)) from exc
|
|
172
|
+
return cls(dll, handle)
|
|
173
|
+
|
|
174
|
+
def initialize_overlapped(self, overlapped: NativeOverlapped) -> None:
|
|
175
|
+
"""Initialize one OVERLAPPED object for asynchronous D3XX I/O."""
|
|
176
|
+
status = self._ft_initialize_overlapped(self._handle, _overlapped_ptr(overlapped))
|
|
177
|
+
_check_native_status("FT_InitializeOverlapped", status)
|
|
178
|
+
|
|
179
|
+
def release_overlapped(self, overlapped: NativeOverlapped) -> None:
|
|
180
|
+
"""Release one initialized OVERLAPPED object."""
|
|
181
|
+
status = self._ft_release_overlapped(self._handle, _overlapped_ptr(overlapped))
|
|
182
|
+
_check_native_status("FT_ReleaseOverlapped", status)
|
|
183
|
+
|
|
184
|
+
def set_stream_pipe(self, pipe: int, stream_size: int) -> None:
|
|
185
|
+
"""Configure fixed-size streaming on one read pipe."""
|
|
186
|
+
status = self._ft_set_stream_pipe(
|
|
187
|
+
self._handle,
|
|
188
|
+
BOOL(False),
|
|
189
|
+
BOOL(False),
|
|
190
|
+
UCHAR(pipe),
|
|
191
|
+
ULONG(stream_size),
|
|
192
|
+
)
|
|
193
|
+
_check_native_status("FT_SetStreamPipe", status)
|
|
194
|
+
|
|
195
|
+
def abort_pipe(self, pipe: int) -> None:
|
|
196
|
+
"""Abort pending transfers for one pipe."""
|
|
197
|
+
status = self._ft_abort_pipe(self._handle, UCHAR(pipe))
|
|
198
|
+
_check_native_status("FT_AbortPipe", status)
|
|
199
|
+
|
|
200
|
+
def read_pipe_ex(
|
|
201
|
+
self,
|
|
202
|
+
pipe: int,
|
|
203
|
+
buffer: ctypes.Array[ctypes.c_char],
|
|
204
|
+
length: int,
|
|
205
|
+
overlapped: NativeOverlapped,
|
|
206
|
+
) -> NativeTransferResult:
|
|
207
|
+
"""Submit or complete one native ``FT_ReadPipeEx`` call."""
|
|
208
|
+
if length > ctypes.sizeof(buffer):
|
|
209
|
+
raise ValueError
|
|
210
|
+
transferred = ULONG(0)
|
|
211
|
+
status = self._ft_read_pipe_ex(
|
|
212
|
+
self._handle,
|
|
213
|
+
UCHAR(pipe),
|
|
214
|
+
ctypes.cast(buffer, ctypes.c_void_p),
|
|
215
|
+
ULONG(length),
|
|
216
|
+
ctypes.byref(transferred),
|
|
217
|
+
_overlapped_ptr(overlapped),
|
|
218
|
+
)
|
|
219
|
+
return NativeTransferResult(status=int(status), transferred=int(transferred.value))
|
|
220
|
+
|
|
221
|
+
def get_overlapped_result(
|
|
222
|
+
self,
|
|
223
|
+
overlapped: NativeOverlapped,
|
|
224
|
+
*,
|
|
225
|
+
wait: bool,
|
|
226
|
+
) -> NativeTransferResult:
|
|
227
|
+
"""Return completion status for one pending overlapped operation."""
|
|
228
|
+
transferred = ULONG(0)
|
|
229
|
+
status = self._ft_get_overlapped_result(
|
|
230
|
+
self._handle,
|
|
231
|
+
_overlapped_ptr(overlapped),
|
|
232
|
+
ctypes.byref(transferred),
|
|
233
|
+
BOOL(wait),
|
|
234
|
+
)
|
|
235
|
+
return NativeTransferResult(status=int(status), transferred=int(transferred.value))
|
|
236
|
+
|
|
237
|
+
def _bind_function(self, name: str, argtypes: list[object]) -> NativeFunction:
|
|
238
|
+
function = getattr(self._dll, name, None)
|
|
239
|
+
if function is None:
|
|
240
|
+
raise D3xxNativeApiUnavailable.missing_function(name)
|
|
241
|
+
function = cast("NativeFunction", function)
|
|
242
|
+
function.argtypes = argtypes
|
|
243
|
+
function.restype = FT_STATUS
|
|
244
|
+
return function
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _coerce_handle(handle: object) -> ctypes.c_void_p:
|
|
248
|
+
if isinstance(handle, ctypes.c_void_p):
|
|
249
|
+
if handle.value is None:
|
|
250
|
+
raise D3xxNativeApiUnavailable.null_handle()
|
|
251
|
+
return handle
|
|
252
|
+
if isinstance(handle, int):
|
|
253
|
+
if handle == 0:
|
|
254
|
+
raise D3xxNativeApiUnavailable.null_handle()
|
|
255
|
+
return ctypes.c_void_p(handle)
|
|
256
|
+
value = getattr(handle, "value", None)
|
|
257
|
+
if isinstance(value, int) and value != 0:
|
|
258
|
+
return ctypes.c_void_p(value)
|
|
259
|
+
raise D3xxNativeApiUnavailable.missing_handle()
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def _overlapped_ptr(overlapped: NativeOverlapped) -> ctypes.c_void_p:
|
|
263
|
+
return ctypes.cast(ctypes.byref(overlapped), ctypes.c_void_p)
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def _check_native_status(function: str, status: int) -> None:
|
|
267
|
+
if status != FT_OK:
|
|
268
|
+
raise D3xxBackendError(function, status)
|
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
"""Native D3XX fast-path async transfer adapter."""
|
|
2
|
+
|
|
3
|
+
import ctypes
|
|
4
|
+
import time
|
|
5
|
+
from collections.abc import Callable
|
|
6
|
+
from contextlib import suppress
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from threading import Event, Lock, Thread
|
|
9
|
+
from typing import TYPE_CHECKING, Protocol, cast
|
|
10
|
+
|
|
11
|
+
from py3dscapture.protocol.sizes import N3DSXL_BULK_IN_ENDPOINT, capture_size
|
|
12
|
+
from py3dscapture.streaming.buffers import RawFrameSlot
|
|
13
|
+
from py3dscapture.transport.d3xx_backend import D3XX_DEFAULT_TIMEOUT_MS, D3xxBackendError
|
|
14
|
+
from py3dscapture.transport.d3xx_native import (
|
|
15
|
+
FT_IO_INCOMPLETE,
|
|
16
|
+
FT_IO_PENDING,
|
|
17
|
+
FT_OK,
|
|
18
|
+
D3xxNativeApi,
|
|
19
|
+
NativeOverlapped,
|
|
20
|
+
NativeTransferResult,
|
|
21
|
+
)
|
|
22
|
+
from py3dscapture.transport.libusb_async import AsyncTransferCallback
|
|
23
|
+
|
|
24
|
+
if TYPE_CHECKING:
|
|
25
|
+
from py3dscapture.transport.d3xx_native import D3xxNativeHandleProvider
|
|
26
|
+
|
|
27
|
+
NativeBufferFactory = Callable[[int], ctypes.Array[ctypes.c_char]]
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class D3xxNativeFastPathConfigError(ValueError):
|
|
31
|
+
"""Raised when native fast-path backend configuration is invalid."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class D3xxNativeFastPathReleasedError(RuntimeError):
|
|
35
|
+
"""Raised when submitting to a released native fast-path backend."""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class D3xxNativeFastPathCancellingError(RuntimeError):
|
|
39
|
+
"""Raised when submitting while native fast-path cancellation is active."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class D3xxNativeFastPathDrainTimeoutError(RuntimeError):
|
|
43
|
+
"""Raised when pending native transfers do not drain within the limit."""
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class D3xxNativeFastPathSlotBusyError(RuntimeError):
|
|
47
|
+
"""Raised when a raw slot is submitted while already in flight."""
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class D3xxNativeHandle(Protocol):
|
|
51
|
+
"""Handle surface owned by the native fast-path backend."""
|
|
52
|
+
|
|
53
|
+
def close(self) -> None:
|
|
54
|
+
"""Close the underlying D3XX handle."""
|
|
55
|
+
...
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class D3xxNativeApiProtocol(Protocol):
|
|
59
|
+
"""Native API operations required by the fast-path backend."""
|
|
60
|
+
|
|
61
|
+
def initialize_overlapped(self, overlapped: NativeOverlapped) -> None:
|
|
62
|
+
"""Initialize one overlapped object."""
|
|
63
|
+
...
|
|
64
|
+
|
|
65
|
+
def release_overlapped(self, overlapped: NativeOverlapped) -> None:
|
|
66
|
+
"""Release one overlapped object."""
|
|
67
|
+
...
|
|
68
|
+
|
|
69
|
+
def set_stream_pipe(self, pipe: int, stream_size: int) -> None:
|
|
70
|
+
"""Configure fixed-size stream transfers."""
|
|
71
|
+
...
|
|
72
|
+
|
|
73
|
+
def abort_pipe(self, pipe: int) -> None:
|
|
74
|
+
"""Abort pending transfers on one pipe."""
|
|
75
|
+
...
|
|
76
|
+
|
|
77
|
+
def read_pipe_ex(
|
|
78
|
+
self,
|
|
79
|
+
pipe: int,
|
|
80
|
+
buffer: ctypes.Array[ctypes.c_char],
|
|
81
|
+
length: int,
|
|
82
|
+
overlapped: NativeOverlapped,
|
|
83
|
+
) -> NativeTransferResult:
|
|
84
|
+
"""Submit a native stream read."""
|
|
85
|
+
...
|
|
86
|
+
|
|
87
|
+
def get_overlapped_result(
|
|
88
|
+
self,
|
|
89
|
+
overlapped: NativeOverlapped,
|
|
90
|
+
*,
|
|
91
|
+
wait: bool,
|
|
92
|
+
) -> NativeTransferResult:
|
|
93
|
+
"""Return pending native read status."""
|
|
94
|
+
...
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@dataclass(slots=True)
|
|
98
|
+
class NativeReadSlot:
|
|
99
|
+
"""Backend-owned native buffer and overlapped state for one raw slot."""
|
|
100
|
+
|
|
101
|
+
slot_index: int
|
|
102
|
+
buffer: ctypes.Array[ctypes.c_char]
|
|
103
|
+
overlapped: NativeOverlapped
|
|
104
|
+
raw_slot: RawFrameSlot | None = None
|
|
105
|
+
callback: AsyncTransferCallback | None = None
|
|
106
|
+
length: int = 0
|
|
107
|
+
in_flight: bool = False
|
|
108
|
+
backend_started_ns: int | None = None
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class D3xxNativeFastPathBackend:
|
|
112
|
+
"""Adapt native D3XX overlapped reads to the StreamingEngine boundary."""
|
|
113
|
+
|
|
114
|
+
def __init__(
|
|
115
|
+
self,
|
|
116
|
+
handle: D3xxNativeHandle,
|
|
117
|
+
*,
|
|
118
|
+
native_api: D3xxNativeApiProtocol | None = None,
|
|
119
|
+
pipe: int = N3DSXL_BULK_IN_ENDPOINT,
|
|
120
|
+
slot_count: int = 2,
|
|
121
|
+
read_size: int | None = None,
|
|
122
|
+
timeout_ms: int = D3XX_DEFAULT_TIMEOUT_MS,
|
|
123
|
+
poll_interval: float = 0.001,
|
|
124
|
+
drain_timeout: float = 2.0,
|
|
125
|
+
buffer_factory: NativeBufferFactory = ctypes.create_string_buffer,
|
|
126
|
+
) -> None:
|
|
127
|
+
"""Create a D3XX native fast-path streaming backend.
|
|
128
|
+
|
|
129
|
+
Args:
|
|
130
|
+
handle: Open D3XX handle that will be closed on release.
|
|
131
|
+
native_api: Optional native API wrapper. When omitted, it is built
|
|
132
|
+
from the PyD3XX-backed handle provider.
|
|
133
|
+
pipe: Read pipe ID.
|
|
134
|
+
slot_count: Number of preallocated native slots.
|
|
135
|
+
read_size: Native buffer size. Defaults to the 2D N3DSXL capture
|
|
136
|
+
transfer size.
|
|
137
|
+
timeout_ms: Reserved to match D3XX backend configuration; native
|
|
138
|
+
overlapped reads use pipe timeout state configured elsewhere.
|
|
139
|
+
poll_interval: Completion poll interval in seconds.
|
|
140
|
+
drain_timeout: Maximum seconds to wait for cancellation drain.
|
|
141
|
+
buffer_factory: Test hook for native buffer allocation.
|
|
142
|
+
|
|
143
|
+
Raises:
|
|
144
|
+
D3xxNativeFastPathConfigError: Configuration values are invalid.
|
|
145
|
+
"""
|
|
146
|
+
_ = timeout_ms
|
|
147
|
+
if slot_count <= 0 or (read_size is not None and read_size <= 0):
|
|
148
|
+
raise D3xxNativeFastPathConfigError
|
|
149
|
+
if poll_interval <= 0 or drain_timeout <= 0:
|
|
150
|
+
raise D3xxNativeFastPathConfigError
|
|
151
|
+
self._handle = handle
|
|
152
|
+
self._native_api = native_api or D3xxNativeApi.from_pyd3xx_handle(
|
|
153
|
+
cast("D3xxNativeHandleProvider", handle)
|
|
154
|
+
)
|
|
155
|
+
self._pipe = pipe
|
|
156
|
+
self._slot_count = slot_count
|
|
157
|
+
self._read_size = read_size or capture_size(mode_3d=False)
|
|
158
|
+
self._poll_interval = poll_interval
|
|
159
|
+
self._drain_timeout = drain_timeout
|
|
160
|
+
self._lock = Lock()
|
|
161
|
+
self._wake = Event()
|
|
162
|
+
self._cancel_requested = Event()
|
|
163
|
+
self._released = False
|
|
164
|
+
self._slots = tuple(
|
|
165
|
+
self._create_native_slot(index, buffer_factory) for index in range(slot_count)
|
|
166
|
+
)
|
|
167
|
+
self._native_api.set_stream_pipe(self._pipe, self._read_size)
|
|
168
|
+
self._pump = Thread(
|
|
169
|
+
target=self._completion_pump,
|
|
170
|
+
name="py3dscapture-d3xx-native-stream",
|
|
171
|
+
)
|
|
172
|
+
self._pump.start()
|
|
173
|
+
|
|
174
|
+
def submit_read(
|
|
175
|
+
self,
|
|
176
|
+
slot: RawFrameSlot,
|
|
177
|
+
*,
|
|
178
|
+
length: int,
|
|
179
|
+
callback: AsyncTransferCallback,
|
|
180
|
+
) -> None:
|
|
181
|
+
"""Submit one native overlapped read into a preallocated native slot."""
|
|
182
|
+
if length > len(slot.buffer) or length > self._read_size:
|
|
183
|
+
raise ValueError
|
|
184
|
+
native_slot = self._slot_for_raw(slot)
|
|
185
|
+
with self._lock:
|
|
186
|
+
if self._released:
|
|
187
|
+
raise D3xxNativeFastPathReleasedError
|
|
188
|
+
if self._cancel_requested.is_set():
|
|
189
|
+
raise D3xxNativeFastPathCancellingError
|
|
190
|
+
if native_slot.in_flight:
|
|
191
|
+
raise D3xxNativeFastPathSlotBusyError
|
|
192
|
+
native_slot.raw_slot = slot
|
|
193
|
+
native_slot.callback = callback
|
|
194
|
+
native_slot.length = length
|
|
195
|
+
native_slot.backend_started_ns = time.monotonic_ns()
|
|
196
|
+
native_slot.in_flight = True
|
|
197
|
+
slot.backend_started_ns = native_slot.backend_started_ns
|
|
198
|
+
result = self._native_api.read_pipe_ex(
|
|
199
|
+
self._pipe,
|
|
200
|
+
native_slot.buffer,
|
|
201
|
+
length,
|
|
202
|
+
native_slot.overlapped,
|
|
203
|
+
)
|
|
204
|
+
if result.status == FT_IO_PENDING:
|
|
205
|
+
self._wake.set()
|
|
206
|
+
return
|
|
207
|
+
self._settle_slot(native_slot, result)
|
|
208
|
+
|
|
209
|
+
def cancel_all(self) -> None:
|
|
210
|
+
"""Request cancellation and abort the native read pipe."""
|
|
211
|
+
self._cancel_requested.set()
|
|
212
|
+
self._native_api.abort_pipe(self._pipe)
|
|
213
|
+
self._wake.set()
|
|
214
|
+
|
|
215
|
+
def drain(self) -> None:
|
|
216
|
+
"""Wait for all in-flight native reads to settle with a bounded timeout."""
|
|
217
|
+
deadline = time.monotonic() + self._drain_timeout
|
|
218
|
+
while self._has_in_flight():
|
|
219
|
+
if time.monotonic() >= deadline:
|
|
220
|
+
raise D3xxNativeFastPathDrainTimeoutError
|
|
221
|
+
self._wake.set()
|
|
222
|
+
time.sleep(min(self._poll_interval, 0.01))
|
|
223
|
+
|
|
224
|
+
def release(self) -> None:
|
|
225
|
+
"""Cancel pending reads, release native resources, and close the handle."""
|
|
226
|
+
with self._lock:
|
|
227
|
+
if self._released:
|
|
228
|
+
return
|
|
229
|
+
self._released = True
|
|
230
|
+
self.cancel_all()
|
|
231
|
+
self.drain()
|
|
232
|
+
self._wake.set()
|
|
233
|
+
self._pump.join(timeout=self._drain_timeout)
|
|
234
|
+
for native_slot in self._slots:
|
|
235
|
+
self._native_api.release_overlapped(native_slot.overlapped)
|
|
236
|
+
self._handle.close()
|
|
237
|
+
|
|
238
|
+
def _create_native_slot(
|
|
239
|
+
self,
|
|
240
|
+
index: int,
|
|
241
|
+
buffer_factory: NativeBufferFactory,
|
|
242
|
+
) -> NativeReadSlot:
|
|
243
|
+
overlapped = NativeOverlapped()
|
|
244
|
+
self._native_api.initialize_overlapped(overlapped)
|
|
245
|
+
return NativeReadSlot(
|
|
246
|
+
slot_index=index,
|
|
247
|
+
buffer=buffer_factory(self._read_size),
|
|
248
|
+
overlapped=overlapped,
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
def _completion_pump(self) -> None:
|
|
252
|
+
while True:
|
|
253
|
+
if self._released and not self._has_in_flight():
|
|
254
|
+
return
|
|
255
|
+
did_settle = False
|
|
256
|
+
for native_slot in self._in_flight_slots():
|
|
257
|
+
result = self._native_api.get_overlapped_result(
|
|
258
|
+
native_slot.overlapped,
|
|
259
|
+
wait=False,
|
|
260
|
+
)
|
|
261
|
+
if result.status == FT_IO_INCOMPLETE:
|
|
262
|
+
continue
|
|
263
|
+
self._settle_slot(native_slot, result)
|
|
264
|
+
did_settle = True
|
|
265
|
+
if did_settle:
|
|
266
|
+
continue
|
|
267
|
+
self._wake.wait(self._poll_interval)
|
|
268
|
+
self._wake.clear()
|
|
269
|
+
|
|
270
|
+
def _settle_slot(self, native_slot: NativeReadSlot, result: NativeTransferResult) -> None:
|
|
271
|
+
completed_ns = time.monotonic_ns()
|
|
272
|
+
callback: AsyncTransferCallback | None
|
|
273
|
+
raw_slot: RawFrameSlot | None
|
|
274
|
+
with self._lock:
|
|
275
|
+
if not native_slot.in_flight:
|
|
276
|
+
return
|
|
277
|
+
native_slot.in_flight = False
|
|
278
|
+
callback = native_slot.callback
|
|
279
|
+
raw_slot = native_slot.raw_slot
|
|
280
|
+
native_slot.callback = None
|
|
281
|
+
native_slot.raw_slot = None
|
|
282
|
+
if raw_slot is None or callback is None:
|
|
283
|
+
return
|
|
284
|
+
if self._cancel_requested.is_set():
|
|
285
|
+
return
|
|
286
|
+
transferred = min(result.transferred, native_slot.length)
|
|
287
|
+
status = result.status
|
|
288
|
+
if status == FT_OK:
|
|
289
|
+
raw_slot.buffer[:transferred] = native_slot.buffer.raw[:transferred]
|
|
290
|
+
elif status != FT_IO_PENDING:
|
|
291
|
+
with suppress(D3xxBackendError):
|
|
292
|
+
self._native_api.abort_pipe(self._pipe)
|
|
293
|
+
callback(raw_slot.index, transferred if status == FT_OK else 0, status, completed_ns)
|
|
294
|
+
|
|
295
|
+
def _slot_for_raw(self, slot: RawFrameSlot) -> NativeReadSlot:
|
|
296
|
+
if slot.index < 0 or slot.index >= self._slot_count:
|
|
297
|
+
raise IndexError
|
|
298
|
+
return self._slots[slot.index]
|
|
299
|
+
|
|
300
|
+
def _in_flight_slots(self) -> tuple[NativeReadSlot, ...]:
|
|
301
|
+
with self._lock:
|
|
302
|
+
return tuple(slot for slot in self._slots if slot.in_flight)
|
|
303
|
+
|
|
304
|
+
def _has_in_flight(self) -> bool:
|
|
305
|
+
with self._lock:
|
|
306
|
+
return any(slot.in_flight for slot in self._slots)
|