XamlLight Class

Definition

Provides a base class used to create XAML lights that use a CompositionLight to apply lighting effects to XAML elements and brushes.

Equivalent WinUI class: Microsoft.UI.Xaml.Media.XamlLight.

/// [Windows.Foundation.Metadata.Composable(Windows.UI.Xaml.Media.IXamlLightFactory, Windows.Foundation.Metadata.CompositionType.Public, 262144, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 262144)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Static(Windows.UI.Xaml.Media.IXamlLightStatics, 262144, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.WebHostHidden]
class XamlLight : DependencyObject
[Windows.Foundation.Metadata.Composable(typeof(Windows.UI.Xaml.Media.IXamlLightFactory), Windows.Foundation.Metadata.CompositionType.Public, 262144, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 262144)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Static(typeof(Windows.UI.Xaml.Media.IXamlLightStatics), 262144, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.WebHostHidden]
public class XamlLight : DependencyObject
Public Class XamlLight
Inherits DependencyObject
Inheritance
Attributes

Windows 10 requirements

Device family
Windows 10 Creators Update (introduced in 10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v4.0)

Examples

See the code example in Lighting.

Remarks

You can use XamlLight to create custom lights.

For example, it can be used to create a light that applies a composition SpotLight to target elements to light them.

XamlLight provides methods for targeting UIElements or XAML Brushes, applying lights to trees of UIElements, and helping manage the lifetime of CompositionLight resources based on whether they're currently in use.

Custom XamlLights can be used in conjunction with custom Brushes derived from XamlCompositionBrushBase which use a SceneLightingEffect to controls the reflective properties of elements when being lit by a XamlLight.

Targeting objects

If you target a Brush with a XamlLight then the portions of any UIElements using that Brush will be lit by the light.

If you target a UIElement with a XamlLight then the entire UIElement and its child UIElements will all be lit by the light.

Targets can be added and removed by calling methods on a XamlLight instance. XamlLights can also define custom attached properties to add and remove targets from markup.

Managing resources

When creating a XamlLight, it's usually a good practice to delay creating a CompositionLight and any related resources until the light is being used. The OnConnected method is called when a XamlLight is first used to target an element or brush on screen, so you can override OnConnected to safely create resources only when they're needed.

It's also a good practice to dispose of composition resources when they're no longer in use. The OnDisconnected method is called when a XamlLight instance is no longer in use anywhere on the screen, so you can override OnDisconnected to safely dispose of resources. If the XamlLight is later used again after being disconnected then OnConnected will be called again.

Warning

On Windows 10 Creators Update (SDK 15063), CompositionLight can't be accessed after Dispose is called, so setting it to null after calling Dispose causes an error. To work around this issue, you can save the CompositionLight to a temporary variable and call Dispose on that after you set CompositionLight to null. var temp = CompostionLight; CompositionLight = null; temp.Dispose(); This issue is fixed in later versions of the SDK. See Version adaptive apps for info about how to target different SDK versions.

Constructors

XamlLight()

Initializes a new instance of the XamlLight class.

Equivalent WinUI constructor: Microsoft.UI.Xaml.Media.XamlLight.XamlLight.

Properties

CompositionLight

Gets or sets the CompositionLight instance used to apply lighting effects.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.XamlLight.CompositionLight.

Dispatcher

Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.

Equivalent WinUI property: Microsoft.UI.Xaml.DependencyObject.Dispatcher.

(Inherited from DependencyObject)

Methods

AddTargetBrush(String, Brush)

Sets a Brush as a target of a XamlLight.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.AddTargetBrush.

AddTargetElement(String, UIElement)

Sets a UIElement as a target of a XamlLight.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.AddTargetElement.

ClearValue(DependencyProperty)

Clears the local value of a dependency property.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ClearValue.

(Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)

Returns any base value established for a dependency property, which would apply in cases where an animation is not active.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetAnimationBaseValue.

(Inherited from DependencyObject)
GetId()

Returns the identifier for the custom XamlLight type.

In most cases you should use a unique identifier to prevent conflicts. For example, you can use the FullName of your custom XamlLight type.

The identifier is used to add and remove Brushes and UIElements as targets for a specific light type.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.GetId.

GetValue(DependencyProperty)

Returns the current effective value of a dependency property from a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetValue.

(Inherited from DependencyObject)
OnConnected(UIElement)

This method is automatically called when the XamlLight is first in use on the screen, or after being previously disconnected then used again.

This provides an opportunity to create resources such as the CompositionLight only when required.

OnDisconnected will be called when the XamlLight is no longer being used to light any UIElements or Brushes.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.OnConnected.

OnDisconnected(UIElement)

This method is automatically called when the XamlLight is no longer in use anywhere on the screen.

This provides an opportunity to safely dispose of resources such as the CompositionLight when they aren't currently required.

OnConnected will be called again if the XamlLight is later used to light any UIElements or Brushes after being disconnected.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.OnDisconnected.

ReadLocalValue(DependencyProperty)

Returns the local value of a dependency property, if a local value is set.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ReadLocalValue.

(Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)

Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.RegisterPropertyChangedCallback.

(Inherited from DependencyObject)
RemoveTargetBrush(String, Brush)

Stops a Brush from being a target of a XamlLight.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.RemoveTargetBrush.

RemoveTargetElement(String, UIElement)

Stops a UIElement from being a target of a XamlLight.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlLight.RemoveTargetElement.

SetValue(DependencyProperty, Object)

Sets the local value of a dependency property on a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.SetValue.

(Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)

Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.UnregisterPropertyChangedCallback.

(Inherited from DependencyObject)

Applies to

See also