En esta página

Qt Quick 3D - Ejemplo sencillo de RuntimeLoader

Muestra cómo cargar un recurso 3D en tiempo de ejecución y consultar sus objetos de escena.

Panel lateral en el que se enumeran los materiales, las cámaras y las luces junto a una escena en 3D

Este ejemplo muestra cómo utilizar RuntimeLoader para cargar un recurso 3D en tiempo de ejecución y cómo utilizar las funciones de query para detectar los materiales, las cámaras y las luces que contiene la escena cargada.

Carga del recurso

El elemento « RuntimeLoader » carga un recurso glTF 2.0 y crea los objetos 3D correspondientes de « Qt Quick » como sus elementos secundarios. La propiedad « source » apunta al archivo del recurso:

RuntimeLoader {
    id: loader
    source: "torus_and_cone.glb"

    onStatusChanged: {
        if (status !== RuntimeLoader.Success)
            return
        root.sceneMaterials = loader.queryAll(RuntimeLoader.Materials)
        root.sceneCameras = loader.queryAll(RuntimeLoader.Cameras)
        root.sceneLights = loader.queryAll(RuntimeLoader.Lights)
        if (root.sceneCameras.length > 0)
            view3d.camera = root.sceneCameras[0]
        if (root.sceneMaterials.length > 0)
            root.selectedMaterial = root.sceneMaterials[0]
    }
}

Una vez que el elemento « status » cambia a « RuntimeLoader.Success », la escena está lista y se pueden invocar las funciones de consulta.

Consulta de objetos de la escena

Tras una carga correcta, queryAll() devuelve una lista de todos los objetos de la escena que coinciden con un QueryFilter determinado. El ejemplo recupera materiales, cámaras y luces de una sola vez:

root.sceneMaterials = loader.queryAll(RuntimeLoader.Materials)
root.sceneCameras = loader.queryAll(RuntimeLoader.Cameras)
root.sceneLights = loader.queryAll(RuntimeLoader.Lights)

Las listas devueltas son matrices de JavaScript sin formato que contienen referencias a QQuick3DObject. Se pueden asignar directamente a un ListView model o utilizarse para establecer propiedades activas de la escena, como View3D.camera.

Interacción con los objetos de la escena

Materiales

Cada entrada de la lista de materiales puede seleccionarse para aplicarle una de las muestras de color. La función auxiliar convierte el objeto devuelto al tipo de material correcto antes de escribir en la propiedad de color:

function applyColorToSelected(color) {
    if (!root.selectedMaterial)
        return
    if (root.selectedMaterial instanceof PrincipledMaterial)
        (root.selectedMaterial as PrincipledMaterial).baseColor = color
    else if (root.selectedMaterial instanceof SpecularGlossyMaterial)
        (root.selectedMaterial as SpecularGlossyMaterial).albedoColor = color
}
Cámaras

Al hacer clic en una entrada de cámara en el panel lateral, esta se asigna a View3D.camera, lo que cambia inmediatamente el punto de vista activo.

Luces

Cada luz del panel lateral cuenta con un conmutador que establece la propiedad « visible » de la luz, activándola o desactivándola sin eliminarla de la escena:

Switch {
    checked: modelData.visible
    onToggled: modelData.visible = checked
}

Proyecto de ejemplo en code.qt.io

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