En esta página

ScreenCapture QML Type

Este tipo se utiliza para hacer capturas de pantalla. Más información...

Import Statement: import QtMultimedia
Since: Qt 6.5
In C++: QScreenCapture

Propiedades

Señales

Métodos

Descripción detallada

ScreenCapture captura una pantalla. Se gestiona mediante CaptureSession, donde la pantalla capturada se puede visualizar en un objeto de vista previa de vídeo o grabarse en un archivo.

El código siguiente muestra una sesión de captura sencilla en la que ScreenCapture reproduce la vista de la pantalla principal capturada en 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]
    }
}

Limitaciones de ScreenCapture

En Qt 6.5.2 y versiones posteriores, se aplican las siguientes limitaciones al uso de ScreenCapture:

  • 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 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.
  • En los 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 WindowCapture y CaptureSession.

Documentación de propiedades

active : bool

Indica si la captura está activa en este momento.

Véase también start() y stop().

error : enumeration [read-only]

Devuelve el código del último error.

ConstanteDescripción
ScreenCapture.NoErrorSin error
ScreenCapture.InternalErrorError interno del controlador de captura de pantalla
ScreenCapture.CapturingNotSupportedLa captura no es compatible
ScreenCapture.CaptureFailedError al capturar la pantalla
ScreenCapture.NotFoundNo se ha encontrado la pantalla seleccionada

errorString : string [read-only]

Devuelve una cadena legible para el usuario que describe la causa del error.

maximumFrameRate : real [since 6.12]

El límite máximo de la frecuencia de fotogramas de la captura de pantalla.

Este valor 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.

Si se establece en -1, se utiliza un valor por defecto que depende de la plataforma.

Cualquier cambio en esta propiedad se aplica la próxima vez que el « ScreenCapture » se active.

Esta propiedad se introdujo en Qt 6.12.

screen : Screen

Describe la pantalla que se va a capturar.

Si se establece el valor nulo Screen, se seleccionará la pantalla principal cuando se active la instancia ScreenCapture.

Véase también ` Application.screens`.

Documentación de Signal

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, utilice la señal errorOccurred.

Nota: El controlador correspondiente es onErrorChanged.

errorOccurred(int error, string errorString)

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

En cuanto al parámetro «error», consulta la tabla de enumeración en error para ver qué valores se pueden pasar.

Nota: El controlador correspondiente es onErrorOccurred.

Véase también error.

Documentación del método

void start()

Comienza a capturar el ` screen`.

Esto equivale a establecer la propiedad active en true.

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