Grafo de escena: importación de texturas Metal
Muestra cómo utilizar una textura creada directamente con Metal.
Qt Quick" src="images/metaltextureimport-example.jpg" title="«Squircle» convertido en una textura «Metal» y mostrado en un elemento de Qt Quick"/>
El ejemplo «Importación de texturas Metal» muestra cómo una aplicación puede importar y utilizar una MTLTexture en la escena de Qt Quick. Esto ofrece una alternativa a los enfoques de superposición o subyacente a la hora de integrar el renderizado nativo de Metal. En muchos casos, pasar por una textura —y, por lo tanto, «aplanar» primero los contenidos 3D— es la mejor opción para integrar y mezclar contenidos 3D personalizados con los elementos de la interfaz de usuario 2D que proporciona 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 ` con 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 elemento personalizado implica sobrescribir QQuickItem::updatePaintNode(), así como las funciones y slots relacionados con los cambios de geometría y la 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 de grafo de escena. En lugar de derivar directamente de ` QSGNode`, podemos utilizar ` QSGSimpleTextureNode `, que nos proporciona parte de la funcionalidad preimplementada para mayor comodidad.
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 elemento se invoca en el hilo de renderizado (si lo hay), con el hilo principal (de la interfaz gráfica de usuario) bloqueado. Aquí creamos un nuevo nodo si aún no existe ninguno y lo actualizamos. En este caso, es seguro acceder a los objetos de Qt que residen en el hilo principal, por lo que sync() calculará y copiará los valores que necesite 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 se limita a la secuencia típica 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 mediante la codificación de una pasada de renderizado completa, dirigida a la textura, en el búfer de comandos del grafo de escena de Qt Quick. beforeRendering() es el lugar adecuado para ello, ya que 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());Tras copiar los valores que necesitamos, `sync()` también lleva a cabo cierta inicialización de los recursos gráficos. Se consulta el `MTLDevice` del grafo de escena. Una vez que hay una `MTLTexture` disponible, se crea un ` QSGTexture ` que la envuelve (sin ser su propietario) mediante ` QNativeInterface::QSGOpenGLTexture::fromNative()`. Por último, el ` 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 búferes 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.