En esta página

QRhiTextureRenderTargetDescription Class

Describe el color y la profundidad, o los complementos de profundidad/plantilla, de un destino de renderizado. 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

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.12) int depthLayer() 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.12) void setDepthLayer(int depthLayer)
(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 destino de renderizado de texturas tiene cero o más texturas como adjuntos de color, cero o un búfer de renderizado como búfer combinado de profundidad/plantilla, o cero o una textura como búfer de profundidad.

Nota: No se pueden establecer simultáneamente` depthStencilBuffer()` y ` depthTexture()` (no pueden ser distintos de nulo al mismo tiempo).

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

Gracias a los constructores, la selección de una textura (sin búfer de profundidad ni de estencil) es sencilla:

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

El siguiente código crea un destino de renderizado de textura configurado para apuntar al nivel mip n.º 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 habitual, en el que se utiliza una textura como adjunto de color y un búfer de renderizado como búfer de profundidad/estarcido para habilitar la comprobación 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 habilitar el renderizado multisample de forma portátil (de modo que también sea compatible con OpenGL ES 3.0), se utiliza un « QRhiRenderBuffer » como búfer de color (multisample) y, a continuación, se resuelve en una textura 2D normal (no multisample). Para habilitar la comprobación de profundidad, se utiliza también un búfer de profundidad-plantilla, que además debe emplear el mismo número 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 se habilita la resolución multimuestra, es posible que los datos multimuestra no se escriban en absoluto. Esto significa que la textura multimuestra de un anexo de color no debe utilizarse posteriormente con sombreadores para el muestreo (u otros fines) siempre que se establezca una textura de resolución, ya que el búfer de color multimuestra es entonces simplemente un almacenamiento intermedio al que, en algunas arquitecturas de GPU, no se le escriben datos en absoluto. Véase PreserveColorContents para más detalles.

Nota: Cuando se utilice ` setDepthTexture()` en lugar de ` setDepthStencilBuffer()` y los datos de profundidad (plantilla) no sean de interés posteriormente, establezca el indicador `DoNotStoreDepthStencilContents` en ` QRhiTextureRenderTarget`. Esto permite indicar a la API 3D subyacente que los datos de profundidad/plantilla pueden descartarse, lo que podría traducirse en un mejor rendimiento con arquitecturas de GPU en mosaico. Cuando el búfer de profundidad-estencil es un « QRhiRenderBuffer » (y también en el caso de la textura de color multisample, véase la nota anterior), esto queda implícito, pero con un «depth (stencil) 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 posteriormente en un shader).

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

Véase también QRhiColorAttachment y QRhiTextureRenderTarget.

Documentación de las funciones miembro

[constexpr noexcept default] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()

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

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)

Crea una descripción del destino de renderizado de textura con un elemento adjunto definido en colorAttachment.

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

Crea una descripción de un destino de renderizado de textura con dos anexos: un anexo de color descrito por colorAttachment y un anexo de profundidad/plantilla descrito por depthStencilBuffer.

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

Crea una descripción de un destino 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 const que apunta al primer elemento de la lista de archivos adjuntos.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const

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

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

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

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const

Devuelve el número de accesorios de color configurados actualmente.

[since 6.12] int QRhiTextureRenderTargetDescription::depthLayer() const

Devuelve el índice de la sección del array que se utilizará para la conexión de profundidad/estarcido, o -1 por defecto.

Esta función se introdujo en Qt 6.12.

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

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

Devuelve la textura a la que se resuelve una textura de profundidad multisample (o de profundidad-estencil) (o matriz de texturas). Devuelve « nullptr » si no hay ninguna, que es el caso más habitual.

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 renderizado utilizado como búfer de profundidad-estencil, o nullptr si no se ha establecido ninguno.

Véase también setDepthStencilBuffer().

QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const

Devuelve la textura de profundidad a la que se hace referencia 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 archivos adjuntos de colores mediante los iteradores first y last.

[since 6.12] void QRhiTextureRenderTargetDescription::setDepthLayer(int depthLayer)

Establece el índice de la sección del array que se utilizará para la asignación de profundidad/plantilla.

