Qt Quick 3D - RuntimeLoader 예제
런타임에 애셋을 로드하는 방법을 보여줍니다.
이 예제는 ` 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 instancing 는 Model을 상속받지는 않지만, 자체적인 속성을 가지고 있어 복잡한 임포트된 에셋을 마치 단순한 모델인 것처럼 인스턴싱할 수 있습니다. 이 예제에서는 모듈의 컴포넌트를 사용하여 고정된 영역 내에서 항목을 무작위 위치에 배치하고 무작위 색상을 적용합니다. Helpers RandomInstancing
머티리얼 재정의
때로는 에셋을 불러올 때 예상한 대로 보이지 않을 수 있습니다. ` materialOverride ` 속성은 씬 내 각 머티리얼이 렌더링되는 방식을 변경하여 전체 렌더링에 대한 특정 기여도를 표시합니다. 이는 에셋의 정확히 어떤 부분이 올바른지 파악하는 데 유용하며, 필요한 경우 원본 에셋을 조정할 수 있게 해줍니다.
© 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.
