QVideoFrame Class
La clase QVideoFrame representa un fotograma de datos de vídeo. Más información...
| Cabecera: | #include <QVideoFrame> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
Tipos públicos
| enum | HandleType { NoHandle, RhiTextureHandle } |
| enum | MapMode { NotMapped, ReadOnly, WriteOnly, ReadWrite } |
Funciones públicas
| QVideoFrame() | |
(since 6.8) | QVideoFrame(const QImage &image) |
| QVideoFrame(const QVideoFrameFormat &format) | |
(since 6.8) | QVideoFrame(std::unique_ptr<QAbstractVideoBuffer> videoBuffer) |
| QVideoFrame(const QVideoFrame &other) | |
| QVideoFrame(QVideoFrame &&other) | |
| ~QVideoFrame() | |
| uchar * | bits(int plane) |
| const uchar * | bits(int plane) const |
| int | bytesPerLine(int plane) const |
| qint64 | endTime() const |
| QVideoFrame::HandleType | handleType() const |
| int | height() const |
| bool | isMapped() const |
| bool | isReadable() const |
| bool | isValid() const |
| bool | isWritable() const |
| bool | map(QVideoFrame::MapMode mode) |
| QVideoFrame::MapMode | mapMode() const |
| int | mappedBytes(int plane) const |
| bool | mirrored() const |
| void | paint(QPainter *painter, const QRectF &rect, const QVideoFrame::PaintOptions &options) |
| QVideoFrameFormat::PixelFormat | pixelFormat() const |
| int | planeCount() const |
| QtVideo::Rotation | rotation() const |
| void | setEndTime(qint64 time) |
| void | setMirrored(bool mirrored) |
| void | setRotation(QtVideo::Rotation angle) |
| void | setStartTime(qint64 time) |
| void | setStreamFrameRate(qreal rate) |
| void | setSubtitleText(const QString &text) |
| QSize | size() const |
| qint64 | startTime() const |
| qreal | streamFrameRate() const |
| QString | subtitleText() const |
| QVideoFrameFormat | surfaceFormat() const |
| void | swap(QVideoFrame &other) |
| QImage | toImage() const |
| void | unmap() |
| int | width() const |
| bool | operator!=(const QVideoFrame &other) const |
| QVideoFrame & | operator=(QVideoFrame &&other) |
| QVideoFrame & | operator=(const QVideoFrame &other) |
| bool | operator==(const QVideoFrame &other) const |
Descripción detallada
Un QVideoFrame encapsula los datos de píxeles de un fotograma de vídeo, así como la información sobre dicho fotograma.
Los fotogramas de vídeo pueden proceder de varias fuentes: un archivo « media » descodificado, un archivo « camera » o generados mediante programación. La forma en que se describen los píxeles en estos fotogramas puede variar considerablemente, y algunos formatos de píxeles ofrecen mayores posibilidades de compresión a costa de la facilidad de uso.
El contenido de píxeles de un fotograma de vídeo se puede asignar a la memoria mediante la función ` map()`. Tras una llamada correcta a ` map()`, se puede acceder a los datos de vídeo a través de diversas funciones. Algunos de los formatos de píxeles YUV proporcionan los datos en varios planos. El método ` planeCount()` devolverá el número de planos que se están utilizando.
Una vez mapeados, se puede acceder a los datos de vídeo de cada plano mediante la función ` bits()`, que devuelve un puntero a un búfer. El tamaño de este búfer viene dado por la función ` mappedBytes()`, y el tamaño de cada línea viene dado por ` bytesPerLine()`. El valor devuelto por la función `handle()` también puede utilizarse para acceder a los datos de los fotogramas mediante las API nativas del búfer interno (por ejemplo, un identificador de textura de OpenGL).
Un fotograma de vídeo también puede tener asociada información de marca de tiempo. Estas marcas de tiempo pueden utilizarse para determinar cuándo comenzar y detener la visualización del fotograma.
Los objetos `QVideoFrame` pueden consumir una cantidad significativa de memoria o de recursos del sistema y no deben mantenerse durante más tiempo del que requiera la aplicación.
Nota: Dado que copiar fotogramas de vídeo puede resultar costoso, QVideoFrame se comparte explícitamente, por lo que cualquier cambio realizado en un fotograma de vídeo se aplicará también a todas sus copias.
Véase también QAbstractVideoBuffer, QVideoFrameFormat y QVideoFrame::MapMode.
Documentación sobre los tipos de miembros
enum QVideoFrame::HandleType
Identifica el tipo de un identificador de búfer de vídeo.
| Constante | Valor | Descripción |
|---|---|---|
QVideoFrame::NoHandle | 0 | El búfer no tiene identificador; solo se puede acceder a sus datos mediante la asignación del búfer. |
QVideoFrame::RhiTextureHandle | 1 | El identificador del búfer viene definido por la interfaz de hardware de renderizado (RHI) de Qt. RHI es la abstracción gráfica interna de Qt para API 3D, como OpenGL, Vulkan, Metal y Direct 3D. |
Véase también ` handleType()`.
enum QVideoFrame::MapMode
Explica cómo se asignan los datos de un búfer de vídeo a la memoria del sistema.
| Constante | Valor | Descripción |
|---|---|---|
QVideoFrame::NotMapped | 0x00 | El búfer de vídeo no está asignado a la memoria. |
QVideoFrame::ReadOnly | 0x01 | La memoria asignada se rellena con datos del búfer de vídeo al asignarla, pero el contenido de la memoria asignada puede descartarse al desasignarla. |
QVideoFrame::WriteOnly | 0x02 | La memoria mapeada no está inicializada al mapearla, pero el contenido, que puede haber sido modificado, se utilizará para rellenar el búfer de vídeo al desmapearla. |
QVideoFrame::ReadWrite | ReadOnly | WriteOnly | La memoria mapeada se rellena con datos del búfer de vídeo, y el búfer de vídeo se vuelve a rellenar con el contenido de la memoria mapeada al desasignarla. |
Documentación de funciones miembro
QVideoFrame::QVideoFrame()
Crea un fotograma de vídeo nulo.
[explicit, since 6.8] QVideoFrame::QVideoFrame(const QImage &image)
Crea un objeto `QVideoFrame` a partir de un objeto ` QImage`.
Si el ` QImage::Format ` coincide con uno de los formatos de QVideoFrameFormat::PixelFormat, el `QVideoFrame` contendrá una instancia de ` image ` y utilizará ese formato sin ninguna conversión de formato de píxeles. En este caso, los datos de píxeles solo se copiarán si se llama a ` QVideoFrame::map ` con el indicador ` WriteOnly `, conservando la imagen original.
Por el contrario, si el QImage::Format no coincide con ninguno de los formatos de vídeo, la imagen se convierte primero a un formato (A)RGB compatible mediante QImage::convertedTo() con el indicador Qt::AutoColor. Esto puede suponer una merma en el rendimiento.
Si QImage::isNull() devuelve «true» para el QImage de entrada, el QVideoFrame no será válido y QVideoFrameFormat::isValid() devolverá «false».
Esta función se introdujo en Qt 6.8.
Véase también QVideoFrameFormat::pixelFormatFromImageFormat(), QImage::convertedTo() y QImage::isNull().
QVideoFrame::QVideoFrame(const QVideoFrameFormat &format)
Crea un fotograma de vídeo a partir del píxel dado format.
[explicit, since 6.8] QVideoFrame::QVideoFrame(std::unique_ptr<QAbstractVideoBuffer> videoBuffer)
Crea un `QVideoFrame` a partir de un ` QAbstractVideoBuffer`.
El objeto ` videoBuffer ` especificado hace referencia a una instancia de una clase ` QAbstractVideoBuffer` reimplementada. Se espera que la instancia contenga un búfer de vídeo personalizado preasignado y debe implementar ` QAbstractVideoBuffer::format`, ` QAbstractVideoBuffer::map` y ` QAbstractVideoBuffer::unmap ` para contenido de GPU.
Si ` videoBuffer ` es nulo u obtiene un ` QVideoFrameFormat` no válido, el constructor creará un fotograma de vídeo no válido.
El fotograma creado mantendrá la propiedad del búfer de vídeo especificado durante toda su vida útil. Teniendo en cuenta que `QVideoFrame` se implementa mediante un objeto privado compartido, el búfer de vídeo especificado se destruirá al destruirse la última copia del fotograma de vídeo creado.
Ten en cuenta que, si se ha pasado un fotograma de vídeo a ` QMediaRecorder ` o a una canalización de renderizado, la vida útil del fotograma es indefinida, y el grabador multimedia puede destruirlo en un hilo diferente.
QVideoFrame contendrá su propia instancia de ` QVideoFrameFormat`. Al invocar ` setStreamFrameRate`, ` setMirrored` o ` setRotation`, se puede modificar el formato interno, y ` surfaceFormat ` devolverá una instancia separada.
Esta función se introdujo en Qt 6.8.
Véase también QAbstractVideoBuffer y QVideoFrameFormat.
QVideoFrame::QVideoFrame(const QVideoFrame &other)
Crea una copia superficial de other. Dado que QVideoFrame se comparte explícitamente, estas dos instancias mostrarán el mismo fotograma.
[constexpr noexcept default] QVideoFrame::QVideoFrame(QVideoFrame &&other)
Crea un objeto `QVideoFrame` a partir de ` other`.
[noexcept] QVideoFrame::~QVideoFrame()
Elimina un fotograma de vídeo.
uchar *QVideoFrame::bits(int plane)
Devuelve un puntero al inicio del búfer de datos del fotograma correspondiente a un ` plane`.
Este valor solo es válido mientras los datos del fotograma estén en mapped.
Solo se garantiza que los cambios realizados en los datos a los que se accede a través de este puntero (cuando se asigna con acceso de escritura) se hayan guardado cuando se llame a ` unmap()` y cuando el búfer se haya asignado para escritura.
Véase también ` map()`, ` mappedBytes()`, ` bytesPerLine()` y ` planeCount()`.
const uchar *QVideoFrame::bits(int plane) const
Devuelve un puntero al inicio del búfer de datos de fotograma de un ` plane`.
Este valor solo es válido mientras los datos del fotograma sean un « mapped ».
Si el búfer no se ha asignado con acceso de lectura, el contenido de este búfer estará inicialmente sin inicializar.
Véanse también map(), mappedBytes(), bytesPerLine() y planeCount().
int QVideoFrame::bytesPerLine(int plane) const
Devuelve el número de bytes de una línea de exploración de un plane.
Este valor solo es válido mientras los datos del fotograma sean de tipo « mapped ».
Véase también bits(), map(), mappedBytes() y planeCount().
qint64 QVideoFrame::endTime() const
Devuelve el tiempo de presentación (en microsegundos) en el que un fotograma debe dejar de mostrarse.
Un tiempo no válido se representa como -1.
Véase también setEndTime().
QVideoFrame::HandleType QVideoFrame::handleType() const
Devuelve el tipo del identificador de un fotograma de vídeo.
El tipo de identificador puede ser « NoHandle », lo que significa que el fotograma se basa en memoria, o una textura RHI.
int QVideoFrame::height() const
Devuelve la altura de un fotograma de vídeo.
bool QVideoFrame::isMapped() const
Determina si el contenido de un fotograma de vídeo está actualmente asignado a la memoria del sistema.
Se trata de una función de conveniencia que comprueba que el valor de « MapMode » del fotograma no sea igual a « QVideoFrame::NotMapped ».
Devuelve «true» si el contenido del fotograma de vídeo está asignado a la memoria del sistema y «false» en caso contrario.
Véanse también mapMode() y QVideoFrame::MapMode.
bool QVideoFrame::isReadable() const
Determina si el contenido mapeado de un fotograma de vídeo se leyó del propio fotograma en el momento de su mapeo.
Se trata de una función de conveniencia que comprueba si el objeto ` MapMode ` contiene el indicador ` QVideoFrame::WriteOnly `.
Devuelve «true» si el contenido de la memoria mapeada se leyó del fotograma de vídeo, y «false» en caso contrario.
Véase también mapMode() y QVideoFrame::MapMode.
bool QVideoFrame::isValid() const
Determina si un fotograma de vídeo es válido.
Un fotograma no válido no tiene ningún búfer de vídeo asociado.
Devuelve «true» si el fotograma es válido y «false» si no lo es.
bool QVideoFrame::isWritable() const
Determina si el contenido mapeado de un fotograma de vídeo se conservará cuando se desmapee dicho fotograma.
Se trata de una función de conveniencia que comprueba si el objeto ` MapMode ` contiene el indicador ` QVideoFrame::WriteOnly `.
Devuelve «true» si el fotograma de vídeo se actualizará al desasignarlo, y «false» en caso contrario.
Nota: El resultado de modificar los datos de un fotograma asignado en modo de solo lectura es indefinido. Dependiendo de la implementación del búfer, los cambios pueden conservarse o, en el peor de los casos, alterar un búfer compartido.
Véase también mapMode() y QVideoFrame::MapMode.
bool QVideoFrame::map(QVideoFrame::MapMode mode)
Asigna el contenido de un fotograma de vídeo a la memoria del sistema (accesible por la CPU).
En algunos casos, los datos del fotograma de vídeo pueden estar almacenados en la memoria de vídeo o en otra memoria a la que no se pueda acceder, por lo que es necesario asignar un fotograma antes de acceder a los datos de los píxeles. Esto puede implicar copiar el contenido, por lo que se debe evitar asignar y desasignar a menos que sea necesario.
La función `map mode ` indica si el contenido de la memoria asignada debe leerse y/o escribirse en el fotograma. Si el modo de asignación incluye el indicador ` QVideoFrame::ReadOnly `, la memoria asignada se rellenará con el contenido del fotograma de vídeo al asignarla inicialmente. Si el modo de asignación incluye el indicador ` QVideoFrame::WriteOnly `, el contenido de la memoria asignada, que puede haber sido modificado, se volverá a escribir en el fotograma al desasignarla.
Mientras esté mapeado, se puede acceder directamente al contenido de un fotograma de vídeo a través del puntero devuelto por la función bits().
Cuando ya no sea necesario acceder a los datos, asegúrate de llamar a la función ` unmap()` para liberar la memoria mapeada y, si procede, actualizar el contenido del fotograma de vídeo.
Si el fotograma de vídeo se ha mapeado en modo de solo lectura, está permitido mapearlo varias veces en modo de solo lectura (y desmapearlo el número correspondiente de veces). En todos los demás casos, es necesario desmapear primero el fotograma antes de mapearlo por segunda vez.
Nota: Escribir en memoria asignada como de solo lectura tiene un comportamiento indefinido y puede provocar cambios en los datos compartidos o fallos del sistema.
Devuelve «true» si el fotograma se ha mapeado en memoria en el « mode » indicado y «false» en caso contrario.
Véase también unmap(), mapMode() y bits().
QVideoFrame::MapMode QVideoFrame::mapMode() const
Devuelve el modo en el que se ha mapeado un fotograma de vídeo en la memoria del sistema.
Véase también map() y QVideoFrame::MapMode.
int QVideoFrame::mappedBytes(int plane) const
Devuelve el número de bytes que ocupa el plano plane de los datos de la trama asignada.
Este valor solo es válido mientras los datos de la trama se encuentran en estado « mapped ».
Véase también ` map()`.
bool QVideoFrame::mirrored() const
Indica si el fotograma debe reflejarse respecto a su eje vertical antes de mostrarse.
Las transformaciones de ` QVideoFrame`, concretamente la rotación y el reflejo, se utilizan únicamente para mostrar el fotograma de vídeo y se aplican sobre la transformación de superficie, que viene determinada por ` QVideoFrameFormat`. El reflejo se aplica después de la rotación.
El reflejo suele ser necesario para los fotogramas de vídeo procedentes de la cámara frontal de un dispositivo móvil.
Véase también setMirrored().
void QVideoFrame::paint(QPainter *painter, const QRectF &rect, const QVideoFrame::PaintOptions &options)
Utiliza un ` QPainter`, ` painter`, para renderizar este ` QVideoFrame ` en ` rect`. Se puede utilizar el objeto `PaintOptions` ` options ` para especificar un color de fondo y cómo se debe rellenar ` rect ` con el vídeo.
Nota: al utilizar este método, la renderización suele realizarse sin aceleración por hardware.
QVideoFrameFormat::PixelFormat QVideoFrame::pixelFormat() const
Devuelve el formato de píxeles de este fotograma de vídeo.
int QVideoFrame::planeCount() const
Devuelve el número de planos que hay en el fotograma de vídeo.
Véase también map().
QtVideo::Rotation QVideoFrame::rotation() const
Devuelve el ángulo en el que se debe girar el fotograma en el sentido de las agujas del reloj antes de mostrarlo.
Las transformaciones de ` QVideoFrame`, concretamente la rotación y el reflejo, solo se utilizan para mostrar el fotograma de vídeo y se aplican sobre la transformación de superficie, que viene determinada por ` QVideoFrameFormat`. La rotación se aplica antes que el reflejo.
Véase también ` setRotation()`.
void QVideoFrame::setEndTime(qint64 time)
Establece el « time » de presentación (en microsegundos) en el que un fotograma debe dejar de mostrarse.
Un tiempo no válido se representa como -1.
Véase también endTime().
void QVideoFrame::setMirrored(bool mirrored)
Establece si el fotograma debe someterse a una transformación « mirrored » alrededor de su eje vertical antes de mostrarse.
Las transformaciones de « QVideoFrame », concretamente la rotación y el reflejo, solo se utilizan para mostrar el fotograma de vídeo y se aplican sobre la transformación de superficie, que viene determinada por « QVideoFrameFormat ». El reflejo se aplica después de la rotación.
El reflejo suele ser necesario para los fotogramas de vídeo procedentes de la cámara frontal de un dispositivo móvil.
El valor por defecto es ` false`.
Véase también mirrored().
void QVideoFrame::setRotation(QtVideo::Rotation angle)
Establece el angle: el fotograma debe girarse en el sentido de las agujas del reloj antes de mostrarse.
Las transformaciones de ` QVideoFrame`, concretamente la rotación y el reflejo, solo se utilizan para mostrar el fotograma de vídeo y se aplican sobre la transformación de superficie, que viene determinada por ` QVideoFrameFormat`. La rotación se aplica antes que el reflejo.
El valor por defecto es QtVideo::Rotation::None.
Véase también rotation().
void QVideoFrame::setStartTime(qint64 time)
Establece el « time » de presentación (en microsegundos) en el que se debe mostrar inicialmente el fotograma.
Un tiempo no válido se representa como -1.
Véase también startTime().
void QVideoFrame::setStreamFrameRate(qreal rate)
Establece la velocidad de fotogramas rate de una secuencia de vídeo en fotogramas por segundo.
Véase también streamFrameRate().
void QVideoFrame::setSubtitleText(const QString &text)
Establece el texto de los subtítulos que debe mostrarse junto con este fotograma de vídeo en text.
Véase también subtitleText().
QSize QVideoFrame::size() const
Devuelve las dimensiones de un fotograma de vídeo.
qint64 QVideoFrame::startTime() const
Devuelve el tiempo de presentación (en microsegundos) en el que debe mostrarse el fotograma.
Un tiempo no válido se representa como -1.
Véase también setStartTime().
qreal QVideoFrame::streamFrameRate() const
Devuelve la frecuencia de fotogramas de una transmisión de vídeo en fotogramas por segundo.
Véase también ` setStreamFrameRate()`.
QString QVideoFrame::subtitleText() const
Devuelve el texto del subtítulo que debe mostrarse junto con este fotograma de vídeo.
Véase también setSubtitleText().
QVideoFrameFormat QVideoFrame::surfaceFormat() const
Devuelve el formato de superficie de este fotograma de vídeo.
[noexcept] void QVideoFrame::swap(QVideoFrame &other)
Intercambia el fotograma de vídeo actual con other.
QImage QVideoFrame::toImage() const
Convierte el fotograma de vídeo actual en una imagen.
La conversión se basa en los datos de píxeles actuales y en el objeto ` surface format`. Las transformaciones del fotograma no afectan al resultado, ya que se aplican únicamente con fines de presentación.
void QVideoFrame::unmap()
Libera la memoria asignada mediante la función ` map()`.
Si la función ` MapMode ` incluía el indicador ` QVideoFrame::WriteOnly `, esto conservará el contenido actual de la memoria mapeada en el fotograma de vídeo.
No se debe llamar a `unmap()` si la función ` map()` ha fallado.
Véase también map().
int QVideoFrame::width() const
Devuelve la anchura de un fotograma de vídeo.
bool QVideoFrame::operator!=(const QVideoFrame &other) const
Devuelve ` true ` si ` QVideoFrame ` y ` other ` no corresponden al mismo fotograma.
[noexcept] QVideoFrame &QVideoFrame::operator=(QVideoFrame &&other)
Traslada other a esta dirección: QVideoFrame.
QVideoFrame &QVideoFrame::operator=(const QVideoFrame &other)
Asigna el contenido de other a este fotograma de vídeo. Dado que QVideoFrame se comparte de forma explícita, estas dos instancias mostrarán el mismo fotograma.
bool QVideoFrame::operator==(const QVideoFrame &other) const
Devuelve « true » si « QVideoFrame » y « other » hacen referencia al mismo fotograma.
© 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.