Transparent windows
A transparent window clears to alpha zero, so the desktop shows through wherever the frame draws nothing. On top of that come a system backdrop, the window shadow, a whole window opacity, and control over which parts of the window take the mouse.
Opening one
isolen_app_desc field | Meaning |
|---|---|
transparent | The frame clears to alpha zero and the desktop shows through. Off by default. --transparent sets it. |
backdrop | An isolen_backdrop the system draws behind the frame. Anything but isolen_backdrop_none makes the window transparent too. --backdrop NAME sets it: mica, acrylic or vibrancy, and any other name is none. |
shadow | An isolen_shadow. isolen_shadow_auto, the default, is the system's choice, except that a transparent borderless window has none. isolen_shadow_on and isolen_shadow_off force it. |
It works with every chrome style: native chrome, drawn chrome and no chrome at all. Nothing in the shell paints the ground under the view, so what the view does not cover stays clear. A panel with a translucent fill shows the desktop dimmed through it.
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
// a rounded panel floating over the desktop, clicks outside it reach the
// windows below
struct hud {
bool pinned;
float opacity = 1.0f;
};
static void hud_view(isolen_frame* f, void* user)
{
hud* h = static_cast<hud*>(user);
ui::ctx* u = f->ui;
// nothing paints the ground, so it stays clear and the desktop shows
ui_box(u, ui::col().width(lay_pct(1.0f)).height(lay_pct(1.0f)).centre())
{
ui_box(u, ui::col().width(360.0f).pad(20.0f).gap(12.0f).bg("#181c20c0").round(18.0f)
.border(1.0f, "#ffffff40"))
{
ui::text(u, "now playing", ui::head(u));
if (ui::slider(u, "opacity", &h->opacity, 0.2f, 1.0f, "%.2f")) {
isolen_set_window_opacity(f->app, h->opacity);
}
if (ui::toggle(u, "let every click through", &h->pinned)) {
isolen_set_click_through(f->app, h->pinned);
}
}
}
}
int run_hud(int argc, char** argv)
{
static hud h;
isolen_app_desc d = isolen_app_defaults();
d.title = "hud";
d.width = 640u;
d.height = 480u;
d.chrome = false;
d.transparent = true;
d.shadow = isolen_shadow_off;
isolen_app* a = isolen_open(&d, argc, argv);
if (!a) {
return 1;
}
// the mouse is taken only over what the ui drew
isolen_set_hit_elements(a, true);
isolen_frame f = {};
while (isolen_next_frame(a, &f)) {
hud_view(&f, &h);
}
isolen_close(a);
return 0;
}Backdrops
isolen_backdrop | Windows 11 | macOS |
|---|---|---|
isolen_backdrop_none | No system backdrop. | No effect view. |
isolen_backdrop_mica | Mica. | The window background vibrancy material. |
isolen_backdrop_acrylic | Acrylic. | The HUD window material. |
isolen_backdrop_vibrancy | Acrylic. | The under window background material. |
On Windows a backdrop also switches the frame to dark. Where the system has no backdrop, such as Windows 10, the request fails and the log says the os has no system backdrop. On macOS the effect view is made on the first request and sits under the Metal view.
backdrop was a bool and is now the isolen_backdrop enum. Code that set d.backdrop = true for Mica no longer compiles. Write d.backdrop = isolen_backdrop_mica.Changing it live
| Call | Does |
|---|---|
void isolen_set_transparent(isolen_app* a, bool on) | Lands on the next frame boundary. On Vulkan it builds the swapchain again. A window with a backdrop stays transparent while the backdrop is on. |
bool isolen_transparent(const isolen_app* a) | Whether it is transparent, or will be once a pending change lands. |
void isolen_set_backdrop(isolen_app* a, isolen_backdrop b) | Switches the backdrop, and the transparency with it. |
void isolen_set_shadow(isolen_app* a, isolen_shadow s) | Switches the shadow. |
void isolen_set_window_opacity(isolen_app* a, float alpha) | Fades the whole window, chrome included, from 0 to 1. This needs no transparency. |
Drawing into it
The compositor reads the frame as premultiplied alpha. The kit blends so the target ends up premultiplied, and colours you hand it stay plain rgba. Keep srgb off, the default. A level two pass must write premultiplied colour too.
| Backend | How the alpha reaches the desktop |
|---|---|
| Metal | The layer stops claiming it is opaque over a clear window. |
| CPU on macOS | The IOSurface layers stop claiming they are opaque. |
| CPU on Windows | The DIB copy keeps its alpha, and the window frame extended over the whole client makes the compositor read it as premultiplied. |
| Vulkan | A swapchain with premultiplied composite alpha. When the surface does not offer it, the swapchain stays opaque and the alpha reaches the desktop only if the driver keeps it under the frame. |
gfx_surface_alpha(dev) in isolenui/gfx/gfx.h says whether the surface itself hands alpha to the compositor. gfx_set_transparent and gfx_transparent are the device side of the switch, and gfx_desc::transparent opens a device that way. See a device on its own.
swapchain transparent asked line in the log to see which composite alpha the surface gave.Where the mouse goes
A transparent window still takes every click inside its rectangle by default, even where it drew nothing. Three calls change that.
| Call | Does |
|---|---|
void isolen_set_click_through(isolen_app* a, bool on) | Every click lands on what is below the window. It wins over the two below. |
void isolen_set_hit_elements(isolen_app* a, bool on) | The window takes the mouse only over what the ui drew last frame, the title bar included. |
void isolen_set_hit_test(isolen_app* a, isolen_hit_fn fn, void* user) | The window takes the mouse only where fn returns true. Null goes back to the whole window, or to the ui when hit elements is on. |
isolen_hit_fn is bool (*)(float x, float y, void* user), with x and y in logical units. A window that lets clicks pass gets no mouse events, so the shell reads the system cursor about 30 times a second and flips the window between taking and passing as the cursor crosses the region. The title bar always takes the mouse while chrome is on, except in full screen.
Hit elements asks ui::solid_at(u, x, y): true when last frame drew a surface, a mark or a control under the point. A surface is an element with a fill, a stroke or a look. A mark is text or a rule. Controls count even when they draw nothing there.
#include "isolenui/app/app.h"
// a round dial, the corners of its square window let the mouse through
struct dial {
float cx;
float cy;
float r;
};
static bool on_dial(float x, float y, void* user)
{
const dial* d = static_cast<const dial*>(user);
const float dx = x - d->cx;
const float dy = y - d->cy;
return dx * dx + dy * dy <= d->r * d->r;
}
void round_window(isolen_app* a)
{
static dial d = { 160.0f, 160.0f, 150.0f };
isolen_set_transparent(a, true);
isolen_set_hit_test(a, on_dial, &d);
}
void back_to_normal(isolen_app* a)
{
isolen_set_hit_test(a, nullptr, nullptr);
isolen_set_transparent(a, false);
}Platform limits
- Windows. A transparent window has no shadow, whatever
shadowsays, and the log notes it. - Windows. A transparent window with native chrome takes its borders into the client, so it grows about 8 pixels on each side.
- Windows. Opacity, click through and a hit region all use a layered window. Turning layering on or off throws the surface away, so the next frame paints in full.
- macOS. A transparent window in a full screen Space shows black behind it unless it has a backdrop.
- Both. A hit region follows the cursor at about 30 checks a second rather than per mouse event.
In the log
| Line | When |
|---|---|
app chrome native, backdrop B, transparent T, shadow S, start fullscreen F | At open. |
app transparent on on vulkan | A live switch. It adds the surface keeps no alpha and the dwm frame carries it when the surface is opaque. |
app backdrop B keeps transparent on | Transparency was turned off while a backdrop needs it. |
app mouse taken over what the ui drew | The mouse mode changed. The others are passes through everywhere, taken where the hit test says and taken everywhere. |
app hit region takes the mouse at X Y px, app hit region lets it pass at X Y px | The cursor crossed the region edge. |
window backdrop mica kind 2 result 0x00000000 | Windows, the backdrop the system was asked for. |
The tree also has an isolen_overlay app, a translucent panel over the desktop with switches for each of these. It is a test bench and is not shipped. See window chrome for the frame styles.