[API Spec] SystemBackdropHost: WinUI3 Background Acrylic Support

[godlytalias]

This is the API Spec for the proposed SystemBackdropHost control for supporting Acrylic effect in WinUI3 for controls other than Window & Flyouts

PR Type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

Description

Current Behavior

New Behavior

Motivation and Context

How Has This Been Tested?

• I have performed a self-review of my own code
• I have added tests to cover my changes

Screenshots (if appropriate):

[Gaoyifei1011]

After the official release of SystemBackdropHost, can WinUI 3 add SystemBackdrop in some pop-up Windows to maintain the consistency of the background color of WinUI 3 and WinUI 2 controls? For example: TeachingTip, ToolTip, Commandbar SecondaryCommands, Combobox popup menu, etc... @godlytalias @AjitSurana

[HO-COOH]

This sounds like only the first step required to support a truly UWP-like acrylic-based popup. To fix the existing issues, developer effort still seems necessary to manually rewrite existing ControlTemplate.

It's better to just fix all those issues by updating all those existing controls' ControlTemplate so that no developer effort is needed.

[godlytalias]

This sounds like only the first step required to support a truly UWP-like acrylic-based popup. To fix the existing issues, developer effort still seems necessary to manually rewrite existing ControlTemplate.

It's better to just fix all those issues by updating all those existing controls' ControlTemplate so that no developer effort is needed.

@HO-COOH Thanks for the response, If we update the template of all controls, that would hit hard on the fundamentals as we would be creating containers to hold the placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

[ghost1372]

@godlytalias Can we use it in next release? (v2.0-exp2)

[godlytalias]

@godlytalias Can we use it in next release? (v2.0-exp2)

@ghost1372 Yes it will be available in exp2 release

[HO-COOH]

@HO-COOH Thanks for the response, If we update the template of all controls, that would hit hard on the fundamentals as we would be creating containers to hold the placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

@godlytalias If that's the case, is there any difference between this and my AcrylicVisual? My existing solution to all these issues also works by finding a place (create one, usually a container if no suitable place), add this acrylic visual.

[godlytalias]

@HO-COOH Thanks for the response, If we update the template of all controls, that would hit hard on the fundamentals as we would be creating containers to hold the placementVisual and the usage of systembackdrop is not justifying to do such a change. Hence we decided to go with a control which developer can easily add to the place wherever they need to have a backdrop.

@godlytalias If that's the case, is there any difference between this and my AcrylicVisual? My existing solution to all these issues also works by finding a place (create one, usually a container if no suitable place), add this acrylic visual.

@HO-COOH I see you're using ContentExternalBackdropLink, so conceptually it would be same. However, ContentExternalBackdropLink API is experimental and so apps won't be able to publish by using it. There is some concerns around making ContentExternalBackdropLink stable in current shape. Hence providing this control in WinUI layer for achieving backdrops.
Moreover I see you're trying to achieve backdrop behavior in combobox, Better way to achieve that may be to apply a custom style of combobox where a SystemBackdrop would be applied on the Popup in the control template. There is a known issue in positioning of backdrop in that way which would get addressed in upcoming release.

[michael-hawker]

I've added this to the public api review process board: https://aka.ms/winappsdk/api-specs-review

This PR will be open for feedback for a month from its opening: October 14th – November 14th

FYI @godlytalias

[dotMorten]

I find this approach as a content item to be weird, and it prevents creating styles with this backdrop. My preference would be a form of brush I can just set as a background brush. In the community call it was mentioned it was hard to do with the current infrastructure, but as an alternative I'd suggest doing this as an attached property instead of a content element. That would allow you to create styles that have the backdrop defined.

[mdtauk]

This would also make adding Acrylic support for those controls that need it, breaking changes, that will require devs to re-template to insert this new object into the visual tree right?

[godlytalias]

If we need to have an attached property on a Control for SystemBackdrop (I guess you mean similar to what we have on Window / Popup), we would need to have a placeholder container added in the control template beneath other parts of the control so that when the backdrop material is applied, the placementVisual can be added to the particular 'placeholder container'. This would affect the fundamentals especially for apps that have very big visual tree, We didn't want to do that on all control templates for supporting a feature that is not very likely to be applied on all instances of the control.

