RFR: 8375578: Enable translucent window backdrops

[Martin Fox]

On Fri, 23 Jan 2026 07:36:57 GMT, Christopher Schnick <duke at openjdk.org> wrote:

>> This PR enables translucent window backdrops for JavaFX stages on macOS and Windows 11. Since we’re reliant on the operating system for these effects (they typically require real-time blurring of the desktop) I needed to flesh out a fairly complete prototype to sort out the API. I will start a discussion about the API on the mailing list.
>> 
>> There’s a crude manual test for trying out the different backdrop materials.
>> 
>> 	java @build/run.args -Djavafx.enablePreview=true tests/manual/stage/BackdropTest.java
>> 
>> You’ll want to drag the windows around to avoid having them overlap each other since they’re all created in the center of the screen. For windows without title bars you can click anywhere on the background to drag the window except for TRANSPARENT stages on Windows which are a bit tricker to get a hold of; try to click on a text label.
>> 
>> If you create an UNDECORATED stage on Windows the backdrop won’t be translucent initially. This can be corrected by changing the stage’s color scheme. This is an OS bug that I haven’t found a workaround for.
>> 
>> The changes on Windows 11 are minimal since we’re just invoking an OS feature by calling DwmSetWindowAttribute. I did need to make two small changes to the D3D9 Prism code to ensure that the swap chain and back buffer support an alpha channel so JavaFX can composite its content on top of the backdrop. This is the same way the old UNIFIED stage style worked before it became unreliable (see [JDK-8154847](https://bugs.openjdk.org/browse/JDK-8154847)).
>> 
>> On macOS I moved the GlassHostView so it’s now a permanent part of the NSWindow. For some time the host view has been a remnant left over from an older approach to implementing fullscreen. Now it serves as a common parent for the NSVisualEffectView that provides the backdrop and the GlassView3D that contains the JavaFX content. Making it the permanent contentView of the NSWindow simplifies some code.
>> 
>> To validate the API I did prototype this for Windows 10 (thanks @mstr2!). Well, I prototyped this using DirectComposition so it should work on Win10 but I can't test Win10 myself. Using DirectComposition is much more involved so I shelved that implementation for now but it does inform the API. It’s the reason the backdrop needs to be specified before the Java window is shown and the platform window created.
>
> modules/javafx.graphics/src/main/native-glass/win/GlassWindow.cpp line 342:
> 
>> 340:             break;
>> 341:         case WM_DWMCOMPOSITIONCHANGED:
>> 342:             if (m_isUnified || m_hasBackdrop) {
> 
> Should a backdrop automatically set the window margin akin to UNIFIED (and maybe EXTENDED)? In my opinion, this should be left to the stage style for consistency.
> 
> Like if I use the normal stage style with a backdrop, I might not want the full backdrop to be visible like that. Maybe I only want the backdrop the be visible in the title bar.

Good question. I had to do this to make the backdrops work. I tweaked Prism to ensure the swap chain supported an alpha channel but apparently that's not enough. To get D3D9 to alpha composite onto the backdrop we have to make this call to invoke the old Aero glass logic (the effect UNIFIED was originally designed for). I'll keep looking into this but for now when there's a backdrop DECORATED and UNIFIED look the same.

I'll also take a look at DWMSBT_AUTO which states that it only draws the backdrop in the title bar but doesn't give us any control over the effect.

Most Microsoft apps that employ these backdrops extend the backdrop into the title bar though there's a lot of subtle variation (and then there's Weather which looks like it was written by a different company).

-------------

PR Review Comment: https://git.openjdk.org/jfx/pull/2048#discussion_r2726138789