Gráfico de escenas - Importación de texturas de metal
Muestra cómo utilizar una textura creada directamente con Metal.
El ejemplo Metal Texture Import muestra cómo una aplicación puede importar y utilizar una MTLTexture en la escena Qt Quick. Esto proporciona una alternativa a los enfoques underlay o overlay a la hora de integrar el renderizado nativo de Metal. En muchos casos, pasar por una textura, y por tanto "aplanar" primero los contenidos 3D, es la mejor opción para integrar y mezclar contenidos 3D personalizados con los elementos de interfaz de usuario 2D proporcionados por Qt Quick.
import MetalTextureImport CustomTextureItem { id: renderer anchors.fill: parent anchors.margins: 10 SequentialAnimation on t { NumberAnimation { to: 1; duration: 2500; easing.type: Easing.InQuad } NumberAnimation { to: 0; duration: 2500; easing.type: Easing.OutQuad } loops: Animation.Infinite running: true }
La aplicación expone una subclase personalizada de QQuickItem bajo el nombre de CustomTextureItem. Esta se instancia en QML. El valor de la propiedad t también se anima.
class CustomTextureItem : public QQuickItem { Q_OBJECT Q_PROPERTY(qreal t READ t WRITE setT NOTIFY tChanged) QML_ELEMENT public: CustomTextureItem(); qreal t() const { return m_t; } void setT(qreal t); signals: void tChanged(); protected: QSGNode *updatePaintNode(QSGNode *, UpdatePaintNodeData *) override; void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry) override; private slots: void invalidateSceneGraph(); private: void releaseResources() override; CustomTextureNode *m_node = nullptr; qreal m_t = 0; };
La implementación de nuestro ítem personalizado implica sobreescribir QQuickItem::updatePaintNode(), así como funciones y ranuras relacionadas con cambios de geometría y limpieza.
class CustomTextureNode : public QSGTextureProvider, public QSGSimpleTextureNode
{
Q_OBJECT
public:
CustomTextureNode(QQuickItem *item);
~CustomTextureNode();
QSGTexture *texture() const override;
void sync();También necesitamos un nodo scenegraph. En lugar de derivar directamente de QSGNode, podemos utilizar QSGSimpleTextureNode, que nos proporciona parte de la funcionalidad preimplementada por conveniencia.
QSGNode *CustomTextureItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
{
CustomTextureNode *n = static_cast<CustomTextureNode *>(node);
if (!n && (width() <= 0 || height() <= 0))
return nullptr;
if (!n) {
m_node = new CustomTextureNode(this);
n = m_node;
}
m_node->sync();
n->setTextureCoordinatesTransform(QSGSimpleTextureNode::NoTransform);
n->setFiltering(QSGTexture::Linear);
n->setRect(0, 0, width(), height());
window()->update(); // ensure getting to beforeRendering() at some point
return n;
}La función updatePaintNode() del item es llamada en el hilo de renderizado (si hay uno), con el hilo principal (GUI) bloqueado. Aquí creamos un nuevo nodo si aún no ha habido uno, y lo actualizamos. El acceso a objetos Qt que viven en el hilo principal es seguro aquí, por lo que sync() calculará y copiará los valores que necesita de QQuickItem o QQuickWindow.
CustomTextureNode::CustomTextureNode(QQuickItem *item)
: m_item(item)
{
m_window = m_item->window();
connect(m_window, &QQuickWindow::beforeRendering, this, &CustomTextureNode::render);
connect(m_window, &QQuickWindow::screenChanged, this, [this]() {
if (m_window->effectiveDevicePixelRatio() != m_dpr)
m_item->update();
});El nodo no sólo se basa en la típica secuencia de actualización QQuickItem - QSGNode, sino que también se conecta a QQuickWindow::beforeRendering(). Ahí es donde se actualizará el contenido de la textura Metal codificando un pase de renderizado completo, dirigido a la textura, en el buffer de comandos del scenegraph de Qt Quicks. beforeRendering() es el lugar adecuado para esto, porque la señal se emite antes de que Qt Quick comience a codificar sus propios comandos de renderizado. Elegir QQuickWindow::beforeRenderPassRecording() en su lugar sería un error en este ejemplo.
void CustomTextureNode::sync()
{
m_dpr = m_window->effectiveDevicePixelRatio();
const QSize newSize = m_window->size() * m_dpr;
bool needsNew = false;
if (!texture())
needsNew = true;
if (newSize != m_size) {
needsNew = true;
m_size = newSize;
}
if (needsNew) {
delete texture();
[m_texture release];
QSGRendererInterface *rif = m_window->rendererInterface();
m_device = (id<MTLDevice>) rif->getResource(m_window, QSGRendererInterface::DeviceResource);
Q_ASSERT(m_device);
MTLTextureDescriptor *desc = [[MTLTextureDescriptor alloc] init];
desc.textureType = MTLTextureType2D;
desc.pixelFormat = MTLPixelFormatRGBA8Unorm;
desc.width = m_size.width();
desc.height = m_size.height();
desc.mipmapLevelCount = 1;
desc.resourceOptions = MTLResourceStorageModePrivate;
desc.storageMode = MTLStorageModePrivate;
desc.usage = MTLTextureUsageShaderRead | MTLTextureUsageRenderTarget;
m_texture = [m_device newTextureWithDescriptor: desc];
[desc release];
QSGTexture *wrapper = QNativeInterface::QSGMetalTexture::fromNative(m_texture, m_window, m_size);
qDebug() << "Got QSGTexture wrapper" << wrapper << "for an MTLTexture of size" << m_size;
setTexture(wrapper);
}
m_t = float(static_cast<CustomTextureItem *>(m_item)->t());Después de copiar los valores que necesitamos, sync() también realiza alguna inicialización de los recursos gráficos. El MTLDevice es consultado desde el scenegraph. Una vez que la MTLTexture está disponible, se crea un QSGTexture que la envuelve (no la posee) a través de QNativeInterface::QSGOpenGLTexture::fromNative(). Finalmente, QSGTexture se asocia con los materiales subyacentes llamando a la función setTexture() de la clase base.
void CustomTextureNode::render()
{
if (!m_initialized)
return;
// Render to m_texture.
MTLRenderPassDescriptor *renderpassdesc = [MTLRenderPassDescriptor renderPassDescriptor];
MTLClearColor c = MTLClearColorMake(0, 0, 0, 1);
renderpassdesc.colorAttachments[0].loadAction = MTLLoadActionClear;
renderpassdesc.colorAttachments[0].storeAction = MTLStoreActionStore;
renderpassdesc.colorAttachments[0].clearColor = c;
renderpassdesc.colorAttachments[0].texture = m_texture;
QSGRendererInterface *rif = m_window->rendererInterface();
id<MTLCommandBuffer> cb = (id<MTLCommandBuffer>) rif->getResource(m_window, QSGRendererInterface::CommandListResource);
Q_ASSERT(cb);
id<MTLRenderCommandEncoder> encoder = [cb renderCommandEncoderWithDescriptor: renderpassdesc];
const QQuickWindow::GraphicsStateInfo &stateInfo(m_window->graphicsStateInfo());
void *p = [m_ubuf[stateInfo.currentFrameSlot] contents];
memcpy(p, &m_t, 4);
MTLViewport vp;
vp.originX = 0;
vp.originY = 0;
vp.width = m_size.width();
vp.height = m_size.height();
vp.znear = 0;
vp.zfar = 1;
[encoder setViewport: vp];
[encoder setFragmentBuffer: m_ubuf[stateInfo.currentFrameSlot] offset: 0 atIndex: 0];
[encoder setVertexBuffer: m_vbuf offset: 0 atIndex: 1];
[encoder setRenderPipelineState: m_pipeline];
[encoder drawPrimitives: MTLPrimitiveTypeTriangleStrip vertexStart: 0 vertexCount: 4 instanceCount: 1 baseInstance: 0];
[encoder endEncoding];
}render(), la ranura conectada a beforeRendering(), codifica los comandos de renderizado utilizando los buffers y los objetos de estado del pipeline creados en sync().
© 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.
