En esta página

QRhiTextureSubresourceUploadDescription Class

Describe la fuente de un nivel MIP en una capa durante una operación de carga de texturas. Más información...

Encabezado: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Desde: Qt 6.6

Funciones públicas

QRhiTextureSubresourceUploadDescription()
QRhiTextureSubresourceUploadDescription(const QByteArray &data)
QRhiTextureSubresourceUploadDescription(const QImage &image)
QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)
QByteArray data() const
quint32 dataStride() const
QPoint destinationTopLeft() const
QImage image() const
void setData(const QByteArray &data)
void setDataStride(quint32 stride)
void setDestinationTopLeft(const QPoint &p)
void setImage(const QImage &image)
void setSourceSize(const QSize &size)
void setSourceTopLeft(const QPoint &p)
QSize sourceSize() const
QPoint sourceTopLeft() const

Descripción detallada

El contenido de origen se especifica como un « QImage » o como un blob sin procesar. El primero solo se permite para texturas sin comprimir con un formato que se pueda asignar a « QImage », mientras que el segundo es compatible con todos los formatos, incluidos los de punto flotante y los comprimidos.

Nota: No se pueden establecer al mismo tiempo` image()` y ` data()`.

destinationTopLeft() especifica la esquina superior izquierda del rectángulo de destino. El valor por defecto es (0, 0).

Un sourceSize() vacío (el valor por defecto) indica que se asume que el tamaño es el del subrecurso. En las subidas basadas en QImage, esto implica que el tamaño del image() de origen debe coincidir con el del subrecurso. Si, por el contrario, se proporcionan datos sin procesar, debe indicarse un número suficiente de bytes en data().

sourceTopLeft() solo es compatible con las subidas basadas en QImage y especifica la esquina superior izquierda del rectángulo de origen.

Nota: Establecer sourceSize() o sourceTopLeft() puede desencadenar una copia de QImage internamente, dependiendo del formato y del backend.

Al proporcionar datos sin procesar, y si el paso no se especifica mediante setDataStride(), el paso (espaciado entre filas, longitud de fila en bytes) de los datos proporcionados debe ser igual a width * pixelSize, donde pixelSize es el número de bytes utilizados para un píxel, y no debe haber relleno adicional entre filas. No hay ningún requisito de alineación al inicio de las filas.

Cuando haya datos no utilizados al final de cada fila en los datos sin procesar de entrada, llama a setDataStride() con el número total de bytes por fila. El paso debe ser siempre un múltiplo del número de bytes por píxel. El paso de fila solo es aplicable a los datos de imagen para texturas con formato sin comprimir.

Nota: El formato de los datos de origen debe ser compatible con el formato de la textura. En muchas API gráficas, los datos se copian tal cual a un búfer de preparación; QRhi no proporciona ninguna conversión de formato intermedia. Esto se aplica también a los formatos de punto flotante; por ejemplo, RGBA16F requiere que los datos de origen estén en formato de punto flotante de media precisión.

Nota: La configuración del «stride» mediante ` setDataStride()` solo funciona cuando ` QRhi::ImageDataStride ` devuelve ` supported`. En la práctica, cabe esperar que esto sea compatible en todas partes, excepto en OpenGL ES 2.0.

Nota: Cuando se especifica un QImage, el stride devuelto por QImage::bytesPerLine() se tiene en cuenta automáticamente.

Advertencia: Cuando se proporciona un ` QImage ` y el ` QImage ` no es propietario de los datos de píxeles subyacentes, corresponde al autor de la llamada garantizar que los datos asociados permanezcan válidos hasta el final del fotograma. (No basta con enviar el lote de actualización de recursos; los datos deben permanecer válidos hasta que se llame a ` QRhi::endFrame()` para que sean portables a todos los backends). Si esto no se puede garantizar, se recomienda encarecidamente al autor de la llamada que llame a `QImage::detach()` sobre la imagen antes de pasarla a `uploadTexture()`.

Nota: Se trata de una API RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.

Véase también QRhiTextureUploadDescription.

Documentación de las funciones miembro

[noexcept default] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()

Crea una descripción de subrecurso vacía.

Nota: una descripción QRhiTextureSubresourceUploadDescription vacía no tiene utilidad por sí sola y no debe enviarse a un QRhiTextureUploadEntry. Como mínimo, primero deben establecerse una imagen o unos datos.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QByteArray &data)

Crea una descripción del nivel MIP con los datos de imagen especificados en data. Es adecuado también para formatos de punto flotante y comprimidos.

[explicit] QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const QImage &image)

Crea una descripción del nivel mip con un ` image`.

El « size » de « image » debe coincidir con el tamaño del nivel de mip. Para el nivel 0, se trata del « texture size ».

