LVRS Storyboard Frame

backend/RenderQuality.svx

Path: backend/RenderQuality.svx

Last modified:

RenderQuality

위치: backend/runtime/renderquality.h / backend/runtime/renderquality.cpp

RenderQuality는 LVRS 렌더링 품질, GPU 비용 및 전력/성능 균형 정책을 관리하는 QML 싱글턴입니다.

1. 책임범위

RenderQuality는 다음을 직접 관리합니다.

  • 장면 슈퍼샘플링은 의사결정을 활성화/비활성화합니다
  • MSAA, 프레임-인-플라이트, 부분 업데이트 및 배치 렌더러에 대한 기본 정책
  • 창이 비활성 상태일 때 다운그레이드 정책(전력 절약)을 렌더링합니다
  • PSO (파이프라인 상태 객체) 캐시 애플리케이션 정책
  • 텍스처 압축 후보 선택 및 Mipmap 사용 정책
  • DRS(동적 해상도 스케일링) 컨트롤러
  • 디바이스 계층 프리셋 (낮음/균형/높음)

2. P3 구현 매핑

P3 ID 구현 지점 행동
P3-01 applyGraphicsConfiguration, configureGlobalDefaults QQuickGraphicsConfiguration 자동 파이프라인 캐시와 파일 로드/저축을 적용하고, QSG_RHI_PIPELINE_CACHE_LOAD/SAVE에 대한 전역 기본값을 초기화합니다.
P3-02 resolveTextureSource, QML Image.mipmap 바인딩 동일한 경로에서 압축된 텍스처(ktx2/ktx/dds)를 자동으로 선택하고 레이어/아이콘 mipmap 정책을 통합합니다.
P3-03 applyGraphicsConfiguration 2D 패스 상태 전환 오버헤드를 줄이기 위해 depthBufferFor2D와 디버그/타임스탬프 정책을 비활성화하십시오.
P3-04 sampleFrameTime, frameSwapped 연결 히스테리시스 기반 로직을 사용하여 DRS의 스케일 업/다운을 제어합니다
P3-05 detectDeviceTierForSystem, applyDeviceTierPreset CPU 스레드 수에서 티어를 추정하고 저/밸런스/고 프리셋을 적용하십시오.

3. 코어 속성 계약

3.1 GPU 캐시/파이프라인

  • psoCacheEnabled
  • psoCacheLoadEnabled
  • psoCacheSaveEnabled
  • psoCacheFile
  • depthBufferFor2D

applyWindow()가 호출될 때, 이러한 값은 즉시 QQuickWindow::graphicsConfiguration()에 반영됩니다.

3.2 텍스처 정책

  • mipmapEnabled
  • textureCompressionEnabled
  • compressedTextureExtensions(기본값: ktx2, ktx, dds)
  • resolveTextureSource(source)

resolveTextureSource()는 압축된 확장 파일이 로컬 파일/qrc 경로에 실제로 존재할 때만 후보자를 다시 씁니다.

3.3 DRS

  • dynamicResolutionEnabled
  • dynamicResolutionScale
  • dynamicResolutionMinScale
  • dynamicResolutionMaxScale
  • dynamicResolutionStep
  • dynamicResolutionTargetFrameMs
  • dynamicResolutionHysteresisMs

effectiveSupersampleScaleValue는 DRS가 활성화될 때 동적으로 변하며, QML 바인딩 업데이트를 위해 NOTIFY 신호를 사용합니다.

3.4 장치 프리셋

  • detectedDeviceTier(상수)
  • activeDeviceTier
  • applyDeviceTierPreset(tier = -1)

tier=-1인 경우 자동 감지 계층이 적용됩니다.

4. DRS 행동 규칙

  1. frameSwapped에서 샘플 프레임 간격(ms)
  2. target + hysteresis를 초과하는 프레임이 누적되면 축소하십시오.
  3. target - hysteresis 이하의 프레임이 충분히 누적되면, 확대하십시오.
  4. 스케일 변경은 [dynamicResolutionMinScale, dynamicResolutionMaxScale] 내에서만 가능합니다.
  5. 창이 전원 절약 모드일 때 DRS 샘플링을 중지하십시오.

5. 사전 설정된 표준

사전 설정 의도 기본 요약
LowTier 저사단 안정성을 우선시하십시오. MSAA=2, framesInFlight=1, DRS on, mipmap off
BalancedTier 기본 균형 모드 MSAA=4, framesInFlight=2, DRS on, mipmap on
HighTier 시각적 품질을 우선시하십시오. MSAA=8, framesInFlight=3, DRS off, mipmap on

6. QML 적용 포인트

  • qml/ApplicationWindow.qml
  • qml/Window.qml
  • 핵심 아이콘 구성 요소 ( IconButton , IconMenuButton , LabelMenuButton , MenuItem , HierarchyItem , ListToolbar )

적용된 동작:

  • 레이어 바인딩: layer.mipmap: RenderQuality.mipmapEnabled
  • 이미지 출처: source: RenderQuality.resolveTextureSource(...)
  • 시작 프리셋 적용: RenderQuality.applyDeviceTierPreset(...)

7. 확인 명령

  • cmake --build build-codex --target LVRSTests_render_quality
  • ./build-codex/tests/LVRSTests_render_quality -txt

P3 회귀 검증 테스트: render_quality_gpu_policy_pso_texture_and_drs_contract()

8. 관련 문서

  • docs/components/app/ApplicationWindow.md
  • docs/architecture/rendering-backend.md
  • docs/quality-automation-p4.md