RenderHDREnabled - ApertureViewer/Aperture-Viewer GitHub Wiki

• Setting Name: RenderHDREnabled
• Controlled By: This setting is typically controlled indirectly via the master setting RenderDisableVintageMode. When RenderDisableVintageMode is true (default), RenderHDREnabled is set to true. When RenderDisableVintageMode is false, RenderHDREnabled is set to false.
• Assumed XML Definition (if directly controlled):

    <key>RenderHDREnabled</key>
    <map>
      <key>Comment</key>
      <string>Enables High Dynamic Range (HDR) rendering pipeline using floating-point buffers and advanced post-processing.</string>
      <key>Persist</key>
      <integer>1</integer> <!-- Likely persistent if controlled directly -->
      <key>Type</key>
      <string>Boolean</string>
      <key>Value</key>
      <integer>1</integer> <!-- Default Value (true) when modern pipeline is active -->
    </map>

• Data Type: Boolean (Stored as integer 0/1, used as bool in C++)
• Default Value: true (when RenderDisableVintageMode is true).

RenderHDREnabled acts as the master switch for the High Dynamic Range (HDR) rendering pipeline. Its primary function is to determine whether the viewer utilizes rendering buffers capable of storing a much wider range of brightness values than traditional Low Dynamic Range (LDR) formats.

Enabling HDR (true) is fundamental for:

• Wider Brightness Range: Allows the renderer to internally handle extremely bright lights (like the sun, intense glows) and deep shadows simultaneously without immediately clipping to pure white or pure black.
• Floating-Point Buffers: Typically causes main render targets (screen buffer, deferred G-Buffer components, reflection probes) to be allocated using higher-precision floating-point formats (e.g., GL_RGBA16F, GL_R11F_G11F_B10F).
• Advanced Post-Processing: Enables the necessary conditions for sophisticated post-processing effects that rely on HDR data, including:
  • Tonemapping: Intelligently compressing the wide HDR brightness range into the displayable LDR range of a monitor, often providing more contrast and a "cinematic" look.
  • Auto-Exposure (Eye Adaptation): Dynamically adjusting the overall scene brightness based on calculated scene luminance.
  • Realistic Bloom: Generating more physically plausible light bleed/glow around very bright objects.
• PBR Accuracy: Essential for correctly rendering the intensity and appearance of Physically Based Rendering (PBR) materials, especially emissive ones.

Disabling HDR (false) reverts the viewer to a Low Dynamic Range (LDR) or "Vintage" rendering mode with significant limitations.

• File: llcommon/llviewercontrol.cpp
  • Function: handleDisableVintageMode(const LLSD& newvalue)
    • Logic: This function, triggered by changes to RenderDisableVintageMode, directly sets the value of RenderHDREnabled (and RenderEnableEmissiveBuffer). gSavedSettings.setBOOL("RenderHDREnabled", newvalue.asBoolean());
• File: llcommon/pipeline.cpp
  • Function: LLPipeline::allocateScreenBufferInternal(...)
    • Logic: Uses a cached control (has_hdr) to check this setting's value. If true (and GL version is sufficient), it selects an HDR format (e.g., GL_RGBA16F) for the main screen render targets (mRT->screen, potentially mRT->deferredLight). If false, it uses a lower-precision LDR format (e.g., GL_RGBA).

    static LLCachedControl<bool> has_hdr(gSavedSettings, "RenderHDREnabled", true);
    bool hdr = gGLManager.mGLVersion > 4.05f && has_hdr();
    // ...
    GLuint screenFormat = hdr ? GL_RGBA16F : GL_RGBA;
    if (!mRT->screen.allocate(resX, resY, GL_RGBA16F)) return false; // Note: Code seems to always request RGBA16F here now, but concept applies
    // ...
    if (!mRT->deferredLight.allocate(resX, resY, screenFormat)) return false;

  • Function: LLPipeline::addDeferredAttachments(...)
    • Logic: Checks RenderHDREnabled. If true, uses HDR formats (GL_RGBA16F, GL_RGB16F) for the Normal and Emissive G-Buffer attachments. If false, uses LDR formats (GL_RGB10_A2, GL_RGB).

    static LLCachedControl<bool> has_hdr(gSavedSettings, "RenderHDREnabled", true);
    bool hdr = has_hdr() && gGLManager.mGLVersion > 4.05f;
    // ... uses hdr to select format ...

  • Function: LLPipeline::renderFinalize()
    • Logic: Checks the HDR state (if (hdr)). If true, it executes the full post-processing chain involving luminance calculation (generateLuminance), exposure calculation (generateExposure), and tonemapping (tonemap). If false, these steps are skipped, and only the simpler gammaCorrect step (using potentially gLegacyPostGammaCorrectProgram) is relied upon later for basic LDR display correction.

    static LLCachedControl<bool> has_hdr(gSavedSettings, "RenderHDREnabled", true);
    bool hdr = gGLManager.mGLVersion > 4.05f && has_hdr();
    
    if (hdr) // Only run these steps if HDR is enabled
    {
        copyScreenSpaceReflections(&mRT->screen, &mSceneMap);
        generateLuminance(&mRT->screen, &mLuminanceMap);
        generateExposure(&mLuminanceMap, &mExposureMap);
        tonemap(&mRT->screen, &mPostMap);
        applyCAS(&mPostMap, &mRT->screen);
    }
    // ... later steps like gammaCorrect might use different shaders based on HDR state implicitly or explicitly

