Back to Qt.io
Contact Us Blog Download Qt
En esta página

QRhiTextureRenderTargetDescription Class

Describe el color y la profundidad o los anexos de profundidad/esténcil de un objetivo de renderizado. Más...

Cabecera: #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

QRhiTextureRenderTargetDescription()
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)
const QRhiColorAttachment *cbeginColorAttachments() const
const QRhiColorAttachment *cendColorAttachments() const
const QRhiColorAttachment *colorAttachmentAt(qsizetype index) const
qsizetype colorAttachmentCount() const
(since 6.8) QRhiTexture *depthResolveTexture() const
QRhiRenderBuffer *depthStencilBuffer() const
QRhiTexture *depthTexture() const
void setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
void setColorAttachments(InputIterator first, InputIterator last)
(since 6.8) void setDepthResolveTexture(QRhiTexture *tex)
void setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
void setDepthTexture(QRhiTexture *texture)
(since 6.9) void setShadingRateMap(QRhiShadingRateMap *map)
(since 6.9) QRhiShadingRateMap *shadingRateMap() const

Descripción Detallada

Un objetivo de render de textura tiene cero o más texturas como adjuntos de color, cero o un búfer de render como búfer combinado de profundidad/esténcil o cero o una textura como búfer de profundidad.

Nota: depthStencilBuffer() y depthTexture() no pueden ser ambos establecidos (no pueden ser no-nulos al mismo tiempo).

Veamos algunos ejemplos de uso en combinación con QRhiTextureRenderTarget.

Debido a los constructores, el targeting de una textura (y sin depth/stencil buffer) es simple:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));

Lo siguiente crea un objetivo de render de textura que está configurado para apuntar al nivel mip #2 de una textura:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped);
texture->create();
QRhiColorAttachment colorAtt(texture);
colorAtt.setLevel(2);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });

Otro ejemplo, esta vez para renderizar en una textura de profundidad:

QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
shadowMap->create();
QRhiTextureRenderTargetDescription rtDesc;
rtDesc.setDepthTexture(shadowMap);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Un caso muy común, tener una textura como el color adjunto y un búfer de renderizado como profundidad/esténcil para permitir pruebas de profundidad:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512));
depthStencil->create();
QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Por último, para permitir el renderizado multimuestra de una manera portátil (por lo que también es compatible con OpenGL ES 3.0), utilizando un QRhiRenderBuffer como el búfer de color (multimuestra) y luego resolviendo en una textura 2D normal (no multimuestra). Para permitir las pruebas de profundidad, también se utiliza un búfer de profundidad-esténcil, que también debe utilizar el mismo recuento de muestras:

QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA
colorBuffer->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4);
depthStencil->create();
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiColorAttachment colorAtt(colorBuffer);
colorAtt.setResolveTexture(texture);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });

Nota: cuando la resolución multimuestra está activada, es posible que los datos multimuestra no se escriban en absoluto. Esto significa que la textura multimuestra en un adjunto de color no debe ser usada después con shaders para muestreo (u otros propósitos) siempre que se establezca una textura de resolución, ya que el buffer de color multimuestra es meramente un almacenamiento intermedio que no recibe datos escritos de vuelta en algunas arquitecturas de GPU. Véase PreserveColorContents para más detalles.

Nota: Cuando se utiliza setDepthTexture(), no setDepthStencilBuffer(), y los datos de profundidad (stencil) no son de interés después, establece la bandera DoNotStoreDepthStencilContents en QRhiTextureRenderTarget. Esto permite indicar a la API 3D subyacente que los datos de profundidad/stencil pueden ser descartados, lo que potencialmente conduce a un mejor rendimiento con arquitecturas GPU en mosaico. Cuando el búfer de profundidad/esténcil es un QRhiRenderBuffer (y también para la textura de color multimuestra, véase la nota anterior) esto está implícito, pero con una profundidad (esténcil) QRhiTexture la intención debe declararse explícitamente. Por defecto QRhi asume que los datos son de interés (por ejemplo, la textura de profundidad se muestrea en un shader después).

Nota: Esta es una API RHI con garantías de compatibilidad limitadas, véase QRhi para más detalles.

Véase también QRhiColorAttachment y QRhiTextureRenderTarget.

Documentación de las funciones miembro

[constexpr noexcept] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()

Construye una descripción de destino de renderizado de textura vacía.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)

Construye una descripción de objetivo de renderizado de textura con un adjunto descrito por colorAttachment.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)

Construye una descripción de objetivo de renderizado de textura con dos adjuntos, un adjunto de color descrito por colorAttachment, y un adjunto de profundidad/esténcil con depthStencilBuffer.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)

Construye una descripción de objetivo de renderizado de textura con dos adjuntos, un adjunto de color descrito por colorAttachment, y un adjunto de profundidad con depthTexture.

Nota: depthTexture debe tener un formato adecuado, como QRhiTexture::D16 o QRhiTexture::D32F.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const

Devuelve un iterador constante que apunta al primer elemento de la lista de adjuntos.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const

Devuelve un iterador constante que apunta justo después del último elemento de la lista de adjuntos.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const

Devuelve el color adjunto en la dirección index especificada.

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const

