Win2D pipeline brushes

[Sergio0694]

This PR is part of the group being tracked in #3108.

PR Type

What kind of change does this PR introduce?

• Feature
• Documentation content changes
• Sample app changes

What is the new behavior?

This PR includes a number of new types:

• PipelineBuilder, a C# pipeline builder class that lets developers create complex Win2D/Composition pipelines of effects, with the ability to then convert them into brushes that can be applied to visual elements
• Effects.*, a collection of wrappers for Win2D/Composition effects that can be instantiated from XAML, to build Win2D/Composition brushes directly from XAML
• PipelineBrush, a XAML brush to use in conjunction with the effects mentioned above
• AcrylicBrush, a custom acrylic effect usable from XAML, that lets users customize every aspect of the acrylic pipeline
• TilesBrush, a XAML brush that displayes a tiled textures. Useful to quickly create a noise texture, or other visual effects where a repeated image is needed.

There are other APIs being added, but they're all marked as internal, and are just needed by the new public APIs being included in this PR.

Open questions

I need some input from @michael-hawker and anyone else interested in this PR.
In particular, some aspects to discuss:

• I personally find the AcrylicBrush very useful, but the same exact effect can be achieved by just rebuilding the pipeline from XAML, using the PipelineBrush. Plus, the name might be confusing for users maybe? I wonder whether we should either rename it, or discard that entirely.
• There are some APIs from the PipelineBuilder that could probably use some reorganization in order to make them more flexible. Feel free to glance at the code and provide feedbacks here. In particular, I'm referring to the delegate types used to animate effects along a pipeline.
• I'm thinking the two caching classes (ThreadSafeCompositionCache<T> and ThreadSafeCompositionMapCache<TKey, TValue>) could probably be modified to only use a ConditionalWeakTable<TKey, TValue> instead, targeting a given CoreDispatcher instance instead, which should also make the whole thing more efficient. I'll give that a try and see how it goes.

PR Checklist

Please check if your PR fulfills the following requirements:

• Tested code with current supported SDKs
• Pull Request has been submitted to the documentation repository instructions. Link: #294
• Sample in sample app has been added / updated (for bug fixes / features)
  • Icon has been created (if new sample) following the Thumbnail Style Guide and templates
• Tests for the changes have been added (for bug fixes / features) (if applicable)
• Header has been added to all new source files (run build/UpdateHeaders.bat)
• Contains NO breaking changes

Other information

Marking this PR as draft since I'll expect we'll need to have a conversation on how to better adjust the exposed APIs, etc. Also I'll definitely need some guidance on how to properly structure tests and/or the sample pages for the sample app.

[ghost]

Thanks for opening a Pull Request! The reviewers will test the PR and highlight if there is any conflict or changes required. If the PR is approved we will proceed to merge the pull request 🙌

[michael-hawker]

Just wanted to provide some initial feedback on namespaces and integration with the Toolkit. Looks like a good start.

I'll have to pull it down and play with it a bit first-hand. Don't forget about adding a sample page to the sample app as well. 😊

[michael-hawker]

Suggested change

	namespace Microsoft.Toolkit.Uwp.UI.Media.Brushes
	namespace Microsoft.Toolkit.Uwp.UI.Media

We didn't add Brushes on top of the namespace as we were keeping consistency with the older System.Windows.Media namespace from the RadialGradientBrush. I mean it's the only thing in the package currently, though I see us moving non-brush things in the future. I still think it's fine to have it in the main space.

Thoughts?

[Sergio0694]

I personally don't mind that, and I could make a commit to move all of those into just the .Media namespace then. The only note though is that we also have other public namespaces though, such as .Pipelines now. We can do either of the following:

• Leave all the brushes in just .Media for simplicity and ignore the inconsistency
• Move all the brushes in .Media to get consistency with the other namespaces (and possibly with new ones being added in the future).

Personally I don't mind having the explicit .Brushes namespace, but I can see how having just .Media there would be maybe more intuitive for users. Maybe we should get some more feedbacks from others too? I'd be leaning towards a uniform .Brushes for now I think 🤔

[michael-hawker]

Yeah, let's keep all the brushes in the .Media namespace for consistency with what we have and the OS brushes from WPF and WinUI (which are all in a .Media namespace, e.g. RadialGradientBrush and AcrylicBrush).

[michael-hawker]

Will Files always start with a Capital letter?

[Sergio0694]

So, from what I've seen that's always the case (I've been using this method for a few years now and never had any issues with it), I assume that's just some constant in the XAML engine somewhere. We can either leave it like that or make the test case insensitive if we want to be extra sure.

[michael-hawker]

Let's make it case insensitive to be sure

[michael-hawker]

These are amazing! Thanks @Sergio0694 for all the hard work on these! 🎉🎉🎉