QScreenCapture Class | Qt Multimedia (original) (raw)
This class is used for capturing a screen. More...
| Header: | #include |
|---|---|
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| Since: | Qt 6.5 |
| In QML: | ScreenCapture |
| Inherits: | QObject |
Public Types
| enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound } |
|---|
Properties
- active : bool
- error : Error
- errorString : QString
- screen : QScreen*
Public Functions
Public Slots
Signals
Detailed Description
The class captures a screen. It is managed by the QMediaCaptureSession class where the captured screen can be displayed in a video preview object or recorded to a file.
Screen Capture Limitations
On Qt 6.5.2 and above, the following limitations apply to using QScreenCapture:
- It is only supported with the FFmpeg backend.
- On Linux systems using the Wayland compositor, the screen capture implementation is experimental and comes with the following limitations. Due to restrictions of the Wayland protocol, it's impossible to set and get the target screen via the API of the
QScreenCaptureclass. Instead, the OS will show a screen selection wizard upon invokingQScreenCapture::setActive(true). The screen capture feature requires the installation of the ScreenCast service supported via XDG Desktop Portal and {https://pipewire.org/}{PipeWire} (0.3). These limitations might change in the future. - It is not supported on mobile operating systems, except on Android. Screen Capture on Android needs additional Android foreground service permission to be added to the
AndroidManifest.xmlfile:
<manifest ...> - On embedded with EGLFS, it has limited functionality. For Qt Quick applications, the class is currently implemented via QQuickWindow::grabWindow, which can cause performance issues.
- In most cases, we set a screen capture frame rate that equals the screen refresh rate, except on Windows, where the rate might be flexible. Such a frame rate (75/120 FPS) might cause performance issues on weak CPUs if the captured screen is of 4K resolution. On EGLFS, the capture frame rate is currently locked to 30 FPS.
See also QWindowCapture and QMediaCaptureSession.
Member Type Documentation
enum QScreenCapture::Error
Enumerates error codes that can be signaled by the QScreenCapture class. errorString() provides detailed information about the error cause.
| Constant | Value | Description |
|---|---|---|
| QScreenCapture::NoError | 0 | No error |
| QScreenCapture::InternalError | 1 | Internal screen capturing driver error |
| QScreenCapture::CapturingNotSupported | 2 | Capturing is not supported |
| QScreenCapture::CaptureFailed | 4 | Capturing screen failed |
| QScreenCapture::NotFound | 5 | Selected screen not found |
Property Documentation
active : bool
This property holds whether the capturing is currently active.
Access functions:
| bool | isActive() const |
|---|---|
| void | setActive(bool active) |
Notifier signal:
[read-only] error : Error
This property holds the code of the last error.
Access functions:
| QScreenCapture::Error | error() const |
|---|
Notifier signal:
[read-only] errorString : QString
This property holds a human readable string describing the cause of error.
Access functions:
| QString | errorString() const |
|---|
Notifier signal:
screen : QScreen*
This property holds the screen for capturing.
Access functions:
| QScreen * | screen() const |
|---|---|
| void | setScreen(QScreen *screen) |
Notifier signal:
| void | screenChanged(QScreen *) |
|---|
Member Function Documentation
QMediaCaptureSession *QScreenCapture::captureSession() const
Returns the capture session this QScreenCapture is connected to.
Use QMediaCaptureSession::setScreenCapture() to connect the camera to a session.
[signal] void QScreenCapture::errorOccurred(QScreenCapture::Error error, const QString &errorString)
Signals when an error occurs, along with the errorString.
[slot] void QScreenCapture::start()
Starts screen capture.
[slot] void QScreenCapture::stop()
Stops screen capture.
© 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.