Pasa -1 (el valor por defecto) para no seleccionar una capa concreta. Cuando se establece en un valor no negativo, el destino de renderizado adjunta una vista que apunta exactamente a esa capa (segmento) de la textura de profundidad. Esto solo es efectivo cuando se proporciona una textura de profundidad de matriz 2D mediante ` setDepthTexture()`; de lo contrario, el valor se ignora.

El valor debe estar dentro del tamaño de la matriz de la textura de profundidad; pasar un índice fuera de rango provoca un comportamiento indefinido. El índice es absoluto con respecto a la textura subyacente, independientemente de cualquier rango de matriz que se haya especificado al crear la textura.

Al especificar un ` depthLayer `, se desactiva el renderizado en capas o multivista para el anexo de profundidad.

Esta función se introdujo en Qt 6.12.

Véase también ` depthLayer()` y ` setDepthTexture()`.

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

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

tex Se espera que sea una textura 2D o una matriz de texturas 2D con un formato que coincida con el de la textura establecida mediante setDepthTexture().

Nota: La resolución de datos de profundidad (o profundidad-estencil) solo funciona cuando la función QRhi::ResolveDepthStencil se indica como compatible en tiempo de ejecución. La compatibilidad con la resolución de profundidad-estencil no está disponible de forma universal en todas las API gráficas. Por lo tanto, los diseños que asumen la disponibilidad incondicional de la resolución de profundidad-estencil no son portables y deben evitarse.

Nota: Como limitación adicional específica de OpenGL ES, la configuración de una textura de resolución de profundidad solo puede funcionar en combinación con ` setDepthTexture()` (), y no con ` setDepthStencilBuffer()` ().

Esta función se introdujo en Qt 6.8.

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

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)

Establece el valor de « renderBuffer » para la profundidad-estencil. No es obligatorio; por ejemplo, cuando no se utilicen pruebas de profundidad, escrituras de profundidad ni funciones relacionadas con el estencil en ninguna de las tuberías gráficas de ninguna de las pasadas de renderizado de este destino de renderizado, se puede dejar establecido en « nullptr ».

Nota: No se pueden establecer a la vezdepthStencilBuffer() y depthTexture() (no pueden ser distintos de nulo al mismo tiempo).

Es muy habitual utilizar un « QRhiRenderBuffer » en lugar de un « QRhiTexture » 2D como búfer de profundidad o de profundidad/plantilla, y es el enfoque recomendado para las aplicaciones. El uso de un « QRhiTexture » y, por lo tanto, de « setDepthTexture()» cobra relevancia si se pretende acceder posteriormente a los datos de profundidad (por ejemplo, muestrearlos en un shader) o cuando interviene « multiview rendering » (ya que, en ese caso, la textura de profundidad debe ser una matriz de texturas).

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

void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)

Establece el « texture » para la pila de profundidad-estencil. Se trata de una alternativa a « setDepthStencilBuffer()», en la que, en lugar de un « QRhiRenderBuffer », se proporciona un « QRhiTexture » con un tipo adecuado (por ejemplo, « QRhiTexture::D32F »).

Nota: No se pueden establecer a la vezdepthStencilBuffer() y depthTexture() (no pueden ser distintos de nulo 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 estarcido, como QRhiTexture::D24S8, también servirá como búfer de estarcido.

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

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

Se asocia con el QRhiShadingRateMap map especificado. Esto solo funciona cuando se indica que la función QRhi::VariableRateShadingMap es compatible.

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

Nota: Cuando el destino de renderizado ya se ha creado (se ha llamado a `create()` con éxito), establecer un mapa de tasas de sombreado implica que se necesita un nuevo ` QRhiRenderPassDescriptor ` diferente y, por lo tanto, es necesario volver a crearlo. Vuelve a llamar a setRenderPassDescriptor() (fuera de una pasada de renderizado) y, a continuación, vuelve a compilar llamando a create(). Esto también tiene otras consecuencias en cadena; por ejemplo, en el caso de los flujos de trabajo gráficos: estos también deben asociarse al nuevo QRhiRenderPassDescriptor y, a continuación, volver a compilarse. Consulta QRhiRenderPassDescriptor::serializedFormat() para obtener algunas sugerencias sobre cómo abordar esto. Recuerda establecer también el indicador 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.