En esta página

QWindowCapture Class

Esta clase se utiliza para capturar una ventana. Más información...

Encabezado: #include <QWindowCapture>
CMake: find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake: QT += multimedia
Desde: Qt 6.6
En QML: WindowCapture
Heredan de: QObject

Tipos públicos

enum Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound }

Propiedades

Funciones públicas

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

Ranuras públicas

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

Señales

void activeChanged(bool)
void errorChanged()
void errorOccurred(QWindowCapture::Error error, const QString &errorString)
void maximumFrameRateChanged()
void windowChanged(QCapturableWindow window)

Miembros públicos estáticos

QList<QCapturableWindow> capturableWindows()

Descripción detallada

La clase captura una ventana. Está gestionada por la clase QMediaCaptureSession, donde la ventana 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 seleccionar una de las ventanas capturables y mostrar el resultado en un objeto ` 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();
}

Limitaciones de la captura de ventanas

Se aplican las siguientes limitaciones al uso de QWindowCapture:

  • QWindowCapture solo es compatible con el backend de FFmpeg.
  • En algunas plataformas, no se emiten nuevos fotogramas de vídeo mientras el contenido de la ventana capturada permanece sin cambios. Por lo tanto, las aplicaciones no deben basarse en la recepción de un flujo continuo de fotogramas a la frecuencia de fotogramas solicitada.

Se aplican las siguientes limitaciones al utilizar QWindowCapture en sistemas X11:

  • En los sistemas Linux X11, cuando una ventana se desplaza parcialmente fuera del área visible de la pantalla, solo se captura la región visible. Como resultado, los fotogramas de vídeo emitidos pueden tener un tamaño inferior al de la geometría de la ventana.
  • Las ventanas que se encuentran fuera del área visible de la pantalla no se pueden capturar, y en ese caso se emite una señal de error.
  • El comportamiento de las ventanas minimizadas o de aquellas situadas en un espacio de trabajo virtual invisible depende del gestor de ventanas. Por ejemplo, estas ventanas se pueden capturar en GNOME, mientras que en WindowMaker o Xfwm no se permite dicha captura, y la instancia de captura de ventanas emite un error.

Véase también QMediaCaptureSession y QCapturableWindow.

Documentación sobre tipos de miembros

enum QWindowCapture::Error

Enumera los códigos de error que puede indicar la clase ` QWindowCapture `. La función ` errorString()` proporciona información detallada sobre la causa del error.

ConstanteValorDescripción
QWindowCapture::NoError0Sin error
QWindowCapture::InternalError1Error interno del controlador de captura de ventanas
QWindowCapture::CapturingNotSupported2La captura de ventanas no es compatible
QWindowCapture::CaptureFailed4Error al capturar la ventana
QWindowCapture::NotFound5No se ha encontrado la ventana 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:

QWindowCapture::Error error() const

Señal de notificación:

void errorChanged()

[read-only] errorString : QString

Esta propiedad contiene una cadena legible que describe la causa del error.

Funciones de acceso:

QString errorString() const

Señal de notificación:

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 ventana.

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 ventana 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 « QWindowCapture » 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 del notificador:

void maximumFrameRateChanged()

window : QCapturableWindow

Esta propiedad contiene la ventana de captura.

Si se establece esta propiedad en una ventana no válida de una aplicación « QWindowCapture » activa, esta pasará a estar inactiva y generará un error.

Funciones de acceso:

QCapturableWindow window() const
void setWindow(QCapturableWindow window)

Señal de notificador:

void windowChanged(QCapturableWindow window)

Véase también QWindowCapture::capturableWindows.

Documentación de funciones de miembro

[explicit] QWindowCapture::QWindowCapture(QObject *parent = nullptr)

Crea un nuevo objeto `QWindowCapture` con ` parent`.

[override virtual noexcept] QWindowCapture::~QWindowCapture()

Destruye el objeto.

[static invokable] QList<QCapturableWindow> QWindowCapture::capturableWindows()

Devuelve una lista de objetos ` QCapturableWindow ` que están disponibles actualmente para la grabación.

Nota: En macOS, al invocar este método se abrirá el cuadro de diálogo de permisos «Grabación de pantalla». Si aún no se han concedido los permisos, este método devolverá una lista vacía. Si se invoca varias veces, este cuadro de diálogo aparecerá en primer plano.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

QMediaCaptureSession *QWindowCapture::captureSession() const

Devuelve la sesión de captura a la que está conectada esta ventana « QWindowCapture ».

Utiliza QMediaCaptureSession::setWindowCapture() para conectar la captura de ventana a una sesión.

[signal] void QWindowCapture::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 notificación para las propiedades ` error ` y ` errorString`.

[signal] void QWindowCapture::errorOccurred(QWindowCapture::Error error, const QString &errorString)

Avisa cuando se produce un error de « error », junto con el error « errorString ».

[slot] void QWindowCapture::start()

Comienza a capturar la propiedad « window ».

Esto equivale a establecer la propiedad active en «true».

[slot] void QWindowCapture::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.