Docs

Docs

Display and Rendering

The virtual screen SwingBridge reports, HiDPI rendering, and the back-buffer format.

A hosted Swing application still asks AWT how big the screen is and what pixel format to use, and there is no physical screen to answer with. SwingBridge answers on its behalf. Three system properties control those answers; the defaults are chosen so that no deployment has to set any of them.

Property Default What it decides

swingbridge.screenSize

per-user

The screen size reported to the Swing application.

swingbridge.hidpi

off

Whether the back buffer is rendered at the browser’s device pixel ratio.

swingbridge.backBufferType

adaptive

The pixel format of each window’s back buffer.

Virtual Screen Size

swingbridge.screenSize decides what the Swing application is told when it reads Toolkit.getScreenSize(), sizes a window to the screen, or centers a dialog with setLocationRelativeTo(null):

  • per-user (the default, also used when the property is unset) — each session sees a screen derived from that user’s own browser.

  • <width>x<height> — one fixed resolution for every session, for example 1920x1080. Each edge must be between 240 and 8192. Use 2560x1440 to reproduce the behavior of releases before per-user screens existed.

  • Anything else is logged as a warning and falls back to 2560x1440.

Source code
terminal
java -Dswingbridge.screenSize=1920x1080 -jar my-app.jar

Two things this property does not do: it never resizes or moves a window — the screen size is information the Swing application may act on — and it does not change rendering resolution.

HiDPI Rendering

swingbridge.hidpi renders the back buffer at the browser’s device pixel ratio, so text is crisp on Retina and 4K displays instead of being upscaled by the browser:

  • off (the default) — one buffer pixel per logical pixel.

  • auto — each session follows its own browser’s ratio, quantized to 0.25 steps and clamped.

  • a decimal, for example 2 or 1.5 — that fixed scale for every session.

Two further properties bound the cost, since heap per window scales with the square of the scale:

Property Default Description

swingbridge.hidpiMaxScale

2.0

Upper bound on the multiplier, between 1.0 and 4.0.

swingbridge.hidpiMaxBufferPixels

8000000

Upper bound on a single window’s back buffer in device pixels. A window over the ceiling renders at a reduced scale rather than being refused.
Source code
terminal
java -Dswingbridge.hidpi=auto -jar my-app.jar

Oversampling is invisible to the Swing application: it keeps its logical coordinate space and a 1x default transform, so layout is identical at every scale, pointer coordinates need no translation, and Toolkit.getScreenResolution() stays 96. Moving the browser to a display with a different pixel ratio is detected and re-rendered at the new ratio.

Images the Swing application creates itself stay at 1x and are upsampled into the oversampled buffer, so an application that blits its own off-screen image may still look soft.

What It Costs

Raising the scale multiplies the pixels in every back buffer. The costs that follow do not all grow at the same rate.

Memory is where it shows. A window’s buffer grows with the square of the scale, so doubling the scale roughly quadruples it. That is the cost to plan for when many sessions share one host. Setting swingbridge.backBufferType=565 halves it, and 16-bit color is less noticeable at a higher scale, because the dithering has more pixels to hide in.

The network sees much less. Frames are compressed as PNG. Large areas of flat color compress nearly as well at a high scale as at a low one, so only the edges of text carry real extra detail. And only a window’s first frame is sent in full — after that SwingBridge sends just the areas that changed, and a small change stays small at any scale.

Encoding costs more CPU, roughly in proportion to the pixels. Because the steady state is small updates, this shows when a window first appears or is resized, not while the user works.

HiDPI is therefore limited by memory rather than by bandwidth. On a slow connection it is the first frame of each window that grows; everything after it costs little more than before. Leave swingbridge.hidpiMaxScale at its default unless you have measured your own application.

Back-Buffer Pixel Format

Each bridged window keeps a back buffer sized to the window. It is the dominant per-window allocation and the source of every frame streamed to the browser. swingbridge.backBufferType selects its format:

  • adaptive (the default) — opaque windows use 24-bit TYPE_INT_RGB; only per-pixel-translucent windows keep 32-bit TYPE_INT_ARGB. Same memory as ARGB, smaller frames, and lossless.

  • argb — 32-bit TYPE_INT_ARGB for every window, the behavior of earlier releases.

  • 565 — 16-bit TYPE_USHORT_565_RGB, halving back-buffer memory at the cost of 16-bit color: banding on gradients and softer text anti-aliasing.

Source code
terminal
java -Dswingbridge.backBufferType=565 -jar my-app.jar

Next Steps