Adding media samples to WCT sample app

[erinpwoo]

Fixes

Added a media section / brush samples to the WCT sample app. These examples serve as a starting point and will be iterated upon to demonstrate how to use and customize attributes of each brush type. Preview of changes:

These samples are based off of the existing WCT docs: https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/tree/main/docs/brushes

PR Type

What kind of change does this PR introduce?

• Sample app changes

What is the current behavior?

No section currently exists for brushes / effects / pipelines.

What is the new behavior?

Added new section for Media and new subsection for Brushes.

PR Checklist

Please check if your PR fulfills the following requirements:

• Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
• Based off latest main branch of toolkit
• Tested code with current supported SDKs
• New component
  • Documentation has been added
  • Sample in sample app has been added
  • Analyzers are passing for documentation and samples
  • Icon has been created (if new sample) following the Thumbnail Style Guide and templates
• Tests for the changes have been added (if applicable)
• Header has been added to all new source files
• Contains NO breaking changes

Other information

[michael-hawker]

Couple of quick comments, I'll pull this down soon and give them a whirl! Thanks!

[michael-hawker]

@erinpwoo also looks like you need to run XAML Styler

[Arlodotexe]

Building Media.Samples locally, I'm seeing the errors:

1>V:\Windows\components\Media\samples\AcrylicBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\AcrylicBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropBlurBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropBlurBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropGammaTransferBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropGammaTransferBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropInvertBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropInvertBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropSaturationBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropSaturationBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropSepiaBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropSepiaBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\ImageBlendBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\ImageBlendBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\PipelineBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\PipelineBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\PipelineVisualFactory.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\PipelineVisualFactory.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\TilesBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\TilesBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\XamlCompiler\Microsoft.Windows.UI.Xaml.Common.targets(486,5): error MSB4181: The "CompileXaml" task returned false but did not log an error.
1>    13 Warning(s)
1>    11 Error(s)
1>
1>Time Elapsed 00:00:05.25
========== Build: 0 succeeded, 1 failed, 6 up-to-date, 0 skipped ==========

The Category and Subcategory used in the markdown front matter should be sourced from the ToolkitSampleCategory and ToolkitSampleSubcategory enums. The source generator used to discover samples in the gallery parses these categories, and the sample gallery groups them into a tree for the NavigationView pane.

Existing Media samples for EffectAnimations used Animations for the category and Media for the subcategory. For these new samples (visual pipelines, effects and brushes), the Xaml category and the Effects subcategory seem like good options.

[erinpwoo]

@erinpwoo the command you issued was incorrect. Please try again.

Examples are:

@dotnet-policy-service agree

and

@dotnet-policy-service agree company="your company"

@dotnet-policy-service agree

[Arlodotexe]

@erinpwoo Pulling for a local build, I'm still seeing these errors come up.

[Arlodotexe]

Trying to build locally for Wasdk instead of UWP, I ran into this error:

9>            V:\Windows\components\Media\samples\Brushes\AcrylicBrushHostBackdropSample.xaml(24,41): XamlCompiler error WMC0011: Unknown member 'BackgroundSource' on element 'AcrylicBrush'
9>            Xaml Compiler Marker: 6:15:02 PM: 964 perfXC_PageValidateEnd, V:\Windows\components\Media\samples\Brushes\AcrylicBrushHostBackdropSample.xaml
9>            Xaml Compiler Marker: 6:15:02 PM: 964 perfXC_PageDone, Brushes\AcrylicBrushHostBackdropSample.xaml
9>            Xaml Compiler Marker: 6:15:02 PM: 964 perfXC_PageStart, Brushes\AcrylicBrushSample.xaml
9>            Xaml Compiler Marker: 6:15:02 PM: 964 perfXC_PageLoadStart, V:\Windows\components\Media\samples\Brushes\AcrylicBrushSample.xaml
9>            Xaml Compiler Marker: 6:15:02 PM: 965 perfXC_PageLoadEnd, V:\Windows\components\Media\samples\Brushes\AcrylicBrushSample.xaml
9>            Xaml Compiler Marker: 6:15:02 PM: 965 perfXC_PageValidateStart, V:\Windows\components\Media\samples\Brushes\AcrylicBrushSample.xaml
9>            V:\Windows\components\Media\samples\Brushes\AcrylicBrushSample.xaml(24,41): XamlCompiler error WMC0011: Unknown member 'BackgroundSource' on element 'AcrylicBrush'

It looks like AcrylicBrush has a small difference between WUX (UWP) and MUX (wasdk)-- BackgroundSource doesn't appear in the Windows App SDK.

We'll have to accommodate in our sample-- conditional XAML maybe? @michael-hawker ideas here?

[michael-hawker]

Our AcrylicBrush is its own thing, it's this line here that removes it from WinUI 3:

Windows/components/Media/src/Brushes/AcrylicBrush.cs

