QWindowCapture Class
该类用于捕获窗口。更多内容...
| 头文件： | #include <QWindowCapture> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake： | QT += multimedia |
| 自： | Qt 6.6 |
| 在 QML 中： | WindowCapture |
| 继承自： | QObject |
公共类型
| enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound } |
属性
|
|
公共函数
| QWindowCapture(QObject *parent = nullptr) | |
| virtual | ~QWindowCapture() override |
| QMediaCaptureSession * | captureSession() const |
| QWindowCapture::Error | error() const |
| QString | errorString() const |
| bool | isActive() const |
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
| void | setWindow(QCapturableWindow window) |
| QCapturableWindow | window() const |
公共槽位
信号
| void | activeChanged(bool) |
| void | errorChanged() |
| void | errorOccurred(QWindowCapture::Error error, const QString &errorString) |
| void | maximumFrameRateChanged() |
| void | windowChanged(QCapturableWindow window) |
静态公共成员
| QList<QCapturableWindow> | capturableWindows() |
详细说明
该类用于捕获窗口。它由QMediaCaptureSession 类进行管理，捕获的窗口可通过该类在视频预览对象中显示，或录制到文件中。
以下代码片段演示了如何选择一个可捕获的窗口，并将结果显示在QVideoWidget 中：
QMediaCaptureSession session;
QWindowCapture windowCapture;
session.setWindowCapture(&windowCapture);
QVideoWidget videoWidget;
session.setVideoOutput(&videoWidget);
videoWidget.show();
// A window must be selected before capturing can start.
const QList<QCapturableWindow> windows = QWindowCapture::capturableWindows();
if (!windows.isEmpty()) {
windowCapture.setWindow(windows.first());
windowCapture.start();
}窗口捕获的限制
使用 QWindowCapture 时需注意以下限制：
- QWindowCapture 仅在 FFmpeg 后端下受支持。
- 在某些平台上，当捕获的窗口内容保持不变时，不会输出新的视频帧。因此，应用程序不应依赖于以请求的帧率持续接收帧流。
在 X11 系统上使用QWindowCapture 时，存在以下限制：
- 在 Linux X11 系统上，当窗口部分移出可见屏幕区域时，仅会捕获可见区域。因此，输出的视频帧尺寸可能小于窗口的几何尺寸。
- 位于可见屏幕区域之外的窗口无法被捕获，此时会发出错误信号。
- 最小化窗口或位于不可见虚拟工作区中的窗口的行为取决于窗口管理器。例如，在 GNOME 中可以捕获此类窗口，而在 WindowMaker 或 Xfwm 中则不允许此类捕获，且窗口捕获实例会发出错误。
另请参阅 QMediaCaptureSession 和QCapturableWindow 。
成员类型文档
enum QWindowCapture::Error
列出了QWindowCapture 类可能抛出的错误代码。errorString()方法提供有关错误原因的详细信息。
| 常量 | 值 | 描述 |
|---|---|---|
QWindowCapture::NoError | 0 | 无错误 |
QWindowCapture::InternalError | 1 | 内部窗口捕获驱动程序错误 |
QWindowCapture::CapturingNotSupported | 2 | 不支持窗口捕获 |
QWindowCapture::CaptureFailed | 4 | 捕获窗口失败 |
QWindowCapture::NotFound | 5 | 未找到所选窗口 |
属性文档
active : bool
该属性表示捕获操作当前是否处于活动状态。
访问函数：
| bool | isActive() const |
| void | setActive(bool active) |
通知信号：
| void | activeChanged(bool) |
[read-only] error : Error
该属性存储了上次错误的代码。
访问函数：
| QWindowCapture::Error | error() const |
通知信号：
| void | errorChanged() |
[read-only] errorString : QString
该属性包含一个描述错误原因的人类可读字符串。
访问函数：
| QString | errorString() const |
通知信号：
| void | errorChanged() |
[since 6.12] maximumFrameRate : std::optional<qreal>
该属性用于设置窗口捕获帧率的上限。
可以设置此属性来覆盖基于显示器刷新率等默认使用的捕获帧率，但仅作为上限，因为窗口捕获生成的帧率是可变的。不建议将此值设置得高于显示器刷新率，否则可能会导致错误。
对该属性的任何更改将在QWindowCapture 下次激活时生效。
此枚举在 Qt 6.12 中引入。
访问函数：
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
通知器信号：
| void | maximumFrameRateChanged() |
window : QCapturableWindow
该属性用于存储用于捕获的窗口。
若将此属性设置为处于活动状态的QWindowCapture 上的无效窗口，将导致该 变为非活动状态并触发错误。
访问函数：
| QCapturableWindow | window() const |
| void | setWindow(QCapturableWindow window) |
通知器信号：
| void | windowChanged(QCapturableWindow window) |
成员函数文档
[explicit] QWindowCapture::QWindowCapture(QObject *parent = nullptr)
使用parent 创建一个新的QWindowCapture对象。
[override virtual noexcept] QWindowCapture::~QWindowCapture()
销毁该对象。
[static invokable] QList<QCapturableWindow> QWindowCapture::capturableWindows()
返回一个包含当前可用于录制的QCapturableWindow 对象的列表。
注意：在 macOS上 ，调用此方法会触发“屏幕录制”权限对话框。如果尚未授予权限，此方法将返回一个空列表。多次调用该方法会将此对话框置于前台。
注意： 可通过元对象系统和 QML 调用此 函数。请参阅Q_INVOKABLE 。
QMediaCaptureSession *QWindowCapture::captureSession() const
返回此QWindowCapture 所连接的捕获会话。
使用QMediaCaptureSession::setWindowCapture() 将窗口捕获连接到一个会话。
[signal] void QWindowCapture::errorChanged()
当error 或errorString 属性发生更改时，会触发此信号。
当抛出多个相同的错误时，不会触发此信号。若要跟踪此类错误，请使用errorOccurred 信号。
注意： 这是针对属性error 和errorString的通知器 信号。
[signal] void QWindowCapture::errorOccurred(QWindowCapture::Error error, const QString &errorString)
当发生error 时触发信号，并同时触发errorString 。
[slot] void QWindowCapture::start()
开始捕获window 。
这相当于将active 属性设置为true。
[slot] void QWindowCapture::stop()
停止捕获。
这相当于将active 属性设置为false。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
