En esta página

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

void setActive(bool active)
void start()
void stop()

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.

ConstanteValorDescripción
QScreenCapture::NoError0Sin error
QScreenCapture::InternalError1Error interno del controlador de captura de pantalla
QScreenCapture::CapturingNotSupported2La captura no es compatible
QScreenCapture::CaptureFailed4Error al capturar la pantalla
QScreenCapture::NotFound5No 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.