Lines 37 to 70 in c068d2d

	#if WINUI2
	/// <summary>
	/// Gets or sets the background source mode for the effect (the default is <see cref="AcrylicBackgroundSource.Backdrop"/>).
	/// </summary>
	public AcrylicBackgroundSource BackgroundSource
	{
	get => (AcrylicBackgroundSource)GetValue(BackgroundSourceProperty);
	set => SetValue(BackgroundSourceProperty, value);
	}
	/// <summary>
	/// Identifies the <see cref="BackgroundSource"/> dependency property.
	/// </summary>
	public static readonly DependencyProperty BackgroundSourceProperty = DependencyProperty.Register(
	nameof(BackgroundSource),
	typeof(AcrylicBackgroundSource),
	typeof(AcrylicBrush),
	new PropertyMetadata(AcrylicBackgroundSource.Backdrop, OnSourcePropertyChanged));
	/// <summary>
	/// Updates the UI when <see cref="BackgroundSource"/> changes
	/// </summary>
	/// <param name="d">The current <see cref="AcrylicBrush"/> instance</param>
	/// <param name="e">The <see cref="DependencyPropertyChangedEventArgs"/> instance for <see cref="BackgroundSourceProperty"/></param>
	private static void OnSourcePropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
	{
	if (d is AcrylicBrush brush &&
	brush.CompositionBrush != null)
	{
	brush.OnDisconnected();
	brush.OnConnected();
	}
	}
	#endif

We should instead mark this with a warning or deprecation or something if it's WinUI 3 vs. removing it. Then the sample will still compile and work in both places.

So, we should probably call this out as a warning block in the docs as well. (e.g. WinUI 3 will always use the Backdrop over HostBackdrop)

(This might mean we have a copy of the enum in our namespace for WinUI 3)

[michael-hawker]

The other option is we just have the sample show the regular Backdrop and ignore the host bit for now too.

[erinpwoo]

I think the BackgroundSource error was one of the reasons I wasn't able to get the WASDK build to work with my changes applied. If it's not available in WinUI, should the property even be documented like it currently is in the AcrylicBrush sample page?

[erinpwoo]

Building Media.Samples locally, I'm seeing the errors:

1>V:\Windows\components\Media\samples\AcrylicBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\AcrylicBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropBlurBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropBlurBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropGammaTransferBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropGammaTransferBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropInvertBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropInvertBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropSaturationBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropSaturationBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\BackdropSepiaBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\BackdropSepiaBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\ImageBlendBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\ImageBlendBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\PipelineBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\PipelineBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\PipelineVisualFactory.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\PipelineVisualFactory.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>V:\Windows\components\Media\samples\TilesBrush.md(1,1,1,1): error TKSMPL0010: Cannot generate sample page info for file V:\Windows\components\Media\samples\TilesBrush.md as an error was encountered parsing its YAML front matter: Can't parse category field, use value from ToolkitSampleCategory enum.
1>C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\XamlCompiler\Microsoft.Windows.UI.Xaml.Common.targets(486,5): error MSB4181: The "CompileXaml" task returned false but did not log an error.
1>    13 Warning(s)
1>    11 Error(s)
1>
1>Time Elapsed 00:00:05.25
========== Build: 0 succeeded, 1 failed, 6 up-to-date, 0 skipped ==========

The Category and Subcategory used in the markdown front matter should be sourced from the ToolkitSampleCategory and ToolkitSampleSubcategory enums. The source generator used to discover samples in the gallery parses these categories, and the sample gallery groups them into a tree for the NavigationView pane.

Existing Media samples for EffectAnimations used Animations for the category and Media for the subcategory. For these new samples (visual pipelines, effects and brushes), the Xaml category and the Effects subcategory seem like good options.

@Arlodotexe I had added the Media ToolkitSampleCategory in addition to the Brushes subcategory. It renders like this in the navigation panel:

Do you think it's failing here because of the other xaml failures related to the BackgroundSource property on the Acrylic brush?

[erinpwoo]

Updated AcrylicBrush sample to remove the second example that uses the BackgroundSource property. Instead added a note about the property in a "UWP only" blurb:

Addressed the last few comments so the build in WinUI should work now, @Arlodotexe @michael-hawker give it a try and let me know if you have any other feedback.

[Arlodotexe]

Got it, I'm able to compile and test now. Seems to work as expected now!

@michael-hawker I'm comparing these new docs to our existing Media docs, and noticed that unlike the EffectAnimations which has many effect samples in a single doc, here we've created a separate document (and separate sample) for every brush.

I think it makes sense to aggregate the Brush-related samples into a single .md doc, like we've done for EffectAnimations in this component. Thoughts?

[erinpwoo]

@Arlodotexe @michael-hawker Just updated to consolidate all the samples into a single Brushes markdown file, still in the same category / subcategory. I left the PipelineBrush and PipelineVisualFactory in their own pages:

[michael-hawker]

Replacing with #654 without submodule changes.