렌더링 백엔드 정책

이 문서는 LVRS가 플랫폼 전체에서 그래픽 백엔드 정책을 선택, 검증 및 보고하는 방법을 정의합니다.

부트스트랩 항목

기본 부트스트랩 경로:

• lvrs::preApplicationBootstrap(options)
• lvrs::postApplicationBootstrap(app, options)

위치: backend/runtime/appbootstrap.h, backend/runtime/appbootstrap.cpp

preApplicationBootstrap는 그래픽 백엔드 부트스트랩 및 선택적 렌더링 품질 전역 기본값을 담당합니다.

플랫폼 백엔드 매트릭스

• macOS / iOS: Metal가 필요합니다.
• Windows / Android: Vulkan가 필요합니다.
• Linux: Qt 기본 백엔드 선택입니다.
• 다른 대상: 하드 오버라이드 없음; Qt 기본 백엔드 선택이 사용됩니다.

필요한 백엔드가 사용 불가능한 경우, 부트스트랩는 오류 메시지와 함께 ok == false를 반환합니다.

빌드 시간 시행

CMake 옵션: LVRS_ENFORCE_VULKAN(기본값 ON)

활성화되면 대상 플랫폼에 대해 고정 백엔드 Qt 기능을 확인할 수 없는 경우 구성이 조기에 실패합니다. 이렇게 하면 오류가 런타임에서 구성/구축 단계로 이동됩니다.

런타임 진단

백엔드 부트스트랩가 성공하면, 시작 로그에는 가능한 경우 백엔드 아이덴티티와 로더 세부 정보가 포함됩니다.

예:

• LVRS graphics backend: metal
• LVRS graphics backend: vulkan, loader = ...

RenderQuality와의 상호 작용

configureRenderQualityDefaults가 활성화된 경우, RenderQuality::configureGlobalDefaults()가 앱 구축 전에 적용됩니다. 이렇게 하면 text/ MSAA 기본값이 백엔드 정책에 맞게 정렬됩니다. 전역 기본값은 또한 GPU 파이프라인 캐시 환경 힌트(QSG_RHI_PIPELINE_CACHE_LOAD/SAVE)를 시드합니다. 창당 PSO 캐시 파일 바인딩 및 디바이스 계층 프리셋이 RenderQuality.applyWindow(...) / RenderQuality.applyDeviceTierPreset(...)에 적용됩니다.

실패 처리 지침

부트스트랩가 실패하는 경우:

1. 즉시 시동을 중지하고,
2. 부트스트랩 오류 메시지를 인쇄합니다.
3. 플랫폼 SDK/런타임(Metal/Vulkan) 및 Qt 기능 지원을 확인합니다.
4. 명시적 진단을 활성화하여 다시 실행합니다.

관련 파일

• backend/runtime/vulkanbootstrap.h
• backend/runtime/vulkanbootstrap.cpp
• backend/runtime/renderquality.h
• backend/runtime/renderquality.cpp

실용적인 목표 매트릭스 검증

배송하기 전에 대상 제품군당 하나의 실제 장치/시뮬레이터를 검증하십시오.

• macOS: Metal 백엔드 선택 및 안정적인 시작을 확인합니다.
• iOS: Metal 경로 및 텍스트 렌더링 품질을 확인합니다.
• Windows : Vulkan 로더 검색 및 시작을 확인하십시오.
• Linux: Qt 기본 백엔드 선택으로 안정적인 시작을 확인합니다.
• Android : Vulkan -능동 장치 동작 및 대체 경로 정책을 확인하십시오.

배포 문제 해결

부트스트랩 단계에서 시작이 실패하는 경우:

• 먼저 부트스트랩 오류 문자열을 검사하십시오.
• Qt 빌드에 필수 렌더링 백엔드 기능이 포함되어 있는지 확인하세요.
• Vulkan 대상에 대한 런타임 로더/드라이버 존재를 확인하십시오 ( Windows / Android ),
• 환경 재정의가 호환되지 않는 그래픽 API를 강제하지 않는지 확인하세요.

운영 권장 사항

비프로덕션 빌드 및 CI 스모크 실행에서 백엔드 부트스트랩 진단을 활성화된 상태로 유지합니다. 이는 앱 수준 UI 로직이 포함되기 전에 환경 회귀를 포착합니다.