Screen consumer enhancements: flexible aspect ratio, mipmaps, multi-display spanning

[gmeisel01]

Screen Consumer Enhancements

This PR adds several improvements to the screen consumer that have been
requested by the community across multiple open issues, plus a bug fix
for non-standard canvas sizes.

Bug Fix — GL Viewport for Non-Standard Canvas Sizes

When <width> and <height> are configured to a non-standard size
(ultra-wide, LED wall, multi-display span), the GL render target was
initialized to the channel's native format dimensions rather than the
configured window size. Content was rendered at native resolution and
simply stretched to fill the larger window rather than rendered at full
canvas resolution.

Fix: Set the initial glViewport to screen_width_ x screen_height_
— the actual configured window dimensions.

Note: For non-standard canvas sizes the channel <video-mode> must
also reference a custom resolution defined in <video-modes>. Without
this the mixer itself operates at the native format width regardless of
the screen consumer window size. See the updated casparcg.config
reference comments for documentation and a complete working example.

Addresses: #487, #619, #995, #1284

---

New Configuration Options

<aspect-ratio> — Extended to accept:

• Named ratios: 4:3, 16:9
• Custom ratio strings: 3840:1080, 5760:1080
• Decimal values: 3.555
• default or empty — auto-derives from format square dimensions

<always-on-top> — Keeps the output window above all other windows.
Addresses #995.

<borderless> — Removes window chrome for clean fullscreen spanning
across displays without requiring OS-level display spanning solutions.

<x> / <y> / <width> / <height> — Full position and size
control in both windowed and fullscreen modes, including multi-display
spanning via explicit position + size. Addresses #487, #1284.

<brightness-boost> — Per-consumer linear brightness multiplier
(default 1.0).

<saturation-boost> — Per-consumer linear saturation multiplier
(default 1.0).

<enable-mipmaps> — Enables mipmapping for improved quality when
content is displayed significantly smaller than its native resolution.

<gpu-texture> — GPU texture strategy for reduced CPU-GPU transfer
overhead on supported hardware.

---

Updated casparcg.config Reference

The <screen> and <video-modes> sections in the reference config have
been updated to document:

• All new screen consumer options
• Custom video mode requirement for non-standard canvas sizes
• Cadence calculation (48000 / fps) with examples
• Complete channel + consumer configuration example for ultra-wide output

---

Testing

Tested on:

• Windows 11, NVIDIA Quadro P6000
• Standard 1080p60 single display
• Ultra-wide 8520x1080 spanning configuration (screen consumer GL viewport fix)
• Windowed and fullscreen borderless modes
• Multi-display spanning via explicit x/y/width/height

[dimitry-ishenko]

@gmeisel01 how are the brightness and saturation boost different from the same mixer commands?

https://github.com/CasparCG/help/wiki/AMCP-Protocol#mixer-commands

[gmeisel01]

When I first envisioned this feature, the intent was to provide independent calibration control per screen consumer — as opposed to the mixer which operates at the channel level affecting all destinations equally. In a scenario with multiple screen consumers on separate outputs that distinction is meaningful.

Upon further reflection however, the correct approach to driving large LED walls across multiple GPU outputs — whether through NVIDIA Mosaic or Windows extended desktop — is to present them as a single unified pixel space to avoid any tearing at output boundaries. That means a single screen consumer with a single shader, which makes the per-consumer argument moot.

With that in mind you're right — brightness and saturation duplicate what the mixer is already providing. They were removed in the latest commit.