Qt Quick 3D - 런타임 로더 예시

런타임에 에셋을 로드하는 방법을 보여줍니다.

이 예제에서는 RuntimeLoader 을 사용하여 간단한 에셋 뷰어를 구현하는 방법을 보여줍니다.

기본 장면을 설정하는 방법에 대한 설명은 소개 예제 문서를 참조하세요. 장면이 설정되면 RuntimeLoader 항목을 추가할 수 있습니다:

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

에셋 로드는 RuntimeLoader 의 source 속성을 설정하여 수행합니다. 이 예제에서 source 는 사용자가 파일 다이얼로그에서 파일을 선택하면 변경되는 importUrl 에 바인딩됩니다.

자산을 로드할 수 있다고 가정하면 콘텐츠는 RuntimeLoader importNode 의 하위 항목으로 생성됩니다. RuntimeLoader 은 Node 유형이며 로드된 자산의 루트 노드이기도 하므로 importNode 에 적용된 모든 트랜스폼은 하위 노드에도 영향을 미칩니다.

오류 처리

에셋이 로드되지 않으면 RuntimeLoader 의 status 속성이 Error 로 설정됩니다. 그런 다음 RuntimeLoader 의 errorString 를 쿼리하여 오류에 대한 자세한 설명을 확인할 수 있습니다.

이 예제에서는 다음과 같이 화면 중앙의 빨간색 메시지 상자에 오류 메시지를 표시합니다:

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
    }
}

카메라 이동하기

카메라 위치를 변경할 수 있도록 하기 위해 Helpers 모듈의 WasdController 을 사용하여 다음과 같이 카메라에 바인딩합니다:

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

이 예제에서는 WasdController 외에도 WheelHandler 및 PointerHandler 를 사용하여 모델의 크기를 조정하고 회전합니다.

인스턴싱

RuntimeLoader 항목은 다음과 같이 인스턴싱과 함께 사용할 수도 있습니다:

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 는 Model에서 상속하지는 않지만 자체 instancing 프로퍼티가 있어 복잡한 임포트된 에셋을 단순한 모델처럼 인스턴스화할 수 있습니다. 이 경우 Helpers 모듈의 RandomInstancing 컴포넌트를 사용하여 고정된 영역 내에 임의의 색상으로 항목을 무작위로 배치합니다.

머티리얼 오버라이드

에셋을 로드할 때 예상대로 보이지 않을 수 있습니다. materialOverride 속성을 사용하면 씬의 각 머티리얼이 렌더링되는 방식을 변경하여 전체 렌더링에 특정 기여도를 표시할 수 있습니다. 이는 에셋의 어떤 부분이 올바르지 않은지 정확히 파악하여 필요한 경우 원본 에셋을 조정할 수 있도록 하는 데 유용할 수 있습니다.

예제 프로젝트 @ code.qt.io

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