En esta página

Qt Quick 3D - Ejemplo de RuntimeLoader

Muestra cómo se pueden cargar recursos en tiempo de ejecución.

Varios modelos de coches con controles de instanciación y de la barra de herramientas

Este ejemplo muestra cómo implementar un visor de recursos sencillo utilizando el RuntimeLoader.

Consulta la documentación del ejemplo introductorio para obtener una explicación sobre cómo configurar una escena básica. Una vez configurada la escena, podemos añadir el elemento « RuntimeLoader »:

RuntimeLoader {
    id: importNode
    source: windowRoot.importUrl
    instancing: instancingButton.checked ? instancing : null
    onBoundsChanged: helper.updateBounds(bounds)
}

La carga de un recurso se realiza configurando la propiedad « source » del « RuntimeLoader ». En este ejemplo, la propiedad « source » está vinculada a la variable « importUrl », cuyo valor cambiará cuando el usuario seleccione un archivo en el cuadro de diálogo de archivos.

Suponiendo que el recurso se pueda cargar, el contenido se creará como elementos secundarios del RuntimeLoader importNode . Ten en cuenta que el RuntimeLoader es de tipo Node y, dado que también es el nodo raíz del recurso cargado, cualquier transformación aplicada al importNode también afectará a sus elementos secundarios.

Gestión de errores

Si un recurso no se carga, la propiedad ` status ` del ` RuntimeLoader` se establecerá en ` Error`. A continuación, se puede consultar el ` errorString ` del ` RuntimeLoader` para obtener una descripción más detallada del error.

En este ejemplo mostraremos el mensaje de error en un cuadro de mensaje rojo en el centro de la pantalla, así:

Rectangle {
    id: messageBox
    visible: importNode.status !== RuntimeLoader.Success
    color: "red"
    width: parent.width * 0.8
    height: parent.height * 0.8
    anchors.centerIn: parent
    radius: Math.min(width, height) / 10
    opacity: 0.6
    Text {
        anchors.fill: parent
        font.pixelSize: 36
        text: "Status: " + importNode.errorString + "\nPress \"Import...\" to import a model"
        color: "white"
        wrapMode: Text.Wrap
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
    }
}
Mover la cámara

Para poder cambiar la posición de la cámara, utilizamos el WasdController del módulo Helpers y lo vinculamos a nuestra cámara, de esta forma:

OrbitCameraController {
    id: orbitController
    origin: orbitCameraNode
    camera: orbitCamera
    enabled: helper.orbitControllerEnabled
}
WasdController {
    id: wasdController
    controlledObject: wasdCamera
    enabled: !helper.orbitControllerEnabled
}

Además de ` WasdController`, el ejemplo utiliza un ` WheelHandler ` y un ` PointerHandler ` para escalar y rotar el modelo.

Instanciación

El elemento RuntimeLoader también se puede utilizar en combinación con la instanciación, tal y como se muestra aquí:

RandomInstancing {
    id: instancing
    instanceCount: 30
    position: InstanceRange {
        property alias boundsDiameter: helper.boundsDiameter
        from: Qt.vector3d(-3*boundsDiameter, -3*boundsDiameter, -3*boundsDiameter);
        to: Qt.vector3d(3*boundsDiameter, 3*boundsDiameter, 3*boundsDiameter)
    }
    color: InstanceRange { from: "black"; to: "white" }
}

RuntimeLoader no hereda de Model, pero cuenta con su propia propiedad instancing, que nos permite instanciar un activo importado complejo como si se tratara de un modelo sencillo. En este caso, utilizamos el componente RandomInstancing del módulo Helpers para colocar elementos de forma aleatoria dentro de un área fija y con un color aleatorio.

Modificaciones de materiales

A veces, al cargar un recurso, es posible que no se vea tal y como se esperaba. La propiedad ` materialOverride ` modificará la forma en que se renderiza cada material de la escena para mostrar su contribución específica al renderizado global. Esto puede resultar útil para determinar qué es exactamente lo que no está correcto en el recurso, de modo que se pueda ajustar el recurso original si es necesario.

Modelo 3D renderizado con la sustitución del material del mapa de normales, que muestra los detalles de la superficie

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.