La profundidad de bits de « image » debe ser compatible con « texture format ».

Para describir una subida parcial, llama posteriormente a setSourceSize(), setSourceTopLeft() o setDestinationTopLeft().

QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription(const void *data, quint32 size)

Crea una descripción del nivel MIP con los datos de la imagen especificados en data y size. Esto también es adecuado para formatos de punto flotante y comprimidos.

data Se puede eliminar o modificar sin problema una vez que esta función haya finalizado.

QByteArray QRhiTextureSubresourceUploadDescription::data() const

Devuelve los datos de píxeles sin procesar actualmente configurados.

Véase también setData().

quint32 QRhiTextureSubresourceUploadDescription::dataStride() const

Devuelve el paso de datos establecido actualmente.

Véase también setDataStride().

QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const

Devuelve la posición superior izquierda del destino establecida actualmente. El valor por defecto es (0, 0).

Véase también setDestinationTopLeft().

QImage QRhiTextureSubresourceUploadDescription::image() const

Devuelve el valor de « QImage » establecido actualmente.

Véase también setImage().

void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)

Establece data.

Nota: No se pueden establecer al mismo tiempoimage() y data().

Véase también data().

void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)

Establece el paso de datos ( stride ) en bytes. Por defecto, este valor es 0 y no siempre es relevante. Cuando se proporcionan datos sin procesar data() y no se especifica el paso mediante setDataStride(), el paso (espaciado entre filas, longitud de fila en bytes) de los datos proporcionados debe ser igual a width * pixelSize, donde pixelSize es el número de bytes utilizados por píxel, y no debe haber relleno adicional entre filas. De lo contrario, si hay espacio adicional entre las líneas, establezca un valor distinto de cero en stride. Todo esto solo es aplicable cuando se proporcionan datos de imagen sin procesar, y no es necesario cuando se trabaja c QImage, ya que este tiene su propio valor stride.

Nota: Cuando se establezca un stride distinto de cero, asegúrate de que los datos contengan también el relleno final de la última fila, es decir, al menos stride * height bytes en total. Aunque proporcionar los datos sin el relleno de la última fila (es decir, interpretar que el stride no se aplica a la última fila) podría ser seguro —y, de hecho, lo es con Vulkan, OpenGL y D3D12, esto no se puede garantizar para todos los backends, por lo que lo más seguro es evitarlo y tratar la última fila como todas las demás.

Nota: La configuración del stride mediante setDataStride() solo funciona cuando QRhi::ImageDataStride se indica como supported.

Nota: Cuando se especifica un ` QImage `, el paso devuelto por ` QImage::bytesPerLine()` se tiene en cuenta automáticamente, por lo que no es necesario establecer el paso de datos manualmente.

Véase también dataStride().

void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)

Establece la posición superior izquierda de destino p.

Nota: En el caso más habitual, en el que los datos de la imagen proceden de QImage, Qt limita los tamaños de carga de texturas no válidos cuando la posición de destino más el tamaño de origen superan el tamaño de la subrecurso de textura de destino (es decir, el tamaño en el nivel de mip dado). En este caso, también se muestra un mensaje « qWarning()» en la salida de depuración. Esto se hace para evitar confusiones cuando las API 3D subyacentes se bloquean y provocan la eliminación de dispositivos GPU en un momento posterior al enviar los comandos. En cualquier caso, se recomienda a los desarrolladores que validen siempre las aplicaciones ejecutándolas con las capas de validación/depuración de Vulkan, D3D12 o Metal activadas, ya que estas ofrecen una gama mucho más amplia de comprobaciones sobre el uso de la API.

Véase también destinationTopLeft().

void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)

Establece ` image`. Al cargar las texturas, los datos de la imagen se leerán tal cual, sin conversiones de formato.

Nota: No es posible establecer a la vezimage() y data().

Véase también image().

void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)

Establece el origen size en píxeles.

Nota: Al establecer ` sourceSize()` o ` sourceTopLeft()`, puede activarse internamente una copia ` QImage `, dependiendo del formato y del backend.

Véase también sourceSize().

void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)

Establece la posición de la esquina superior izquierda de la fuente p.

Nota: Al establecer sourceSize() o sourceTopLeft() puede activarse internamente una copia QImage, dependiendo del formato y del backend.

Véase también sourceTopLeft().

QSize QRhiTextureSubresourceUploadDescription::sourceSize() const

Devuelve el tamaño de la fuente en píxeles. Por defecto, se trata de un objeto ` QSize` creado de forma predeterminada, que hace referencia a todo el subrecurso.

Véase también setSourceSize().

QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const

Devuelve la posición actual del origen en la esquina superior izquierda. El valor por defecto es (0, 0).

Véase también setSourceTopLeft().

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