[dotMorten]

@godlytalias Are you saying that WinUI itself doesn't have access to the internal rendering engine to inject this at a lower level when needed? If you're saying it requires re-templating, then you're still thinking of this in terms of adding more FrameworkElements into the UI tree, rather than at the rendering tier level.
Not being able to create custom styles with this setting is a huge break from how we generally develop and designs UIs and easily update and reuse styling. I'd like to be able to do:

<Page.Resources>
  <Style TargetType="Grid" x:Key="AcrylicGrid">
    <Setter Property="SystemBackdrop.Backdrop">
       <Setter.Value>
            <DesktopAcrylicBackdrop /> 
       </Setter.Value>
    </Setter>
  </Style>
</Page.Resources>
<Grid Style="{StaticResource AcrylicGrid}">

</Grid>

The current proposal completely prevents this and feels like a quick band-aid solution.

[godlytalias]

Yes, We wanted to avoid making lot of changes into the rendering stack of WinUI to support SystemBackdrop. We are looking at bringing the support to WinUI3 in the future more similar to the UWP way of using brush. So we came up with this quick and lightweight solution to bridge the gap and to ensure that critical scenarios are unblocked.

[d2phap]

Totally agree with @dotMorten. Since the WinAppSdk v2.0 will introduce the breaking changes, I don't think this

avoid making lot of changes into the rendering stack of WinUI to support SystemBackdrop

is an issue, especially when you guys target this feature for v2.0.

[godlytalias]

@dotMorten @d2phap Thanks for the responses, However the cost of introducing rendering stack changes to support backdrop is not trivial and don't fit into the 2.0 release timelines as well. Moreover as I mentioned above, we have the longterm plan related to compositor to make things work similar to the UWP case, Hence putting such a big cost into making changes to rendering stack is not a wise decision.
Considering the risks & cost of such a solution it was put out of scope for 2.0 release.
We're also evaluating the necessity of bringing this solution down-level to 1.* versions as well, based on the requirements of some critical scenarios.

[Diegorro98]

Can this help to the WebView2 control to get acrylic/mica background so that if the web page rendered is transparent, it can show the acrylic/mica background? (so that it feels more integrated with Windows)

[lhak]

In the current implementation, a change of the SystemBackdrop property (e.g. in a visual state) leads to a crash because changing the SystemBackdrop property of the object implementing ICompositionSupportsSystemBackdrop does not seem to be supported. This limitation should either be fixed in the code or pointed out in the documentation.

[godlytalias]

In the current implementation, a change of the SystemBackdrop property (e.g. in a visual state) leads to a crash because changing the SystemBackdrop property of the object implementing ICompositionSupportsSystemBackdrop does not seem to be supported. This limitation should either be fixed in the code or pointed out in the documentation.

@lhak Whether you're mentioning about a scenario where the SystemBackdrop property getting updated for the control? I've tested this scenario and didn't see a crash. Could you please clarify more on the repro steps? Thanks

[lhak]

In the current implementation, a change of the SystemBackdrop property (e.g. in a visual state) leads to a crash because changing the SystemBackdrop property of the object implementing ICompositionSupportsSystemBackdrop does not seem to be supported. This limitation should either be fixed in the code or pointed out in the documentation.

@lhak Whether you're mentioning about a scenario where the SystemBackdrop property getting updated for the control? I've tested this scenario and didn't see a crash. Could you please clarify more on the repro steps? Thanks

I have investigated this issue again and noticed that switching between the mica and acrylic system backdrops worked fine, but using my custom backdrop caused a crash. I have now found the reason: If the SystemBackdrop property has been set once, then future changes require the backdrop implementation to reuse the compositor of the initial backdrop object. Otherwise, an unauthorized exception will be thrown. I think this should be documented, probably in the ICompositionSupportsSystemBackdrop documentation. Open sourcing the implementation of the inbox backdrops (e.g. MicaController) would also be very helpful.