Q2PRO-X 1.6 Beta 5 by ly — HDR in Q2PRO-X 1.6 Beta 5
The complete guide in HTML. The original DOCX is available from its documentation card.
Q2PRO-X 1.6 Beta 5 by ly
HDR in Q2PRO-X 1.6 Beta 5
Project author: ly
High dynamic range, tone mapping and screenshots
English edition • Q2PRO-X 1.6 Beta 5 by ly • 2026-10-10
Contents
The entries are links: click one to jump to that section.
4. Gamma and compatibility with older configs
HDR changes in beta 2
Fixed the black screen when switching WGL HDR output and hangs while loading or changing a map with AVFX enabled. An ordinary map change preserves the current HDR output mode without an intermediate disable/re-enable cycle. Failed mode changes have a rollback path. AVFX starts after the color mode is applied and the map is ready; SDR and other backends use the same lifecycle. Leaving a map releases its AVFX data, including blood and contact effects.
HDR rendering and HDR output remain separate settings. The display requirements and distinctions below still apply.
What HDR is in Q2PRO-X
HDR in Q2PRO-X is split into two independent parts.
The internal HDR can be used without a true HDR display: it still improves how light and overbright values are handled. The full effect appears when both parts are enabled and the monitor really supports HDR.
| The menu's own recommendation. Use the win32wgl backend for the best HDR effect. win32egl can output HDR too, but on Windows it depends on system HDR being enabled and has a separate white-level calibration. |
|---|
Where the settings live
Menu path: Main menu → Video & Display → HDR Settings
HDR Settings
| Type | Section | Row | Variable or target | What it does |
|---|---|---|---|---|
| Section | Render & output | Render & output | ||
| List | Render & output | HDR rendering | gl_hdr | gl_hdr: HDR rendering mode. Off keeps the current LDR look. Applies immediately. [Off / Auto / Force] |
| List | Render & output | HDR display output | gl_hdr_output | Real HDR signal to the monitor (needs Windows HDR; applies instantly via video restart). Applies immediately. [Off / On] |
| List | Render & output | HDR output mode | gl_hdr_output_mode | Paper-white parity or real above-white highlights. Applies immediately. [Paper-white match / Extended highlights] |
| List | Render & output | Scene format | gl_hdr_scene_format | HDR scene buffer format. Auto picks the best supported. Applies immediately. [Auto / RGBA16F / R11F_G11F_B10F / RGBA8] |
| List | Render & output | Tone mapping | gl_hdr_tonemap | How overbright light is compressed to the display. Applies immediately. [Linear / Reinhard / ACES / Uncharted] |
| Section | Brightness | Brightness | ||
| Slider | Brightness | Peak brightness | gl_hdr_peak_nits | Target display peak brightness. Applies immediately. |
| Slider | Brightness | Paper white | gl_hdr_paper_white_nits | Brightness of ordinary white. Applies immediately. |
| Slider | Brightness | EGL app white | gl_hdr_egl_app_white_max | Win32egl-only app-side white cap for true HDR output. Lower protects lamp/sun/moon detail from EGL overexposure; higher makes EGL HDR brighter. win32wgl ignores it. Applies immediately. |
| Slider | Brightness | Exposure | gl_hdr_exposure | Manual scene brightness compensation in EV stops. Applies immediately. |
| Section | HDR bloom | HDR bloom | ||
| Slider | HDR bloom | HDR bloom threshold | gl_hdr_bloom_threshold_nits | Bloom onset in HDR units. Applies immediately. |
| Slider | HDR bloom | HDR bloom strength | gl_hdr_bloom_strength | HDR-aware bloom strength. Applies immediately. |
| Section | Peak scales | Peak scales | ||
| Slider | Peak scales | Emissive peak scale | gl_hdr_emissive_peak_scale | HDR peak of map / spawn emissive lights. Applies immediately. |
| Slider | Peak scales | Celestial peak scale | gl_hdr_celestial_peak_scale | Sun/moon disk peak + celestial bloom. Applies immediately. |
| Slider | Peak scales | FX peak scale | gl_hdr_fx_peak_scale | HDR peak of lightning sky flash + AVFX lightning bloom. Applies immediately. |
| Section | Service | Service | ||
| List | Service | HDR debug view | gl_hdr_debug | HDR diagnostic overlay. Applies immediately. [Off / False-color / Histogram / Clip mask] |
| Navigation | Service | HDR info... | gl_hdr_info | Print HDR capability / scene-format probe to the console. |
1. Quick setup
1. Enable HDR for your monitor in the Windows settings.
2. In Q2PRO-X, select the win32wgl backend if you want the maximum effect and your driver is stable with WGL.
3. Load a map. Checking HDR output is more reliable after a map has loaded: part of the output path only becomes evident with real rendering.
4. Open Main menu → Video & Display → HDR Settings.
5. Set HDR rendering to Auto, HDR display output to on, and the output mode to extended highlights.
6. Set Paper white for a comfortable ordinary white: usually 160–250 nits.
7. Set Peak brightness for your monitor: 1000, 1300 or 1600 nits, for example.
8. Run gl_hdr_info and check that the backend, the scene format and the output path look as expected.
An example for a 1300-nit display:
vid_driver win32wgl
gl_hdr 1
gl_hdr_output 1
gl_hdr_output_mode 1
gl_hdr_paper_white_nits 200
gl_hdr_peak_nits 1300
gl_hdr_tonemap 2
gl_hdr_info
| gl_hdr_output takes effect after a video-mode restart. |
|---|
2. The main parameters
| Variable | Accepted values | Description |
|---|---|---|
| gl_hdr | 0=off / LDR (default) / 1=auto (HDR when supported) / 2=force (developer) | Master switch for the optional HDR / tone-mapping render pipeline. Off keeps the accepted LDR look exactly. Auto enables HDR scene rendering when the backend can actually render to a floating-point scene buffer (probed at startup — see gl_hdr_info). Force is a developer setting that requests HDR even on marginal backends. HDR keeps light in linear high-range until a final tone-map to the display, so the sun, lightning, stars and emissive effects can exceed ordinary white before being compressed instead of clipping flat. |
| gl_hdr_output | 0=SDR tone-mapped (default) / 1=true HDR (live on active native WGL) | True HDR display output (HDR-6B/HDRLIVE-1). 0 = SDR tone-mapped output. 1 = request a real FP16 scRGB presentation surface. On native win32wgl, changing this while a map or demo is active runs one bounded live transaction: retire the old renderer, settle Advanced Color on the captured monitor if needed, recreate once, then verify the first presented backbuffer. A failed gate or proof rolls back to readable SDR; Windows HDR is restored only when this game enabled it. The selected desktop-fullscreen margin policy is preserved across the transition. Startup, disconnected menus and loading stay on the regular surface. The established win32egl/ANGLE path still applies the change through its normal refresh. gl_hdr_info and gl_hdr_transition_info report requested versus actual state and the exact fallback. The app buffer uses linear scRGB units; Windows composition may additionally apply its SDR-reference-white scale. screenshotjxr is presentation-matched and screenshotjxr_raw is app-exact. |
| gl_hdr_output_mode | 0=paper-white parity (default) / 1=extended highlights | True-HDR output mapping mode (only acts on a live FP16 surface). 0 = paper-white parity: the picture matches the accepted SDR look anchored at gl_hdr_paper_white_nits (UI white == scene white == paper white; nothing exceeds it). 1 = extended highlights: the final clamp is lifted to peak/paper, so tone-curve values above 1.0 (sun/moon discs, lightning, dialed emissive peaks, exposure) survive as REAL above-paper-white brightness on the HDR display. UI is never boosted in either mode. scRGB mapping per spec: value = nits / 80 in the APP buffer; Windows composition may scale that by the system SDR-reference-white on screen (see gl_hdr_output / gl_hdr_info). |
| gl_hdr_scene_format | 0=auto (default) / 1=RGBA16F / 2=R11F_G11F_B10F (no alpha) / 3=RGBA8 (LDR/debug) | Pixel format for the HDR scene buffer. Auto picks the best format that actually passes a framebuffer-completeness probe on this backend. RGBA16F is the safe default and keeps the alpha channel that the sky / god-ray masking relies on. R11F_G11F_B10F is faster and uses less memory but has NO alpha, so it is only valid once the alpha-marker users are moved. RGBA8 forces the legacy LDR buffer (debug). Unsupported choices fall back to RGBA8 with a reason shown in gl_hdr_info. |
| gl_hdr_tonemap | 0=linear/clamp (debug) / 1=Reinhard / 2=ACES filmic (default) / 3=Uncharted filmic | Tone-mapping curve used to compress HDR scene light to the display. Linear/clamp is a debug passthrough. Reinhard is a simple safe roll-off. ACES filmic is the recommended quality curve. Uncharted is an alternative filmic curve. |
| gl_hdr_peak_nits | 100..2000 nits (default 1000) | Target peak display brightness in nits that the tone-mapper aims for. Higher values let bright sources stay brighter before rolling off. On an SDR display this acts as the upper anchor of the tone curve rather than a literal panel brightness. |
| gl_hdr_paper_white_nits | 100..400 nits (default 200) | Brightness assigned to ordinary white world / UI surfaces inside the HDR scene. Raising it lifts mid-tones; lowering it gives more tonal headroom to very bright sources before they clip. |
| gl_hdr_egl_app_white_max | 0.25..8.0 (default 1.1; recommended 1.1 for win32egl HDR) | win32egl-only true-HDR output limiter for the app-side scRGB white scale. It caps the EGL app buffer before Windows composition applies its HDR SDR-white presentation scale. Lower values protect bright lamp/sun/moon detail from EGL overexposure; higher values make EGL HDR brighter but can blow out highlights. win32wgl ignores this setting. |
| gl_hdr_exposure | -4..+4 EV (default 0) | Manual exposure compensation in EV stops applied to the HDR scene before tone mapping. 0 is neutral; +1 doubles scene brightness, -1 halves it. |
| gl_hdr_bloom_threshold_nits | 0..8 HDR units (default 2.0) | Bloom onset threshold expressed in HDR (nits-derived) scene units. Pixels brighter than this start to bloom. Higher restricts bloom to only the brightest sources. |
| gl_hdr_bloom_strength | 0..3 (default 1.0) | HDR-aware bloom strength multiplier applied on top of the bloom chain in HDR mode. |
| gl_hdr_saturation | 0..2 (default 1.0) | Optional post-tone-map saturation adjustment. 1.0 is neutral; lower desaturates, higher boosts color. |
| gl_hdr_contrast | 0..2 (default 1.0) | Optional post-tone-map contrast adjustment. 1.0 is neutral; higher increases contrast, lower flattens it. |
| gl_hdr_emissive_peak_scale | 0..8 (default 1.0) | HDR-only peak multiplier for emissive MAP and SPAWN light contributions (the static emissive-light channel). 1.0 = neutral; higher makes those sources read brighter before tone mapping. Only effective when gl_hdr is active. (HDR-3b wires map/spawn emissive only; lightning/sparks/projectile peak scaling is deferred to a later phase.) |
| gl_hdr_celestial_peak_scale | 0..8 (default 1.0) | HDR peak multiplier for celestial highlights. Currently scales the sun/moon disk peak and the accepted sun/star/planet bloom contribution. It does NOT scale direct star/planet point color (that experiment produced a diamond-fragment artifact and was reverted; a future attempt needs a non-fragmenting soft-glow approach). Only effective when gl_hdr is active. |
| gl_hdr_fx_peak_scale | 0..8 (default 1.0) | HDR-only peak multiplier for the AVFX LIGHTNING visual family. 1.0 = neutral; higher writes true overbright so lightning blooms past white through the tone-map instead of clipping flat. Only effective when gl_hdr is active. HDR-4b scales only the AVFX-lightning paths explicitly marked for lightning HDR peak: sky flash, force-bloom lightning beam/halo/surface-arc segments, and cloud illumination. Model/powerup shells, item vis-tints, snow glints, plain grapple/BFG beams, weapon sparks, projectile lights and static emissive map lights are NOT scaled by this knob. Future non-lightning FX peak routing is deferred. |
Practical guidance:
3. WGL and EGL
win32wgl is the main recommended path for true HDR. It gives a more direct OpenGL output path on modern drivers and usually preserves bright peaks better without losing detail.
win32egl is useful for performance and compatibility. For HDR output it needs Windows system HDR enabled. Because of differences in the swap chain and the colour space, EGL can need a separate white-level adjustment.
| Variable | Accepted values | Description |
|---|---|---|
| gl_hdr_egl_app_white_max | 0.25..8.0 (default 1.1; recommended 1.1 for win32egl HDR) | win32egl-only true-HDR output limiter for the app-side scRGB white scale. It caps the EGL app buffer before Windows composition applies its HDR SDR-white presentation scale. Lower values protect bright lamp/sun/moon detail from EGL overexposure; higher values make EGL HDR brighter but can blow out highlights. win32wgl ignores this setting. |
If bright sources turn into white blobs on EGL:
1. Leave the peak brightness and the paper white the same as on WGL.
2. Lower the white cap in steps of 0.05: 1.10 → 1.05 → 1.00.
3. If the image became too dull, return to 1.10 or raise the exposure slightly.
4. For a final image, use WGL unless you have a reason to stay on EGL.
4. Gamma and compatibility with older configs
This is a separate topic that is easily confused with HDR.
| Variable | Accepted values | Description |
|---|---|---|
| vid_gamma | default 1 / range 0.3..3 / step 0.05 / r_reload/vid_restart | Compatibility texture gamma used by existing Q2/Q2PRO configs. Default 1.0 = identity; lower values brighten texture mid-tones, higher values darken them. On programmable WGL/EGL it is baked into wall/skin texture uploads and therefore needs r_reload or vid_restart; it never changes the whole final frame. With vid_hwgamma 1, the display backend may instead consume this curve as a hardware gamma ramp. Owned by the unified global video config when global video preferences are enabled. |
| vid_display_gamma | default 1 / range 0.3..3 / step 0.05 / live | Optional live final-composite gamma for programmable WGL/EGL. Default 1.0 is neutral; lower values brighten the complete frame and higher values darken it. This new control is deliberately independent from legacy vid_gamma and never inherits its persisted value. Owned by the unified global video config when global video preferences are enabled. |
If an old config made the image unexpectedly bright or dark, start here rather than with the HDR settings.
5. HDR presets in AVFX
The HDR presets live in the AVFX preset section. They assume the internal HDR renderer is on. The music variants stop the current online-music track and start their own; the ordinary variants change only the visual profile.
Details about the slots and the preset rules are in the AVFX presets guide.
6. Screenshots
An ordinary JPEG screenshot is enough for a comparison. For true HDR use:
screenshotjxr
screenshotjxr_raw
The JXR format is what preserves the extended range. A JPEG may look fine as an illustration, but it is not a check of the HDR data. HDR quality is verified by eye on an HDR display and through gl_hdr_info.
7. Diagnostics
gl_hdr_info prints the backend capabilities, the scene format and the current output path. The command changes nothing.
There is also a separate HDR diagnostic overlay. It is a developer aid, acts only for the current session and is never written to a config:
| Variable | Accepted values | Description |
|---|---|---|
| gl_hdr_debug | 0=off / 1=false-color luminance / 2=histogram / 3=overbright clip mask | HDR diagnostic overlay. Off is normal rendering. False-color shows per-pixel luminance bands. Histogram shows the exposure / luminance distribution. Clip mask highlights pixels that exceed the display range. Developer aid; not archived. |
The clip mask is the most useful mode for a player: it directly shows the pixels that exceed the display range.
8. Common problems
| Symptom | What to check |
|---|---|
| No HDR effect at all | Windows system HDR, HDR output enabled, the backend, and a loaded map |
| The scene looks ordinary | The extended-highlights output mode, the peak brightness and the paper white; try WGL |
| Lamps, the Moon and the Sun turn into blobs on EGL | Lower the EGL white cap |
| The interface or ordinary white is too bright | Lower the paper white |
| Everything is too dark | Raise the paper white first, then the exposure carefully |
| The image changed after loading an old config | Check the gamma, not HDR |