• File: llcommon/llreflectionmapmanager.cpp
  • Function: LLReflectionMapManager::update() / initReflectionMaps()
    • Logic: Checks RenderHDREnabled. If true, allocates reflection probe render targets and the main texture array using HDR formats (e.g., GL_R11F_G11F_B10F). If false, uses LDR formats (e.g., GL_RGB8).

• Enabling HDR (true):

  • Memory: Significantly increases GPU memory usage due to higher-precision floating-point formats for multiple large render targets (Screen, G-Buffer, Probes). Can be a bottleneck on GPUs with limited VRAM.
  • GPU Load: Increases GPU processing load due to:
    • Higher bandwidth requirements for reading/writing HDR buffers.
    • Execution of the more complex post-processing chain (luminance, exposure, tonemapping, potentially CAS).
  • FPS Impact: Can cause a noticeable FPS decrease, especially on lower-end or VRAM-constrained hardware. On high-end hardware, the impact might be small to moderate.

• Disabling HDR (false):

  • Memory: Significantly reduces GPU memory usage by using standard LDR buffer formats.
  • GPU Load: Reduces GPU load by using lower-bandwidth LDR buffers and skipping the complex HDR post-processing chain (likely falling back to simpler gamma correction).
  • FPS Impact: Can provide a significant FPS boost on systems struggling with HDR enabled, particularly older or lower-spec hardware.

Conclusion: Enabling HDR has a definite performance cost (memory and GPU cycles), primarily due to buffer formats and the advanced post-processing it enables. Disabling it is a major performance optimization at the cost of visual fidelity.

• Enabled (true):

  • Lighting: Much more realistic handling of bright lights and deep shadows. Prevents harsh clipping of bright areas (e.g., sun reflections, intense lights preserve detail instead of becoming flat white). Allows seeing details in shadows even with bright areas present.
  • Post-Processing: Enables visually rich effects like bloom around bright lights, nuanced tonemapping for contrast and style, and auto-exposure that smoothly adapts perceived brightness.
  • Materials: PBR materials, especially those with high emissive values or strong specular highlights, render much more accurately and intensely.
  • Overall: Produces a more dynamic, deeper, and often more visually appealing "cinematic" or realistic image.

• Disabled (false - Vintage Mode):

  • Lighting: Limited dynamic range. Bright areas quickly clip to pure white, losing detail. Dark areas clip to pure black, losing detail (crushed blacks). Scenes can appear washed out or have overly harsh contrast depending on the light levels.
  • Post-Processing: Lacks advanced tonemapping (may use simple gamma correction), resulting in a flatter look. Auto-exposure is disabled or ineffective. Bloom effect is significantly reduced or absent.
  • Materials: PBR materials can look flat or incorrect, especially emissive and highly reflective ones. Glow effects are largely disabled or inaccurate.
  • Overall: Produces a less dynamic, often flatter or harsher image reminiscent of older rendering techniques ("Vintage" look).

