Method dequeue

rustcv-camera/src/backend/linux/mod.rs:194–237

Dequeue a frame from the driver (blocking). 从驱动出队一帧（阻塞）。 This is the **hot path** — called once per frame. No heap allocations, no poll(), single ioctl syscall. 这是**热路径** —— 每帧调用一次。 无堆分配、无 poll()、单次 ioctl 系统调用。

(&mut self)

    /// 这是**热路径** —— 每帧调用一次。
    /// 无堆分配、无 poll()、单次 ioctl 系统调用。
    pub fn dequeue(&mut self) -> Result<RawFrame<'_>> {
        if !self.streaming {
            return Err(CameraError::StreamNotStarted);
        }

        // If the previous frame's buffer hasn't been returned, queue it now.
        // This happens automatically when the user calls next_frame() again.
        // 如果上一帧的缓冲区尚未归还，现在将其入队。
        // 当用户再次调用 next_frame() 时会自动执行此操作。
        if let Some(prev_idx) = self.pending_queue.take() {
            v4l2_sys::queue_buffer(self.fd, prev_idx as u32)?;
        }

        // Blocking DQBUF — the kernel wakes us when a frame is ready.
        // 阻塞 DQBUF —— 帧就绪时内核唤醒我们。
        let v4l2_buf = v4l2_sys::dequeue_buffer(self.fd)?;

        let index = v4l2_buf.index as usize;
        let bytesused = v4l2_buf.bytesused as usize;

        // Record this buffer as pending-queue (will be returned on next dequeue).
        // 记录此缓冲区为待归还状态（下次 dequeue 时归还）。
        self.pending_queue = Some(index);

        // Create a slice of only the valid data portion.
        // For MJPEG: bytesused ≈ 88KB, buffer length ≈ 614KB.
        // 创建仅包含有效数据部分的切片。
        // 对于 MJPEG：bytesused ≈ 88KB，缓冲区总长 ≈ 614KB。
        let data = unsafe {
            let buf = &self.buffers[index];
            std::slice::from_raw_parts(buf.ptr, bytesused)
        };

        Ok(RawFrame {
            index,
            data,
            width: self.width,
            height: self.height,
            pixel_format: self.pixel_format,
            sequence: v4l2_buf.sequence as u64,
            timestamp_us: v4l2_buf.timestamp.tv_sec as u64 * 1_000_000
                + v4l2_buf.timestamp.tv_usec as u64,
        })
    }

    /// Explicitly re-queue a buffer (return it to the driver).
    /// 显式将缓冲区重新入队（归还给驱动）。