Devuelve el número de adjuntos de color establecidos actualmente.

[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const

Devuelve la textura a la que se resuelve una textura (o matriz de texturas) multimuestra de profundidad (o profundidad-esténcil). nullptr si no hay ninguna, que es el caso más común.

Esta función se introdujo en Qt 6.8.

Véase también setDepthResolveTexture(), QRhiColorAttachment::resolveTexture(), y depthTexture().

QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const

Devuelve el búfer de render utilizado como búfer de profundidad, o nullptr si no se ha establecido ninguno.

Véase también setDepthStencilBuffer().

QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const

Devuelve la textura de profundidad referenciada actualmente, o nullptr si no se ha establecido ninguna.

Véase también setDepthTexture().

void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)

Establece el list de los archivos adjuntos de color.

template <typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)

Establece la lista de colores adjuntos mediante los iteradores first y last.

[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)

Establece la textura de resolución de profundidad (o depth-stencil) tex.

tex se espera que sea una textura 2D o una matriz de texturas 2D con un formato que coincida con la textura establecida a través de setDepthTexture().

Nota: La resolución de datos de profundidad (o depth-stencil) sólo es funcional cuando la característica QRhi::ResolveDepthStencil se reporta como soportada en tiempo de ejecución. El soporte para la resolución de depth-stencil no está disponible universalmente entre las APIs gráficas. Por lo tanto, los diseños que asuman la disponibilidad incondicional de la resolución de depth-stencil no son portables y deben evitarse.

Nota: Como limitación adicional para OpenGL ES en particular, establecer una textura de resolución de profundidad sólo puede ser funcional en combinación con setDepthTexture(), no con setDepthStencilBuffer().

Esta función se introdujo en Qt 6.8.

Véase también depthResolveTexture(), QRhiColorAttachment::setResolveTexture(), y setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)

Establece renderBuffer para el stencil de profundidad. No es obligatorio, por ejemplo, cuando no se utiliza ninguna prueba de profundidad/escritura o características relacionadas con el stencil dentro de cualquier canal de gráficos en cualquiera de los pases de renderizado para este objetivo de renderizado, se puede dejar establecido en nullptr.

Nota: depthStencilBuffer() y depthTexture() no pueden tener ambos valores (no pueden ser no nulos al mismo tiempo).

Usar un QRhiRenderBuffer sobre un QRhiTexture 2D como buffer de profundidad o profundidad/estencil es muy común, y es la aproximación recomendada para aplicaciones. El uso de QRhiTexture, y por lo tanto setDepthTexture() se vuelve relevante si se pretende acceder a los datos de profundidad (por ejemplo, muestreados en un shader) después, o cuando multiview rendering está involucrado (porque entonces la textura de profundidad debe ser una matriz de textura).

Véase también depthStencilBuffer() y setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)

Establece el texture para el depth-stencil. Se trata de una alternativa a setDepthStencilBuffer(), donde en lugar de un QRhiRenderBuffer se proporciona un QRhiTexture con un tipo adecuado (por ejemplo, QRhiTexture::D32F).

Nota: depthStencilBuffer() y depthTexture() no pueden estar ambos establecidos (no pueden ser no nulos al mismo tiempo).

texture puede ser una textura 2D o una matriz de texturas 2D (cuando se admiten matrices de texturas). Especificar una matriz de texturas es relevante en particular con multiview rendering.

Nota: Si texture es un formato con un componente de stencil, como QRhiTexture::D24S8, servirá también como búfer de stencil.

Véase también depthTexture() y setDepthStencilBuffer().

[since 6.9] void QRhiTextureRenderTargetDescription::setShadingRateMap(QRhiShadingRateMap *map)

Se asocia con el QRhiShadingRateMap especificado map. Esto es funcional sólo cuando la característica QRhi::VariableRateShadingMap es reportada como soportada.

Cuando también se llama a QRhiCommandBuffer::setShadingRate(), se utiliza la mayor de las dos tasas de sombreado para cada mosaico. Actualmente no se ofrece ningún control sobre el comportamiento del combinador.

Nota: Cuando el objetivo de renderizado ya había sido construido (create() fue llamado con éxito), establecer un mapa de tasa de sombreado implica que se necesita un nuevo y diferente QRhiRenderPassDescriptor y por lo tanto se necesita una reconstrucción. Llame a setRenderPassDescriptor() de nuevo (fuera de un pase de render) y luego reconstruya llamando a create(). Esto tiene otras consecuencias también, por ejemplo para los pipelines gráficos: estos también necesitan ser asociados con el nuevo QRhiRenderPassDescriptor y luego reconstruidos. Ver QRhiRenderPassDescriptor::serializedFormat() para algunas sugerencias sobre cómo tratar con esto. Recuerde también establecer la bandera QRhiGraphicsPipeline::UsesShadingRate.

Esta función se introdujo en Qt 6.9.

Véase también shadingRateMap().

[since 6.9] QRhiShadingRateMap *QRhiTextureRenderTargetDescription::shadingRateMap() const

Devuelve el valor actual de QRhiShadingRateMap. Por defecto es nullptr.

Esta función se introdujo en Qt 6.9.

Véase también setShadingRateMap().

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