iisacc logo

LVRS Document Viewer

backend/RenderQuality.svx

Path: backend/RenderQuality.svx

Last modified:

RenderQuality

Location: backend/runtime/renderquality.h / backend/runtime/renderquality.cpp

RenderQuality is a QML singleton that governs LVRS render quality, GPU cost, and power/performance balance policies.

1. Responsibility Scope

RenderQuality directly manages the following:

  • Scene supersampling enable/disable decisions
  • Default policies for MSAA, frames-in-flight, partial update, and batch renderer
  • Render downgrade policy (power-save) when the window is inactive
  • PSO (pipeline state object) cache application policy
  • Texture compression candidate selection and mipmap usage policy
  • DRS (dynamic resolution scaling) controller
  • Device-tier presets (low/balanced/high)

2. P3 Implementation Mapping

P3 ID Implementation Point Behavior
P3-01 applyGraphicsConfiguration, configureGlobalDefaults Apply QQuickGraphicsConfiguration automatic pipeline cache plus load/save files, and initialize global defaults for QSG_RHI_PIPELINE_CACHE_LOAD/SAVE
P3-02 resolveTextureSource, QML Image.mipmap binding Auto-select compressed textures (ktx2/ktx/dds) on the same path and unify layer/icon mipmap policy
P3-03 applyGraphicsConfiguration Reduce 2D pass state-switch overhead by disabling depthBufferFor2D and debug/timestamp policies
P3-04 sampleFrameTime, frameSwapped hookup Control DRS scale up/down with hysteresis-based logic
P3-05 detectDeviceTierForSystem, applyDeviceTierPreset Estimate tier from CPU thread count and apply low/balanced/high presets

3. Core Property Contract

3.1 GPU Cache/Pipeline

  • psoCacheEnabled
  • psoCacheLoadEnabled
  • psoCacheSaveEnabled
  • psoCacheFile
  • depthBufferFor2D

When applyWindow() is called, these values are immediately reflected in QQuickWindow::graphicsConfiguration().

3.2 Texture Policy

  • mipmapEnabled
  • textureCompressionEnabled
  • compressedTextureExtensions (default: ktx2, ktx, dds)
  • resolveTextureSource(source)

resolveTextureSource() only rewrites candidates when a compressed extension file actually exists on the local file/qrc path.

3.3 DRS

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

effectiveSupersampleScaleValue changes dynamically when DRS is enabled, and uses a NOTIFY signal for QML binding updates.

3.4 Device Presets

  • detectedDeviceTier (constant)
  • activeDeviceTier
  • applyDeviceTierPreset(tier = -1)

If tier=-1, the auto-detected tier is applied.

4. DRS Behavior Rules

  1. Sample frame interval (ms) at frameSwapped.
  2. If frames above target + hysteresis accumulate, scale down.
  3. If frames below target - hysteresis accumulate sufficiently, scale up.
  4. Scale changes only within [dynamicResolutionMinScale, dynamicResolutionMaxScale].
  5. Stop DRS sampling when the window is in power-save mode.

5. Preset Standards

Preset Intent Default Summary
LowTier Prioritize low-end stability MSAA=2, framesInFlight=1, DRS on, mipmap off
BalancedTier Default balanced mode MSAA=4, framesInFlight=2, DRS on, mipmap on
HighTier Prioritize visual quality MSAA=8, framesInFlight=3, DRS off, mipmap on

6. QML Application Points

  • qml/ApplicationWindow.qml
  • qml/Window.qml
  • Core icon components (IconButton, IconMenuButton, LabelMenuButton, MenuItem, HierarchyItem, ListToolbar)

Applied behavior:

  • Layer binding: layer.mipmap: RenderQuality.mipmapEnabled
  • Image source: source: RenderQuality.resolveTextureSource(...)
  • Startup preset apply: RenderQuality.applyDeviceTierPreset(...)

7. Verification Commands

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

P3 regression verification test: render_quality_gpu_policy_pso_texture_and_drs_contract()

8. Related Documents

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