microsoft / microsoft/microsoft-ui-xaml
MicaBackdrop has no effect when the process opts into the system composition engine
- Dominant language
- C++
- Stars
- 8.4k
- Forks
- 942
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 105
Description
### Describe the bug
Setting `Window.SystemBackdrop` to a `Microsoft.UI.Xaml.Media.MicaBackdrop` works as expected by default, but silently does nothing if the process has opted into the system composition engine via `Microsoft.UI.Composition.CompositionEngine.TrySetProcessEngine(CompositionEngineType.System)`.
Instead of a Mica material, the window renders a flat, opaque background (black in dark theme and white in light theme). No exception is thrown, no warning is emitted, and the `SystemBackdrop` property still reports the `MicaBackdrop` instance that was assigned, so from the app's point of view everything looks like it succeeded.
`DesktopAcrylicBackdrop` appears to be affected in the same way and for the same reason, so this should probably be treated as a general "`SystemBackdrop` materials don't work under the system composition engine" issue rather than something specific to Mica.
### Why is this important?
Choosing a composition engine and choosing a backdrop material are two entirely independent decisions, and today the first one silently breaks the second.
An app that already renders correctly can lose its window material purely as a side effect of opting into the system composition engine, i.e. a call that is typically made once at startup, often for unrelated reasons (interop, performance, or platform requirements). The failure is silent and happens far away from the `SystemBackdrop` assignment, so the connection between the two is not at all obvious. Developers reasonably conclude that Mica itself is broken.
The result is also visually severe rather than subtle: instead of degrading to a reasonable solid colour that matches the app's theme, the window is left with a flat black (or white) background that does not match the rest of the app's chrome, so the window looks broken rather than merely unstyled.
Because there is no diagnostic of any kind, the only way to discover the cause is to already know that the two features interact, which makes this expensive to debug and easy to misattribute.
### Steps to reproduce the bug
1. Create a new WinUI 3 (Windows App SDK) desktop app.
2. Opt the process into the system composition engine at startup, before any composition object is created(the engine can only be selected once per process). Note that `CompositionEngine` is a Limited Access Feature, so this requires the corresponding LAF unlock:
```csharp
using Microsoft.UI.Composition;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Media;
public partial class App : Application
{
public App()
{
// Must run before anything creates a Compositor.
CompositionEngine.TrySetProcessEngine(CompositionEngineType.System);
this.InitializeComponent();
}
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
m_window = new MainWindow();
m_window.SystemBackdrop = new MicaBackdrop();
m_window.Activate();
}
private Window m_window;
}
```
3. Run the app and look at the window background. (Make sure the window is large enough, and that its content does not paint an opaque background of its own, so the backdrop is actually visible.)
4. Comment out the `TrySetProcessEngine` call and run again to compare.
Note that `TrySetProcessEngine` returns `true` in this scenario, i.e. the engine switch itself succeeds. It is only the backdrop that fails to apply.
### Actual behavior
The window background is flat and opaque ( black in dark theme, white in light theme). There is no Mica material, no transparency, and no tint from the desktop wallpaper. Nothing is logged and no exception is raised.
### Expected behavior
Setting `SystemBackdrop` to a `MicaBackdrop` should produce a Mica window under the system composition engine too, without the app having to change any of its code or apply a material by some other route.
Mica is a system material, so the same visual result should be achievable regardless of which composition engine the process happens to be using. The backdrop API is the documented, supported way to request it, and it should keep working across that boundary.
Failing that, the API should at minimum fail loudly rather than silently, and should not leave the window in a visually broken state.
### Screenshots
### NuGet package version
2.3.1
### Windows version
Windows Insider Build (26667.1000)
### Additional context
**Scope.** The problem is not that Mica is unavailable under the system composition engine. The material can still be obtained on that path. It is that the `SystemBackdrop` property does not route to it, so the supported API quietly becomes a no-op.
**Workaround.** Apps that need Mica today while using the system composition engine can request it directly from DWM on the window handle, using the public Win32 API:
```cpp
// hwnd is the window handle obtained from the WinUI Window (WindowNative::GetWindowHandle).
auto backdropType = DWMSBT_MAINWINDOW; // DWMSBT_TABBEDWINDOW corresponds to MicaKind.BaseAlt
DwmSetWindowAttribute(hwnd, DWMWA_SYSTEMBACKDROP_TYPE, &backdropType, sizeof(backdropType));
```
This is workable but not a good developer experience:
- It requires dropping to Win32 interop for something the framework already exposes as a first-class XAML property.
- It has to be applied and re-applied by hand, and kept in sync with the `MicaBackdrop.Kind` property, which the framework would otherwise manage.
- Crucially, the app has to know it needs to do this at all, and it only needs to when the system composition engine is in use, which means the code has to branch on the active engine. So the app's rendering code ends up coupled to a process-wide startup decision that is otherwise invisible to it.
**Suggested fix.** `MicaBackdrop` (and `DesktopAcrylicBackdrop`) should detect that the process is using the system composition engine and transparently apply the equivalent system material, so that existing app code continues to work unchanged. The `MicaKind` values should map onto the corresponding system backdrop types so that `Kind` keeps behaving as documented.
Ideally the framework should also avoid painting an opaque background over the material in this configuration, since that is what makes the current failure look like a solid black or white window rather than simply an unstyled one.
Contributor guide
Research direction
Start by tracing the SystemBackdrop handling for MicaBackdrop and DesktopAcrylicBackdrop when CompositionEngine.TrySetProcessEngine selects the system engine. Compare that path with the documented DWM system-backdrop workaround and verify behavior using the provided WinUI 3 reproduction. Done means the material applies under the system engine, or the API reports a clear failure without painting an opaque replacement background.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, csharp
- Domain
- desktop, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100