QScreenCapture Class
Esta clase se utiliza para realizar capturas de pantalla. Más información...
| Encabezado: | #include <QScreenCapture> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| Desde: | Qt 6.5 |
| En QML: | ScreenCapture |
| Heredan de: | QObject |
Tipos públicos
| enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound } |
Propiedades
|
|
Funciones públicas
| QMediaCaptureSession * | captureSession() const |
| QScreenCapture::Error | error() const |
| QString | errorString() const |
| bool | isActive() const |
| std::optional<qreal> | maximumFrameRate() const |
| QScreen * | screen() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
| void | setScreen(QScreen *screen) |
Ranuras públicas
Señales
| void | activeChanged(bool) |
| void | errorChanged() |
| void | errorOccurred(QScreenCapture::Error error, const QString &errorString) |
| void | maximumFrameRateChanged() |
| void | screenChanged(QScreen *) |
Descripción detallada
La clase captura una pantalla. Se gestiona mediante la clase ` QMediaCaptureSession `, donde la pantalla capturada se puede mostrar en un objeto de vista previa de vídeo o grabarse en un archivo.
El siguiente fragmento de código muestra cómo capturar la pantalla principal y mostrar el resultado en un objeto ` QVideoWidget`:
QMediaCaptureSession session;
QScreenCapture screenCapture;
session.setScreenCapture(&screenCapture);
QVideoWidget videoWidget;
session.setVideoOutput(&videoWidget);
videoWidget.show();
// With no screen set, the primary screen is captured once capturing starts.
screenCapture.start();Limitaciones de la captura de pantalla
En Qt 6.5.2 y versiones posteriores, se aplican las siguientes limitaciones al uso de QScreenCapture:
- Solo es compatible con el backend FFmpeg.
- En algunas plataformas, no se emiten nuevos fotogramas de vídeo mientras el contenido de la pantalla capturada permanece inalterado. Por lo tanto, las aplicaciones no deben basarse en la recepción de un flujo continuo de fotogramas a la frecuencia de fotogramas solicitada.
- En sistemas Linux que utilizan el compositor Wayland, la implementación de la captura de pantalla es experimental y presenta las siguientes limitaciones. Debido a las restricciones del protocolo Wayland, es imposible establecer y obtener la pantalla de destino a través de la API de la clase `
QScreenCapture`. En su lugar, el sistema operativo mostrará un asistente de selección de pantalla al invocar `QScreenCapture::setActive(true)`. La función de captura de pantalla requiere la instalación del servicio ScreenCast, compatible con XDG Desktop Portal y PipeWire (0.3). Estas limitaciones podrían cambiar en el futuro. - No es compatible con sistemas operativos móviles, salvo en Android. La captura de pantalla en Android requiere que se añada un permiso adicional de servicio en primer plano de Android al archivo «
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> - En entornos integrados con EGLFS, la funcionalidad es limitada. Para las aplicaciones de Qt Quick, la clase se implementa actualmente a través de QQuickWindow::grabWindow, lo que puede provocar problemas de rendimiento.
- En la mayoría de los casos, establecemos una frecuencia de fotogramas de captura de pantalla igual a la frecuencia de actualización de la pantalla, excepto en Windows, donde la frecuencia puede ser flexible. Dicha frecuencia de fotogramas (75/120 FPS) podría provocar problemas de rendimiento en CPU poco potentes si la pantalla capturada tiene una resolución 4K. En EGLFS, la frecuencia de fotogramas de captura está fijada actualmente en 30 FPS.
Véase también QWindowCapture y QMediaCaptureSession.
Documentación sobre tipos de miembros
enum QScreenCapture::Error
Enumera los códigos de error que puede indicar la clase ` QScreenCapture `. El método ` errorString()` proporciona información detallada sobre la causa del error.
| Constante | Valor | Descripción |
|---|---|---|
QScreenCapture::NoError | 0 | Sin error |
QScreenCapture::InternalError | 1 | Error interno del controlador de captura de pantalla |
QScreenCapture::CapturingNotSupported | 2 | La captura no es compatible |
QScreenCapture::CaptureFailed | 4 | Error al capturar la pantalla |
QScreenCapture::NotFound | 5 | No se ha encontrado la pantalla seleccionada |
Documentación de propiedades
active : bool
Esta propiedad indica si la captura está activa en este momento.
Funciones de acceso:
| bool | isActive() const |
| void | setActive(bool active) |
Señal de notificador:
| void | activeChanged(bool) |
Véase también start() y stop().
[read-only] error : Error
Esta propiedad contiene el código del último error.
Funciones de acceso:
| QScreenCapture::Error | error() const |
Señal de notificación:
| void | errorChanged() |
[read-only] errorString : QString
Esta propiedad contiene una cadena legible para el usuario que describe la causa del error.
Funciones de acceso:
| QString | errorString() const |
Señal del notificador:
| void | errorChanged() |
[since 6.12] maximumFrameRate : std::optional<qreal>
Esta propiedad establece el límite máximo de la frecuencia de fotogramas de la captura de pantalla.
Se puede configurar para anular la frecuencia de fotogramas de captura utilizada por defecto en función, por ejemplo, de la frecuencia de actualización de la pantalla, pero solo como límite máximo, ya que la captura de pantalla genera fotogramas a una frecuencia variable. No se recomienda establecer este valor por encima de la frecuencia de actualización de la pantalla, ya que puede provocar errores.
Cualquier cambio en esta propiedad se aplica la próxima vez que el « QScreenCapture » se active.
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
Señal de notificador:
| void | maximumFrameRateChanged() |
screen : QScreen*
Esta propiedad determina la pantalla que se va a capturar.
Si se establece el valor nulo « QScreen », se seleccionará « QGuiApplication::primaryScreen » cuando se active la instancia « QScreenCapture ».
Funciones de acceso:
| QScreen * | screen() const |
| void | setScreen(QScreen *screen) |
Señal de notificador:
| void | screenChanged(QScreen *) |
Véase también QGuiApplication::screens() y QGuiApplication::primaryScreen().
Documentación de funciones de miembro
QMediaCaptureSession *QScreenCapture::captureSession() const
Devuelve la sesión de captura a la que está conectada esta captura de pantalla QScreenCapture.
Utiliza QMediaCaptureSession::setScreenCapture() para vincular la captura de pantalla a una sesión.
[signal] void QScreenCapture::errorChanged()
Esta señal se emite cuando se modifican las propiedades « error » o « errorString ».
Esta señal no se emite cuando se producen varios errores idénticos. Para realizar un seguimiento de dichos errores, utiliza la señal errorOccurred.
Nota: Señalde notificador para las propiedades error y errorString.
[signal] void QScreenCapture::errorOccurred(QScreenCapture::Error error, const QString &errorString)
Avisa cuando se produce un « error », junto con el « errorString ».
[slot] void QScreenCapture::start()
Comienza a capturar el screen.
Esto equivale a establecer la propiedad active en true.
[slot] void QScreenCapture::stop()
Detiene la captura.
Esto equivale a establecer la propiedad « active » en «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.