• Defined Default: true (implicitly set by RenderDisableVintageMode being true).

This is the correct and intended default for the modern Second Life viewer. The entire PBR material system and advanced lighting/post-processing pipeline are built around the assumption that HDR rendering is enabled. Disabling it should be considered a fallback or compatibility mode.

• For All Modern/Capable Hardware: true (Enabled). This unlocks the intended visual fidelity of the viewer and is necessary for PBR materials and modern lighting/post-processing effects to function correctly. High-end hardware should easily handle the performance cost.
• For Troubleshooting/Compatibility/Very Low-End Hardware: false (Disabled). Only recommended if experiencing severe performance issues directly attributable to HDR (after ruling out other bottlenecks) or on extremely old hardware that lacks proper support for the required buffer formats or shader instructions. Disabling it significantly degrades visual quality.

Objective: To observe the visual and performance differences between HDR and LDR rendering.

Prerequisites: Access to toggle the RenderDisableVintageMode setting (which controls RenderHDREnabled).

Procedure:

1. Select Test Locations:
   • Find a scene with very high contrast: bright sunlight hitting surfaces adjacent to deep, dark shadows.
   • Find a nighttime scene with intense, bright artificial lights or strong glow effects.
   • Find a scene with detailed PBR materials, including emissive ones if possible.
2. Enable HDR (Default): Ensure RenderDisableVintageMode is true. Observe the test locations.
   • Note the detail visible in both the brightest highlights and the darkest shadows.
   • Observe the intensity and appearance of bloom around light sources.
   • Watch how the scene brightness adapts when moving the camera between bright and dark areas (auto-exposure).
   • Observe the richness/intensity of PBR materials.
   • Note the current FPS.
3. Disable HDR (Enable Vintage Mode): Set RenderDisableVintageMode to false. The viewer might need a shader reload or restart for the full effect. Re-visit the test locations.
   • Expected Observation (Visual): Bright areas will likely clip to flat white much sooner. Dark areas may become uniformly black (crushed). Bloom will be significantly reduced or absent. Auto-exposure adaptation will be gone. PBR materials may look flatter, less intense. Overall contrast might feel harsher or flatter depending on the scene.
   • Expected Observation (Performance): FPS may increase, potentially significantly on lower-end systems.
4. Toggle Back: Return RenderDisableVintageMode to true to restore HDR rendering.

Objective: To verify buffer format changes, post-processing execution path changes, and performance/memory differences.

Prerequisites: Debug build, graphics debugger (RenderDoc, etc.), performance profiling tools (GPUView, vendor tools), ability to toggle RenderDisableVintageMode.

Procedure:

1. Verify Buffer Formats:
   • Enable HDR (RenderDisableVintageMode = true). Capture a frame with the graphics debugger. Inspect the format of key render targets: mRT->screen, mRT->deferredScreen attachments (especially Normal, Emissive if enabled), mRT->deferredLight, mReflectionMapManager.mTexture.
   • Expected Formats: Look for floating-point formats like GL_RGBA16F, GL_RGB16F, GL_R11F_G11F_B10F.
   • Disable HDR (RenderDisableVintageMode = false). Restart/reload shaders if necessary. Capture another frame. Inspect the same buffers.
   • Expected Formats: Look for LDR formats like GL_RGBA8, GL_RGB8, GL_RGB10_A2.
2. Verify Post-Processing Path:
   • Enable HDR. Capture a frame. In the debugger, step through the LLPipeline::renderFinalize function.
   • Expected Execution: The code block if (hdr) should execute, calling generateLuminance, generateExposure, tonemap.
   • Disable HDR. Capture a frame. Step through renderFinalize again.
   • Expected Execution: The if (hdr) block should be skipped. Later calls to gammaCorrect might use different shaders (e.g., gLegacyPostGammaCorrectProgram).
3. Measure Performance/Memory:
   • Enable HDR. Use profiling tools to measure average GPU frame time and GPU VRAM allocation after settling in a complex scene.
   • Disable HDR. Restart/reload if needed. Measure frame time and VRAM allocation in the same scene.
   • Expected Observation: Frame time should generally be lower (FPS higher) and VRAM usage should be significantly lower when HDR is disabled.