ScreenCapture QML Type

此类型用于截屏。更多...

• 所有成员列表，包括继承的成员

属性

• active : bool
• error : enumeration
• errorString : string
• maximumFrameRate : real (since 6.12)
• screen : Screen

信号

• errorChanged()
• errorOccurred(int error, string errorString)

方法

• void start()
• void stop()

详细说明

ScreenCapture 用于捕获屏幕。它由CaptureSession 管理，捕获的屏幕可在视频预览对象中显示，或录制到文件中。

下面的代码展示了一个简单的捕获会话，其中 ScreenCapture 将捕获的主屏幕视图在VideoOutput 中进行回放。

CaptureSession {
    id: captureSession
    screenCapture: ScreenCapture {
        id: capture
        active: true
    }
    videoOutput: VideoOutput {
        id: videoOutput
    }

    Component.onCompleted: {
        // Select the screen to capture. If no screen is set, the primary
        // screen is captured by default.
        const screens = Application.screens
        if (screens.length > 0)
            capture.screen = screens[0]
    }
}

屏幕捕获的限制

在 Qt 6.5.2 及更高版本中，使用 ScreenCapture 时存在以下限制：

• 仅支持 FFmpeg 后端。
• 在某些平台上，当捕获的屏幕内容保持不变时，不会输出新的视频帧。因此，应用程序不应依赖于以请求的帧率持续接收帧流。
• 在使用 Wayland 合成器的 Linux 系统上，屏幕捕获功能尚处于实验阶段，并存在以下限制。受 Wayland 协议的限制，无法通过QScreenCapture 类的 API 设置和获取目标屏幕。 取而代之的是，在调用 `QScreenCapture::setActive(true)` 时，操作系统会显示一个屏幕选择向导。屏幕捕获功能需要安装由XDG Desktop Portal和PipeWire(0.3) 支持的ScreenCast服务。这些限制在未来可能会发生变化。
• 除 Android 之外，移动操作系统不支持此功能。在 Android 上进行屏幕截图需要将额外的Android 前台服务权限添加到AndroidManifest.xml 文件中：

  <manifest ...>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
  <application ...>
      <service android:name="org.qtproject.qt.android.multimedia.QtScreenCaptureService"
          android:foregroundServiceType="mediaProjection"
          android:exported="false"/>
      </service>
  </application>
  </manifest>

• 在采用 EGLFS 的嵌入式系统上，该功能受限。对于Qt Quick 应用程序，该类目前通过QQuickWindow::grabWindow 实现，这可能会导致性能问题。
• 在大多数情况下，我们会将屏幕截图帧率设置为与屏幕刷新率相同，但 Windows 系统除外，该系统的帧率可能较为灵活。如果截图分辨率为 4K，此类帧率（75/120 FPS）可能会在性能较弱的 CPU 上导致性能问题。 在 EGLFS 上，捕获帧率目前被锁定为 30 FPS。

另请参阅 WindowCapture 和CaptureSession 。

属性文档

active : bool

描述捕获功能当前是否处于活动状态。

另请参阅 start() 和stop()。

error : enumeration [read-only]

返回最后一个错误的代码。

errorString : string [read-only]

返回一个描述错误原因的人类可读字符串。

maximumFrameRate : real [since 6.12]

屏幕捕获帧率的上限。

此参数可用于覆盖默认的屏幕捕获帧率（该帧率通常基于显示器刷新率等因素确定），但仅作为上限，因为屏幕捕获生成的帧率是可变的。不建议将此值设置得高于显示器刷新率，否则可能会导致错误。

若设为 -1，则使用取决于平台的默认值。

对该属性的任何更改将在ScreenCapture 下次激活时生效。

该属性在 Qt 6.12 中引入。

screen : Screen

描述用于捕获的屏幕。

如果设置了空值Screen ，则当ScreenCapture 实例被激活时，将选择主屏幕。

另请参阅 Application.screens 。

Signal 文档

errorChanged()

当error 或errorString 属性发生变化时，会发出此信号。

当抛出多个相同的错误时，不会发出此信号。若要跟踪此类错误，请使用信号errorOccurred 。

errorOccurred(int error, string errorString)

当发生error 时触发信号，并同时触发errorString 。

关于 error 参数，请参阅error 中的枚举表，了解可传递的值。

另请参阅 error 。

方法文档

void start()

开始捕获screen 。

这相当于将active 属性设置为true 。

void stop()

停止捕获。

这相当于将active 属性设置为false 。