Replace various WPF include files with content (#1335)

* net-current-v30plus-md.md

* net-current-v40plus-md.md

* tla2sharptla-ui-md.md

* tla2sharptla-uiautomation-md.md

* tla2sharptla-winclient-md.md

* tla2sharptla-xaml-md.md

* tlasharptla-ui-md.md

* tlasharptla-uiautomation-md.md

* tlasharptla-winclient-md.md

* tlasharptla-xaml-md.md

* fix warnings
This commit is contained in:
Andy (Steve) De George
2022-03-16 12:14:11 -04:00
committed by GitHub
parent dd0052ecec
commit be103da07e
353 changed files with 1339 additions and 1349 deletions
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 4f091835-28d1-498c-b660-9b3acf34ed13
---
# 3D Graphics How-to Topics
The topics in this section demonstrate how to use 3D graphics in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications.
The topics in this section demonstrate how to use 3D graphics in Windows Presentation Foundation (WPF) applications.
## In This Section
[Create a 3D Scene](how-to-create-a-3-d-scene.md)
@@ -12,22 +12,22 @@ helpviewer_keywords:
ms.assetid: 67f31ed4-e36b-4b02-9889-dcce245d7afc
---
# 3D Graphics Overview
<a name="introduction"></a> The 3D functionality in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] enables developers to draw, transform, and animate 3D graphics in both markup and procedural code. Developers can combine 2D and 3D graphics to create rich controls, provide complex illustrations of data, or enhance the user experience of an application's interface. 3D support in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is not designed to provide a full-featured game-development platform. This topic provides an overview of 3D functionality in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] graphics system.
<a name="introduction"></a> The 3D functionality in WPF is not designed to provide a full-featured game-development platform. This topic provides an overview of 3D functionality in the WPF graphics system.
<a name="threed_in_2d"></a>
## 3D in a 2D Container
3D graphics content in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is encapsulated in an element, <xref:System.Windows.Controls.Viewport3D>, that can participate in the two-dimensional element structure. The graphics system treats <xref:System.Windows.Controls.Viewport3D> as a two-dimensional visual element like many others in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. <xref:System.Windows.Controls.Viewport3D> functions as a window—a viewport—into a three-dimensional scene. More accurately, it is a surface on which a 3D scene is projected.
3D graphics content in WPF is encapsulated in an element, <xref:System.Windows.Controls.Viewport3D>, that can participate in the two-dimensional element structure. The graphics system treats <xref:System.Windows.Controls.Viewport3D> as a two-dimensional visual element like many others in WPF. <xref:System.Windows.Controls.Viewport3D> functions as a window—a viewport—into a three-dimensional scene. More accurately, it is a surface on which a 3D scene is projected.
In a conventional 2D application, use <xref:System.Windows.Controls.Viewport3D> as you would another container element like Grid or Canvas. Although you can use <xref:System.Windows.Controls.Viewport3D> with other 2D drawing objects in the same scene graph, you cannot interpenetrate 2D and 3D objects within a <xref:System.Windows.Controls.Viewport3D>. This topic will focus on how to draw 3D graphics inside the <xref:System.Windows.Controls.Viewport3D>.
<a name="coord_space"></a>
## 3D Coordinate Space
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] coordinate system for 2D graphics locates the origin in the upper left of the rendering area (typically the screen). In the 2D system, positive x-axis values proceed to the right and positive y-axis values proceed downward. In the 3D coordinate system, however, the origin is located in the center of the rendering area, with positive x-axis values proceeding to the right but positive y-axis values proceeding upward instead, and positive z-axis values proceeding outward from the origin, toward the viewer.
The WPF coordinate system for 2D graphics locates the origin in the upper left of the rendering area (typically the screen). In the 2D system, positive x-axis values proceed to the right and positive y-axis values proceed downward. In the 3D coordinate system, however, the origin is located in the center of the rendering area, with positive x-axis values proceeding to the right but positive y-axis values proceeding upward instead, and positive z-axis values proceeding outward from the origin, toward the viewer.
![Coordinate systems](./media/coordsystem-1.png "CoordSystem-1")
Conventional 2D and 3D coordinate system representations
The space defined by these axes is the stationary frame of reference for 3D objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. As you build models in this space and create lights and cameras to view them, it's helpful to distinguish this stationary frame of reference, or "world space," from the local frame of reference you create for each model when you apply transformations to it. Remember also that objects in world space might look entirely different, or not be visible at all, depending on light and camera settings, but the position of the camera does not change the location of objects in world space.
The space defined by these axes is the stationary frame of reference for 3D objects in WPF. As you build models in this space and create lights and cameras to view them, it's helpful to distinguish this stationary frame of reference, or "world space," from the local frame of reference you create for each model when you apply transformations to it. Remember also that objects in world space might look entirely different, or not be visible at all, depending on light and camera settings, but the position of the camera does not change the location of objects in world space.
<a name="cameras"></a>
## Cameras and Projections
@@ -53,17 +53,17 @@ Perspective and Orthographic Projections
<a name="models_meshes"></a>
## Model and Mesh Primitives
<xref:System.Windows.Media.Media3D.Model3D> is the abstract base class that represents a generic 3D object. To build a 3D scene, you need some objects to view, and the objects that make up the scene graph derive from <xref:System.Windows.Media.Media3D.Model3D>. Currently, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports modeling geometries with <xref:System.Windows.Media.Media3D.GeometryModel3D>. The <xref:System.Windows.Media.Media3D.GeometryModel3D.Geometry%2A> property of this model takes a mesh primitive.
<xref:System.Windows.Media.Media3D.Model3D> is the abstract base class that represents a generic 3D object. To build a 3D scene, you need some objects to view, and the objects that make up the scene graph derive from <xref:System.Windows.Media.Media3D.Model3D>. Currently, the WPF supports modeling geometries with <xref:System.Windows.Media.Media3D.GeometryModel3D>. The <xref:System.Windows.Media.Media3D.GeometryModel3D.Geometry%2A> property of this model takes a mesh primitive.
To build a model, begin by building a primitive, or mesh. A 3D primitive is a collection of vertices that form a single 3D entity. Most 3D systems provide primitives modeled on the simplest closed figure: a triangle defined by three vertices. Because the three points of a triangle are coplanar, you can continue adding triangles in order to model more complex shapes, called meshes.
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] 3D system currently provides the <xref:System.Windows.Media.Media3D.MeshGeometry3D> class, which allows you to specify any geometry; it does not currently support predefined 3D primitives like spheres and cubic forms. Begin creating a <xref:System.Windows.Media.Media3D.MeshGeometry3D> by specifying a list of triangle vertices as its <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> property. Each vertex is specified as a <xref:System.Windows.Media.Media3D.Point3D>. (In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], specify this property as a list of numbers grouped in threes that represent the coordinates of each vertex.) Depending on its geometry, your mesh might be composed of many triangles, some of which share the same corners (vertices). To draw the mesh correctly, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] needs information about which vertices are shared by which triangles. You provide this information by specifying a list of triangle indices with the <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A> property. This list specifies the order in which the points specified in the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list will determine a triangle.
The WPF 3D system currently provides the <xref:System.Windows.Media.Media3D.MeshGeometry3D> class, which allows you to specify any geometry; it does not currently support predefined 3D primitives like spheres and cubic forms. Begin creating a <xref:System.Windows.Media.Media3D.MeshGeometry3D> by specifying a list of triangle vertices as its <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> property. Each vertex is specified as a <xref:System.Windows.Media.Media3D.Point3D>. (In WPF needs information about which vertices are shared by which triangles. You provide this information by specifying a list of triangle indices with the <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A> property. This list specifies the order in which the points specified in the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list will determine a triangle.
[!code-xaml[basic3d#Basic3DXAML3DN3](~/samples/snippets/xaml/VS_Snippets_Wpf/Basic3D/XAML/Window1.xaml#basic3dxaml3dn3)]
In the preceding example, the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list specifies eight vertices to define a cube-shaped mesh. The <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A> property specifies a list of twelve groups of three indices. Each number in the list refers to an offset into the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list. For example, the first three vertices specified by the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list are (1,1,0), (0,1,0), and (0,0,0). The first three indices specified by the <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A> list are 0, 2, and 1, which correspond to the first, third, and second points in the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A> list. As a result, the first triangle that makes up the cube model will be composed from (1,1,0) to (0,1,0) to (0,0,0), and the remaining eleven triangles will be determined similarly.
You can continue defining the model by specifying values for the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Normals%2A> and <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A> properties. To render the surface of the model, the graphics system needs information about which direction the surface is facing at any given triangle. It uses this information to make lighting calculations for the model: surfaces that face directly towards a light source appear brighter than those angled away from the light. Though the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can determine default normal vectors by using the position coordinates, you can also specify different normal vectors to approximate the appearance of curved surfaces.
You can continue defining the model by specifying values for the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Normals%2A> and <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A> properties. To render the surface of the model, the graphics system needs information about which direction the surface is facing at any given triangle. It uses this information to make lighting calculations for the model: surfaces that face directly towards a light source appear brighter than those angled away from the light. Though the WPF can determine default normal vectors by using the position coordinates, you can also specify different normal vectors to approximate the appearance of curved surfaces.
The <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A> property specifies a collection of <xref:System.Windows.Point>s that tell the graphics system how to map the coordinates that determine how a texture is drawn to the vertices of the mesh. <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A> are specified as a value between zero and 1, inclusive. As with the <xref:System.Windows.Media.Media3D.MeshGeometry3D.Normals%2A> property, the graphics system can calculate default texture coordinates, but you might choose to set different texture coordinates to control the mapping of a texture that includes part of a repeating pattern, for example. More information about texture coordinates can be found in subsequent topics or in the Managed Direct3D SDK.
@@ -80,7 +80,7 @@ Perspective and Orthographic Projections
For a mesh to look like a three-dimensional object, it must have an applied texture to cover the surface defined by its vertices and triangles so it can be lit and projected by the camera. In 2D, you use the <xref:System.Windows.Media.Brush> class to apply colors, patterns, gradients, or other visual content to areas of the screen. The appearance of 3D objects, however, is a function of the lighting model, not just of the color or pattern applied to them. Real-world objects reflect light differently depending on the quality of their surfaces: glossy and shiny surfaces don't look the same as rough or matte surfaces, and some objects seem to absorb light while others glow. You can apply all the same brushes to 3D objects that you can apply to 2D objects, but you can't apply them directly.
To define the characteristics of a model's surface, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses the <xref:System.Windows.Media.Media3D.Material> abstract class. The concrete subclasses of Material determine some of the appearance characteristics of the model's surface, and each also provides a Brush property to which you can pass a SolidColorBrush, TileBrush, or VisualBrush.
To define the characteristics of a model's surface, WPF uses the <xref:System.Windows.Media.Media3D.Material> abstract class. The concrete subclasses of Material determine some of the appearance characteristics of the model's surface, and each also provides a Brush property to which you can pass a SolidColorBrush, TileBrush, or VisualBrush.
- <xref:System.Windows.Media.Media3D.DiffuseMaterial> specifies that the brush will be applied to the model as though that model were lit diffusely. Using DiffuseMaterial most resembles using brushes directly on 2D models; model surfaces do not reflect light as though shiny.
@@ -101,7 +101,7 @@ Perspective and Orthographic Projections
<a name="lights"></a>
## Illuminating the Scene
Lights in 3D graphics do what lights do in the real world: they make surfaces visible. More to the point, lights determine what part of a scene will be included in the projection. Light objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] create a variety of light and shadow effects and are modeled after the behavior of various real-world lights. Include at least one light in your scene, or no models will be visible.
Lights in 3D graphics do what lights do in the real world: they make surfaces visible. More to the point, lights determine what part of a scene will be included in the projection. Light objects in WPF create a variety of light and shadow effects and are modeled after the behavior of various real-world lights. Include at least one light in your scene, or no models will be visible.
The following lights derive from the base class <xref:System.Windows.Media.Media3D.Light>:
@@ -136,9 +136,9 @@ Perspective and Orthographic Projections
<a name="animations"></a>
## Animating Models
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] 3D implementation participates in the same timing and animation system as 2D graphics. In other words, to animate a 3D scene, animate the properties of its models. It's possible to animate properties of primitives directly, but it's typically easier to animate transformations that change the position or appearance of models. Because transformations can be applied to <xref:System.Windows.Media.Media3D.Model3DGroup> objects as well as individual models, it's possible to apply one set of animations to a child of a Model3DGroup and another set of animations to a group of child objects. You can also achieve a variety of visual effects by animating the properties of your scene's lighting. Finally, you might choose to animate the projection itself by animating the camera position or field of view. For background information on the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] timing and animation system, see the [Animation Overview](animation-overview.md), [Storyboards Overview](storyboards-overview.md), and [Freezable Objects Overview](../advanced/freezable-objects-overview.md) topics.
The WPF 3D implementation participates in the same timing and animation system as 2D graphics. In other words, to animate a 3D scene, animate the properties of its models. It's possible to animate properties of primitives directly, but it's typically easier to animate transformations that change the position or appearance of models. Because transformations can be applied to <xref:System.Windows.Media.Media3D.Model3DGroup> objects as well as individual models, it's possible to apply one set of animations to a child of a Model3DGroup and another set of animations to a group of child objects. You can also achieve a variety of visual effects by animating the properties of your scene's lighting. Finally, you might choose to animate the projection itself by animating the camera position or field of view. For background information on the WPF timing and animation system, see the [Animation Overview](animation-overview.md), [Storyboards Overview](storyboards-overview.md), and [Freezable Objects Overview](../advanced/freezable-objects-overview.md) topics.
To animate an object in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you create a timeline, define an animation (which is really a change in some property value over time), and specify the property to which to apply the animation. Because all the objects in a 3D scene are children of <xref:System.Windows.Controls.Viewport3D>, the properties targeted by any animation you want to apply to the scene are properties of Viewport3D.
To animate an object in WPF, you create a timeline, define an animation (which is really a change in some property value over time), and specify the property to which to apply the animation. Because all the objects in a 3D scene are children of <xref:System.Windows.Controls.Viewport3D>, the properties targeted by any animation you want to apply to the scene are properties of Viewport3D.
Suppose you want to make a model appear to wobble in place. You might choose to apply a <xref:System.Windows.Media.Media3D.RotateTransform3D> to the model, and animate the axis of its rotation from one vector to another. The following code example demonstrates applying a Vector3DAnimation to the Axis property of the transformation's Rotation3D, assuming the RotateTransform3D to be one of several transforms applied to the model with a TransformGroup.
@@ -11,17 +11,17 @@ helpviewer_keywords:
ms.assetid: e45e555d-ac1e-4b36-aced-e433afe7f27f
---
# 3D Transformations Overview
This topic describes how to apply transformations to 3D models in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] graphics system. Transformations allow the developer to reposition, resize, and reorient models without changing the base values that define them.
This topic describes how to apply transformations to 3D models in the Windows Presentation Foundation (WPF) graphics system. Transformations allow the developer to reposition, resize, and reorient models without changing the base values that define them.
## 3D Coordinate Space
3D graphics content in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is encapsulated in an element, <xref:System.Windows.Controls.Viewport3D>, that can participate in the two-dimensional element structure. The graphics system treats Viewport3D as a two-dimensional visual element like many others in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. Viewport3D functions as a window—a viewport—into a three-dimensional scene. More accurately, it is a surface on which a 3D scene is projected. Although you can use Viewport3D with other 2D drawing objects in the same scene graph, you cannot interpenetrate 2D and 3D objects within a Viewport3D. In the following discussion, the coordinate space described is contained by the Viewport3D element.
3D graphics content in Windows Presentation Foundation (WPF) is encapsulated in an element, <xref:System.Windows.Controls.Viewport3D>, that can participate in the two-dimensional element structure. The graphics system treats Viewport3D as a two-dimensional visual element like many others in Windows Presentation Foundation (WPF). Viewport3D functions as a window—a viewport—into a three-dimensional scene. More accurately, it is a surface on which a 3D scene is projected. Although you can use Viewport3D with other 2D drawing objects in the same scene graph, you cannot interpenetrate 2D and 3D objects within a Viewport3D. In the following discussion, the coordinate space described is contained by the Viewport3D element.
The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] coordinate system for 2D graphics locates the origin in the upper left of the rendering surface (typically the screen). In the 2D system, positive x-axis values proceed to the right and positive y-axis values proceed downward. In the 3D coordinate system, however, the origin is located in the center of the screen, with positive x-axis values proceeding to the right but positive y-axis values proceeding upward instead, and positive z-axis values proceeding outward from the origin, toward the viewer.
The Windows Presentation Foundation (WPF) coordinate system for 2D graphics locates the origin in the upper left of the rendering surface (typically the screen). In the 2D system, positive x-axis values proceed to the right and positive y-axis values proceed downward. In the 3D coordinate system, however, the origin is located in the center of the screen, with positive x-axis values proceeding to the right but positive y-axis values proceeding upward instead, and positive z-axis values proceeding outward from the origin, toward the viewer.
![Coordinate systems](./media/coordsystem-1.png "CoordSystem-1")
Coordinate System Comparison
The space defined by these axes is the stationary frame of reference for 3D objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. As you build models in this space and create lights and cameras to view them, it's helpful to distinguish this stationary frame of reference, or "world space," from the local frame of reference you create for each model when you apply transformations to it. Remember also that objects in world space might look entirely different, or not be visible at all, depending on light and camera settings, but the position of the camera does not change the location of objects in world space.
The space defined by these axes is the stationary frame of reference for 3D objects in Windows Presentation Foundation (WPF). As you build models in this space and create lights and cameras to view them, it's helpful to distinguish this stationary frame of reference, or "world space," from the local frame of reference you create for each model when you apply transformations to it. Remember also that objects in world space might look entirely different, or not be visible at all, depending on light and camera settings, but the position of the camera does not change the location of objects in world space.
## Transforming Models
When you create models, they have a particular location in the scene. To move those models around in the scene, to rotate them, or to change their size, it's not practical to change the vertices that define the models themselves. Instead, just as in 2D, you apply transformations to models.
@@ -29,7 +29,7 @@ Coordinate System Comparison
Each model object has a <xref:System.Windows.Media.Media3D.Model3D.Transform%2A> property with which you can move, re-orient, or resize the model. When you apply a transform, you effectively offset all the points of the model by whatever vector or value is specified by the transform. In other words, you've transformed the coordinate space in which the model is defined ("model space"), but you haven't changed the values that make up the model's geometry in the coordinate system of the entire scene ("world space").
## Translation Transformations
3D transformations inherit from the abstract base class <xref:System.Windows.Media.Media3D.Transform3D>; these include the affine transform classes <xref:System.Windows.Media.Media3D.TranslateTransform3D>, <xref:System.Windows.Media.Media3D.ScaleTransform3D>, and <xref:System.Windows.Media.Media3D.RotateTransform3D>. The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 3D system also provides a <xref:System.Windows.Media.Media3D.MatrixTransform3D> class that lets you specify the same transformations in more concise matrix operations.
3D transformations inherit from the abstract base class <xref:System.Windows.Media.Media3D.Transform3D>; these include the affine transform classes <xref:System.Windows.Media.Media3D.TranslateTransform3D>, <xref:System.Windows.Media.Media3D.ScaleTransform3D>, and <xref:System.Windows.Media.Media3D.RotateTransform3D>. The Windows Presentation Foundation (WPF) 3D system also provides a <xref:System.Windows.Media.Media3D.MatrixTransform3D> class that lets you specify the same transformations in more concise matrix operations.
<xref:System.Windows.Media.Media3D.TranslateTransform3D> moves all the points in the Model3D in the direction of the offset vector you specify with the <xref:System.Windows.Media.Media3D.TranslateTransform3D.OffsetX%2A>, <xref:System.Windows.Media.Media3D.TranslateTransform3D.OffsetY%2A>, and <xref:System.Windows.Media.Media3D.TranslateTransform3D.OffsetZ%2A> properties. For example, given one vertex of a cube at (2,2,2), an offset vector of (0,1.6,1) would move that vertex (2,2,2) to (2,3.6,3). The cube's vertex is still (2,2,2) in model space, but now that model space has changed its relationship to world space so that (2,2,2) in model space is (2,3.6,3) in world space.
@@ -60,7 +60,7 @@ Scale Center Example
[!code-xaml[animation3dgallery_snip#Rotate3DUsingAxisAngleRotation3DExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/Animation3DGallery_snip/CS/Rotat3DUsingAxisAngleRotation3DExample.xaml#rotate3dusingaxisanglerotation3dexamplewholepage)]
Note:[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 3D is a right-handed system, which means that a positive angle value for a rotation results in a counter-clockwise rotation about the axis.
Note:Windows Presentation Foundation (WPF) 3D is a right-handed system, which means that a positive angle value for a rotation results in a counter-clockwise rotation about the axis.
Axis-angle rotations assume rotation about the origin if a value is not specified for the <xref:System.Windows.Media.Media3D.RotateTransform3D.CenterX%2A>, <xref:System.Windows.Media.Media3D.RotateTransform3D.CenterY%2A>, and <xref:System.Windows.Media.Media3D.RotateTransform3D.CenterZ%2A> properties on RotateTransform3D. As with scaling, it's helpful to remember that the rotation transforms the model's entire coordinate space. If the model was not created about the origin, or has been translated previously, the rotation might "pivot" about the origin instead of rotating in place.
@@ -80,9 +80,9 @@ Rotation Example
When building a scene, it's common to apply more than one transformation to a model. Add transforms to the <xref:System.Windows.Media.Media3D.Transform3DGroup.Children%2A> collection of the <xref:System.Windows.Media.Media3D.Transform3DGroup> class to group transforms conveniently to apply to various models in the scene. It's often convenient to reuse a transformation in several different groups, in much the way that you can reuse a model by applying a different set of transforms to each instance. Note that order in which the transformations are added to the collection is significant: transforms in the collection are applied from first to last.
## Animating Transformations
The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 3D implementation participates in the same timing and animation system as 2D graphics. In other words, to animate a 3D scene, animate the properties of its models. It's possible to animate properties of primitives directly, but it's typically easier to animate transformations that change the position or appearance of models. Because transformations can be applied to <xref:System.Windows.Media.Media3D.Model3DGroup> objects as well as individual models, it's possible to apply one set of animations to the children of a Model3Dgroup and another set of animations to a group of objects. For background information on the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] timing and animation system, see [Animation Overview](animation-overview.md) and [Storyboards Overview](storyboards-overview.md).
The Windows Presentation Foundation (WPF) 3D implementation participates in the same timing and animation system as 2D graphics. In other words, to animate a 3D scene, animate the properties of its models. It's possible to animate properties of primitives directly, but it's typically easier to animate transformations that change the position or appearance of models. Because transformations can be applied to <xref:System.Windows.Media.Media3D.Model3DGroup> objects as well as individual models, it's possible to apply one set of animations to the children of a Model3Dgroup and another set of animations to a group of objects. For background information on the Windows Presentation Foundation (WPF) timing and animation system, see [Animation Overview](animation-overview.md) and [Storyboards Overview](storyboards-overview.md).
To animate an object in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], create a timeline, define an animation (which is really a change in some property value over time), and specify the property to which to apply the animation. This property must be a property of a FrameworkElement. Because all the objects in a 3D scene are children of Viewport3D, the properties targeted by any animation you want to apply to the scene are properties of properties of Viewport3D. It's important to work out the property path for the animation carefully, because the syntax can be verbose.
To animate an object in Windows Presentation Foundation (WPF), create a timeline, define an animation (which is really a change in some property value over time), and specify the property to which to apply the animation. This property must be a property of a FrameworkElement. Because all the objects in a 3D scene are children of Viewport3D, the properties targeted by any animation you want to apply to the scene are properties of properties of Viewport3D. It's important to work out the property path for the animation carefully, because the syntax can be verbose.
Suppose you want to rotate an object in place, but also to apply a swinging motion to expose more of the object to view. You might choose to apply a RotateTransform3D to the model, and animate the axis of its rotation from one vector to another. The following code example demonstrates applying a <xref:System.Windows.Media.Animation.Vector3DAnimation> to the Axis property of the transformation's Rotation3D, assuming the RotateTransform3D to be one of several transforms applied to the model with a <xref:System.Windows.Media.TransformGroup>.
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 587e36f6-1957-424e-9d89-c43724f26d84
---
# Animation and Timing How-to Topics
The following topics demonstrate how to use the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] animation and timing system in your applications.
The following topics demonstrate how to use the Windows Presentation Foundation (WPF) animation and timing system in your applications.
## In This Section
[Accelerate or Decelerate an Animation](how-to-accelerate-or-decelerate-an-animation.md)
@@ -11,7 +11,7 @@ This topic describes how the timing system uses the animation, <xref:System.Wind
<a name="prerequisites"></a>
## Prerequisites
To understand this topic, you should be able to use [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animations to animate properties, as described in the [Animation Overview](animation-overview.md). It also helps to be familiar with dependency properties; for more information, see the [Dependency Properties Overview](../advanced/dependency-properties-overview.md).
To understand this topic, you should be able to use WPF animations to animate properties, as described in the [Animation Overview](animation-overview.md). It also helps to be familiar with dependency properties; for more information, see the [Dependency Properties Overview](../advanced/dependency-properties-overview.md).
<a name="timelinesandclocks"></a>
## Timelines and Clocks
@@ -36,11 +36,11 @@ This topic describes how the timing system uses the animation, <xref:System.Wind
<a name="timemanager"></a>
## Clocks and the Time Manager
When you animate objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], its the time manager that manages the <xref:System.Windows.Media.MediaPlayer.Clock%2A> objects created for your timelines. The time manager is the root of a tree of <xref:System.Windows.Media.MediaPlayer.Clock%2A> objects and controls the flow of time in that tree. A time manager is automatically created for each [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application and is invisible to the application developer. The time manager "ticks" many times per second; the actual number of ticks that occur each second varies depending on available system resources. During each one of these ticks, the time manager computes the state of all <xref:System.Windows.Media.Animation.ClockState.Active> <xref:System.Windows.Media.Animation.Clock> objects in the timing tree.
When you animate objects in WPF, its the time manager that manages the <xref:System.Windows.Media.MediaPlayer.Clock%2A> objects created for your timelines. The time manager is the root of a tree of <xref:System.Windows.Media.MediaPlayer.Clock%2A> objects and controls the flow of time in that tree. A time manager is automatically created for each WPF application and is invisible to the application developer. The time manager "ticks" many times per second; the actual number of ticks that occur each second varies depending on available system resources. During each one of these ticks, the time manager computes the state of all <xref:System.Windows.Media.Animation.ClockState.Active> <xref:System.Windows.Media.Animation.Clock> objects in the timing tree.
The following illustration shows the relationship between the time manager, and <xref:System.Windows.Media.Animation.AnimationClock>, and an animated dependency property.
![Timing system components](./media/graphicsmm-clocks-1clock1prop.png "graphicsmm_clocks_1clock1prop")
![Timing system components and the time manager.](./media/graphicsmm-clocks-1clock1prop.png "graphicsmm_clocks_1clock1prop")
Animating a property
When the time manager ticks, it updates the time of every <xref:System.Windows.Media.Animation.ClockState.Active> <xref:System.Windows.Media.Animation.Clock> in the application. If the <xref:System.Windows.Media.Animation.Clock> is an <xref:System.Windows.Media.Animation.AnimationClock>, it uses the <xref:System.Windows.Media.Animation.AnimationTimeline.GetCurrentValue%2A> method of the <xref:System.Windows.Media.Animation.AnimationTimeline> from which it was created to calculate its current output value. The <xref:System.Windows.Media.Animation.AnimationClock> supplies the <xref:System.Windows.Media.Animation.AnimationTimeline> with the current local time, an input value, which is typically the base value of the property, and a default destination value. When you retrieve the value of an animated by property using the <xref:System.Windows.DependencyObject.GetValue%2A> method or its CLR accessor, you get the output of its <xref:System.Windows.Media.Animation.AnimationClock>.
@@ -48,13 +48,13 @@ Animating a property
#### Clock Groups
The preceding section described how there are different types of <xref:System.Windows.Media.Animation.Clock> objects for different types of timelines. The following illustration shows the relationship between the time manager, a <xref:System.Windows.Media.Animation.ClockGroup>, an <xref:System.Windows.Media.Animation.AnimationClock>, and an animated dependency property. A <xref:System.Windows.Media.Animation.ClockGroup> is created for timelines that group other timelines, such as the <xref:System.Windows.Media.Animation.Storyboard> class, which groups animations and other timelines.
![Timing system components](./media/graphicsmm-clocks-2clock1clockgroup2prop.png "graphicsmm_clocks_2clock1clockgroup2prop")
![Timing system components with the time manager and dependency properties.](./media/graphicsmm-clocks-2clock1clockgroup2prop.png "graphicsmm_clocks_2clock1clockgroup2prop")
A ClockGroup
#### Composition
It's possible to associate multiple clocks with a single property, in which case each clock uses the output value of the preceding clock as its base value. The following illustration shows three <xref:System.Windows.Media.Animation.AnimationClock> objects applied to the same property. Clock1 uses the base value of the animated property as its input and uses it to generate output. Clock2 takes the output from Clock1 as its input and uses it to generate output. Clock3 takes the output from Clock2 as its input and uses it to generate output. When multiple clocks affect the same property simultaneously, they are said to be in a composition chain.
![Timing system components](./media/graphicsmm-clocks-2clock1prop.png "graphicsmm_clocks_2clock1prop")
![Timing system components composed with multiple dependency properties.](./media/graphicsmm-clocks-2clock1prop.png "graphicsmm_clocks_2clock1prop")
A composition chain
Note that although a relationship is created among the input and output of the <xref:System.Windows.Media.Animation.AnimationClock> objects in the composition chain, their timing behaviors are not affected; <xref:System.Windows.Media.Animation.Clock> objects (including <xref:System.Windows.Media.Animation.AnimationClock> objects) have a hierarchical dependency on their parent <xref:System.Windows.Media.Animation.Clock> objects.
@@ -14,9 +14,9 @@ ms.assetid: bd9ce563-725d-4385-87c9-d7ee38cf79ea
# Animation Overview
<a name="introduction"></a>
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a powerful set of graphics and layout features that enable you to create attractive user interfaces and appealing documents. Animation can make an attractive user interface even more spectacular and usable. By just animating a background color or applying an animated <xref:System.Windows.Media.Transform>, you can create dramatic screen transitions or provide helpful visual cues.
Windows Presentation Foundation (WPF) provides a powerful set of graphics and layout features that enable you to create attractive user interfaces and appealing documents. Animation can make an attractive user interface even more spectacular and usable. By just animating a background color or applying an animated <xref:System.Windows.Media.Transform>, you can create dramatic screen transitions or provide helpful visual cues.
This overview provides an introduction to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation and timing system. It focuses on the animation of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects by using storyboards.
This overview provides an introduction to the WPF animation and timing system. It focuses on the animation of WPF objects by using storyboards.
<a name="introducinganimations"></a>
@@ -34,15 +34,15 @@ Animation on a computer is similar. For example, a program that makes a drawing
- The program then updates the rectangle with the new value and redraws it.
Prior to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], Microsoft Windows developers had to create and manage their own timing systems or use special custom libraries. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes an efficient timing system that is exposed through managed code and [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and that is deeply integrated into the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] framework. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation makes it easy to animate controls and other graphical objects.
Prior to WPF, Microsoft Windows developers had to create and manage their own timing systems or use special custom libraries. WPF includes an efficient timing system that is exposed through managed code and WPF framework. WPF animation makes it easy to animate controls and other graphical objects.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] handles all the behind-the-scenes work of managing a timing system and redrawing the screen efficiently. It provides timing classes that enable you to focus on the effects you want to create, instead of the mechanics of achieving those effects. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also makes it easy to create your own animations by exposing animation base classes from which your classes can inherit, to produce customized animations. These custom animations gain many of the performance benefits of the standard animation classes.
WPF handles all the behind-the-scenes work of managing a timing system and redrawing the screen efficiently. It provides timing classes that enable you to focus on the effects you want to create, instead of the mechanics of achieving those effects. WPF also makes it easy to create your own animations by exposing animation base classes from which your classes can inherit, to produce customized animations. These custom animations gain many of the performance benefits of the standard animation classes.
<a name="thewpftimingsystem"></a>
## WPF Property Animation System
If you understand a few important concepts about the timing system, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animations can be easier to use. Most important is that, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you animate objects by applying animation to their individual properties. For example, to make a framework element grow, you animate its <xref:System.Windows.FrameworkElement.Width%2A> and <xref:System.Windows.FrameworkElement.Height%2A> properties. To make an object fade from view, you animate its <xref:System.Windows.UIElement.Opacity%2A> property.
If you understand a few important concepts about the timing system, WPF animations can be easier to use. Most important is that, in WPF, you animate objects by applying animation to their individual properties. For example, to make a framework element grow, you animate its <xref:System.Windows.FrameworkElement.Width%2A> and <xref:System.Windows.FrameworkElement.Height%2A> properties. To make an object fade from view, you animate its <xref:System.Windows.UIElement.Opacity%2A> property.
For a property to have animation capabilities, it must meet the following three requirements:
@@ -50,9 +50,9 @@ For a property to have animation capabilities, it must meet the following three
- It must belong to a class that inherits from <xref:System.Windows.DependencyObject> and implements the <xref:System.Windows.Media.Animation.IAnimatable> interface.
- There must be a compatible animation type available. (If [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not provide one, you can create your own. See the [Custom Animations Overview](custom-animations-overview.md).)
- There must be a compatible animation type available. (If WPF does not provide one, you can create your own. See the [Custom Animations Overview](custom-animations-overview.md).)
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] contains many objects that have <xref:System.Windows.Media.Animation.IAnimatable> properties. Controls such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TabControl>, and also <xref:System.Windows.Controls.Panel> and <xref:System.Windows.Shapes.Shape> objects inherit from <xref:System.Windows.DependencyObject>. Most of their properties are dependency properties.
WPF contains many objects that have <xref:System.Windows.Media.Animation.IAnimatable> properties. Controls such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TabControl>, and also <xref:System.Windows.Controls.Panel> and <xref:System.Windows.Shapes.Shape> objects inherit from <xref:System.Windows.DependencyObject>. Most of their properties are dependency properties.
You can use animations almost anywhere, which includes in styles and control templates. Animations do not have to be visual; you can animate objects that are not part of the user interface if they meet the criteria that are described in this section.
@@ -60,7 +60,7 @@ You can use animations almost anywhere, which includes in styles and control tem
## Example: Make an Element Fade In and Out of View
This example shows how to use a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation to animate the value of a dependency property. It uses a <xref:System.Windows.Media.Animation.DoubleAnimation>, which is a type of animation that generates <xref:System.Double> values, to animate the <xref:System.Windows.UIElement.Opacity%2A> property of a <xref:System.Windows.Shapes.Rectangle>. As a result, the <xref:System.Windows.Shapes.Rectangle> fades in and out of view.
This example shows how to use a WPF animation to animate the value of a dependency property. It uses a <xref:System.Windows.Media.Animation.DoubleAnimation>, which is a type of animation that generates <xref:System.Double> values, to animate the <xref:System.Windows.UIElement.Opacity%2A> property of a <xref:System.Windows.Shapes.Rectangle>. As a result, the <xref:System.Windows.Shapes.Rectangle> fades in and out of view.
The first part of the example creates a <xref:System.Windows.Shapes.Rectangle> element. The steps that follow show how to create an animation and apply it to the rectangle's <xref:System.Windows.UIElement.Opacity%2A> property.
@@ -150,7 +150,7 @@ For more information about <xref:System.Windows.Media.Animation.Storyboard.Targe
### Part 3 (XAML): Associate the Storyboard with a Trigger
The easiest way to apply and start a <xref:System.Windows.Media.Animation.Storyboard> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is to use an event trigger. This section shows how to associate the <xref:System.Windows.Media.Animation.Storyboard> with a trigger in XAML.
The easiest way to apply and start a <xref:System.Windows.Media.Animation.Storyboard> in XAML is to use an event trigger. This section shows how to associate the <xref:System.Windows.Media.Animation.Storyboard> with a trigger in XAML.
1. Create a <xref:System.Windows.Media.Animation.BeginStoryboard> object and associate your storyboard with it. A <xref:System.Windows.Media.Animation.BeginStoryboard> is a type of <xref:System.Windows.TriggerAction> that applies and starts a <xref:System.Windows.Media.Animation.Storyboard>.
@@ -248,7 +248,7 @@ As previously mentioned, a timeline represents a segment of time. The length of
An animation uses its <xref:System.Windows.Media.Animation.Timeline.Duration%2A> property to determine its current value. If you do not specify a <xref:System.Windows.Media.Animation.Timeline.Duration%2A> value for an animation, it uses 1 second, which is the default.
The following syntax shows a simplified version of the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] attribute syntax for the <xref:System.Windows.Media.Animation.Timeline.Duration%2A> property.
The following syntax shows a simplified version of the Extensible Application Markup Language (XAML) attribute syntax for the <xref:System.Windows.Media.Animation.Timeline.Duration%2A> property.
*hours* `:` *minutes* `:` *seconds*
@@ -262,7 +262,7 @@ The following table shows several <xref:System.Windows.Duration> settings and th
One way to specify a <xref:System.Windows.Duration> in code is to use the <xref:System.TimeSpan.FromSeconds%2A> method to create a <xref:System.TimeSpan>, then declare a new <xref:System.Windows.Duration> structure using that <xref:System.TimeSpan>.
For more information about <xref:System.Windows.Duration> values and the complete [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] syntax, see the <xref:System.Windows.Duration> structure.
For more information about <xref:System.Windows.Duration> values and the complete Extensible Application Markup Language (XAML) syntax, see the <xref:System.Windows.Duration> structure.
#### AutoReverse
@@ -288,13 +288,13 @@ Assigning a name to a <xref:System.Windows.FrameworkElement> differs from assign
- To make a <xref:System.Windows.FrameworkElement> an animation target, you give it a name by setting its <xref:System.Windows.FrameworkElement.Name%2A> property. In code, you must also use the <xref:System.Windows.FrameworkElement.RegisterName%2A> method to register the element name with the page to which it belongs.
- To make a <xref:System.Windows.Freezable> object an animation target in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use the [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) to assign it a name. In code, you just use the <xref:System.Windows.FrameworkElement.RegisterName%2A> method to register the object with the page to which it belongs.
- To make a <xref:System.Windows.Freezable> object an animation target in XAML, you use the [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) to assign it a name. In code, you just use the <xref:System.Windows.FrameworkElement.RegisterName%2A> method to register the object with the page to which it belongs.
The sections that follow provide an example of naming an element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and code. For more detailed information about naming and targeting, see the [Storyboards Overview](storyboards-overview.md).
The sections that follow provide an example of naming an element in XAML and code. For more detailed information about naming and targeting, see the [Storyboards Overview](storyboards-overview.md).
### Applying and Starting Storyboards
To start a storyboard in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you associate it with an <xref:System.Windows.EventTrigger>. An <xref:System.Windows.EventTrigger> is an object that describes what actions to take when a specified event occurs. One of those actions can be a <xref:System.Windows.Media.Animation.BeginStoryboard> action, which you use to start your storyboard. Event triggers are similar in concept to event handlers because they enable you to specify how your application responds to a particular event. Unlike event handlers, event triggers can be fully described in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]; no other code is required.
To start a storyboard in XAML, you associate it with an <xref:System.Windows.EventTrigger>. An <xref:System.Windows.EventTrigger> is an object that describes what actions to take when a specified event occurs. One of those actions can be a <xref:System.Windows.Media.Animation.BeginStoryboard> action, which you use to start your storyboard. Event triggers are similar in concept to event handlers because they enable you to specify how your application responds to a particular event. Unlike event handlers, event triggers can be fully described in XAML; no other code is required.
To start a <xref:System.Windows.Media.Animation.Storyboard> in code, you can use an <xref:System.Windows.EventTrigger> or use the <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method of the <xref:System.Windows.Media.Animation.Storyboard> class.
@@ -19,7 +19,7 @@ Bitmap effects enable designers and developers to apply visual effects to render
Bitmap effects (<xref:System.Windows.Media.Effects.BitmapEffect> object) are simple pixel processing operations. A bitmap effect takes a <xref:System.Windows.Media.Imaging.BitmapSource> as an input and produces a new <xref:System.Windows.Media.Imaging.BitmapSource> after applying the effect, such as a blur or drop shadow. Each bitmap effect exposes properties that can control the filtering properties, such as <xref:System.Windows.Media.Effects.BlurBitmapEffect.Radius%2A> of <xref:System.Windows.Media.Effects.BlurBitmapEffect>.
As a special case, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], effects can be set as properties on live <xref:System.Windows.Media.Visual> objects, such as a <xref:System.Windows.Controls.Button> or <xref:System.Windows.Controls.TextBox>. The pixel processing is applied and rendered at run-time. In this case, at the time of rendering, a <xref:System.Windows.Media.Visual> is automatically converted to its <xref:System.Windows.Media.Imaging.BitmapSource> equivalent and is fed as input to the <xref:System.Windows.Media.Effects.BitmapEffect>. The output replaces the <xref:System.Windows.Media.Visual> object's default rendering behavior. This is why <xref:System.Windows.Media.Effects.BitmapEffect> objects force visuals to render in software only i.e. no hardware acceleration on visuals when effects are applied.
As a special case, in WPF, effects can be set as properties on live <xref:System.Windows.Media.Visual> objects, such as a <xref:System.Windows.Controls.Button> or <xref:System.Windows.Controls.TextBox>. The pixel processing is applied and rendered at run-time. In this case, at the time of rendering, a <xref:System.Windows.Media.Visual> is automatically converted to its <xref:System.Windows.Media.Imaging.BitmapSource> equivalent and is fed as input to the <xref:System.Windows.Media.Effects.BitmapEffect>. The output replaces the <xref:System.Windows.Media.Visual> object's default rendering behavior. This is why <xref:System.Windows.Media.Effects.BitmapEffect> objects force visuals to render in software only i.e. no hardware acceleration on visuals when effects are applied.
- <xref:System.Windows.Media.Effects.BlurBitmapEffect> simulates an object that appears out-of-focus.
@@ -42,7 +42,7 @@ Bitmap effects enable designers and developers to apply visual effects to render
<xref:System.Windows.Media.Effects.BitmapEffect> is a property on <xref:System.Windows.Media.Visual>. Therefore applying effects to Visuals, such as a <xref:System.Windows.Controls.Button>, <xref:System.Windows.Controls.Image>, <xref:System.Windows.Media.DrawingVisual>, or <xref:System.Windows.UIElement>, is as easy as setting a property. <xref:System.Windows.UIElement.BitmapEffect%2A> can be set to a single <xref:System.Windows.Media.Effects.BitmapEffect> object or multiple effects can be chained by using the <xref:System.Windows.Media.Effects.BitmapEffectGroup> object.
The following example demonstrates how to apply a <xref:System.Windows.Media.Effects.BitmapEffect> in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
The following example demonstrates how to apply a <xref:System.Windows.Media.Effects.BitmapEffect> in Extensible Application Markup Language (XAML).
[!code-xaml[EffectsGallery_snip#BlurSimpleExampleInline](~/samples/snippets/csharp/VS_Snippets_Wpf/EffectsGallery_snip/CSharp/blursimpleexample.xaml#blursimpleexampleinline)]
@@ -11,7 +11,7 @@ helpviewer_keywords:
ms.assetid: be180b56-ca6e-4da3-a839-f6b0bf482f7d
---
# Bitmap Effects
The topics in this section describe how to apply visual effects to bitmap images using [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
The topics in this section describe how to apply visual effects to bitmap images using Windows Presentation Foundation (WPF).
> [!IMPORTANT]
> In the .NET Framework 4 or later, the <xref:System.Windows.Media.Effects.BitmapEffect> class is obsolete. If you try to use the <xref:System.Windows.Media.Effects.BitmapEffect> class, you will get an obsolete exception. The non-obsolete alternative to the <xref:System.Windows.Media.Effects.BitmapEffect> class is the <xref:System.Windows.Media.Effects.Effect> class. In most situations, the <xref:System.Windows.Media.Effects.Effect> class is significantly faster.
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 43e7f798-9558-4498-b5b6-4a4c6baf956b
---
# Brushes How-to Topics
The following topics demonstrate how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] brushes in order to paint content to the screen.
The following topics demonstrate how to use Windows Presentation Foundation (WPF) brushes in order to paint content to the screen.
## In This Section
[Animate the Color or Opacity of a SolidColorBrush](how-to-animate-the-color-or-opacity-of-a-solidcolorbrush.md)
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 26710879-12ad-4c63-9bc6-a1834bb4243b
---
# Brushes
The following topics describe how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] brushes to "paint" content to the screen
The following topics describe how to use Windows Presentation Foundation (WPF) brushes to "paint" content to the screen
## In This Section
[WPF Brushes Overview](wpf-brushes-overview.md)
@@ -11,19 +11,19 @@ helpviewer_keywords:
ms.assetid: 9be69d50-3384-4938-886f-08ce00e4a7a6
---
# Custom Animations Overview
This topic describes how and when to extend the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation system by creating custom key frames, animation classes, or by using per-frame callback to bypass it.
This topic describes how and when to extend the WPF animation system by creating custom key frames, animation classes, or by using per-frame callback to bypass it.
<a name="prerequisites"></a>
## Prerequisites
To understand this topic, you should be familiar with the different types of animations provided by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. For more information, see the From/To/By Animations Overview, the [Key-Frame Animations Overview](key-frame-animations-overview.md), and the [Path Animations Overview](path-animations-overview.md).
To understand this topic, you should be familiar with the different types of animations provided by the WPF. For more information, see the From/To/By Animations Overview, the [Key-Frame Animations Overview](key-frame-animations-overview.md), and the [Path Animations Overview](path-animations-overview.md).
Because the animation classes inherit from the <xref:System.Windows.Freezable> class, you should be familiar with <xref:System.Windows.Freezable> objects and how to inherit from <xref:System.Windows.Freezable>. For more information, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md).
<a name="extendingtheanimationsystem"></a>
## Extending the Animation System
There are a number of ways to extend the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation system, depending on the level of built-in functionality you want to use. There are three primary extensibility points in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation engine:
There are a number of ways to extend the WPF animation system, depending on the level of built-in functionality you want to use. There are three primary extensibility points in the WPF animation engine:
- Create a custom key frame object by inheriting from one of the *\<Type>*KeyFrame classes, such as <xref:System.Windows.Media.Animation.DoubleKeyFrame>. This approach uses most of the built-in functionality of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation engine.
- Create a custom key frame object by inheriting from one of the *\<Type>*KeyFrame classes, such as <xref:System.Windows.Media.Animation.DoubleKeyFrame>. This approach uses most of the built-in functionality of the WPF animation engine.
- Create your own animation class by inheriting from <xref:System.Windows.Media.Animation.AnimationTimeline> or one of the *\<Type>*AnimationBase classes.
@@ -35,7 +35,7 @@ This topic describes how and when to extend the [!INCLUDE[TLA2#tla_winclient](..
|-------------------------|-----------------------|
|Customize the interpolation between values of a type that has a corresponding *\<Type>*AnimationUsingKeyFrames|Create a custom key frame. For more information, see the [Create a Custom Key Frame](#createacustomkeyframe) section.|
|Customize more than just the interpolation between values of a type that has a corresponding *\<Type>*Animation.|Create a custom animation class that inherits from the *\<Type>*AnimationBase class that corresponds to the type you want to animate. For more information, see the [Create a Custom Animation Class](#createacustomanimationtype) section.|
|Animate a type that has no corresponding [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation|Use an <xref:System.Windows.Media.Animation.ObjectAnimationUsingKeyFrames> or create a class that inherits from <xref:System.Windows.Media.Animation.AnimationTimeline>. For more information, see the [Create a Custom Animation Class](#createacustomanimationtype) section.|
|Animate a type that has no corresponding WPF animation|Use an <xref:System.Windows.Media.Animation.ObjectAnimationUsingKeyFrames> or create a class that inherits from <xref:System.Windows.Media.Animation.AnimationTimeline>. For more information, see the [Create a Custom Animation Class](#createacustomanimationtype) section.|
|Animate multiple objects with values that are computed each frame and are based on the last set of object interactions|Use per-frame callback. For more information, see the [Create a Use Per-Frame Callback](#useperframecallback) section.|
<a name="createacustomkeyframe"></a>
@@ -73,10 +73,10 @@ This topic describes how and when to extend the [!INCLUDE[TLA2#tla_winclient](..
**Alternative Approaches**
If you simply want to change how animation values are interpolated, considering deriving from one of the *\<Type>*KeyFrame classes. The key frame you create can be used with the corresponding *\<Type>*AnimationUsingKeyFrames provided by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
If you simply want to change how animation values are interpolated, considering deriving from one of the *\<Type>*KeyFrame classes. The key frame you create can be used with the corresponding *\<Type>*AnimationUsingKeyFrames provided by WPF.
### Derive from AnimationTimeline
Derive from the <xref:System.Windows.Media.Animation.AnimationTimeline> class when you want to create an animation for a type that doesn't already have a matching [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation, or you want to create an animation that is not strongly typed.
Derive from the <xref:System.Windows.Media.Animation.AnimationTimeline> class when you want to create an animation for a type that doesn't already have a matching WPF animation, or you want to create an animation that is not strongly typed.
**Implementation Instructions**
@@ -92,7 +92,7 @@ This topic describes how and when to extend the [!INCLUDE[TLA2#tla_winclient](..
If the class does not use dependency properties to store its data or it requires extra initialization after creation, you might need to override additional methods; see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md) for more information.
The recommended paradigm (used by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animations) is to use two inheritance levels:
The recommended paradigm (used by WPF animations) is to use two inheritance levels:
1. Create an abstract *\<Type>*AnimationBase class that derives from <xref:System.Windows.Media.Animation.AnimationTimeline>. This class should override the <xref:System.Windows.Media.Animation.AnimationTimeline.TargetPropertyType%2A> method. It should also introduce a new abstract method, GetCurrentValueCore, and override <xref:System.Windows.Media.Animation.AnimationTimeline.GetCurrentValue%2A> so that it validates the types of the default origin value and default destination value parameters, then calls GetCurrentValueCore.
@@ -104,13 +104,13 @@ This topic describes how and when to extend the [!INCLUDE[TLA2#tla_winclient](..
<a name="useperframecallback"></a>
## Use Per-Frame Callback
Use this approach when you need to completely bypass the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation system. One scenario for this approach is physics animations, where at each animation step a new direction or position of animated objects needs to be recomputed based on the last set of object interactions.
Use this approach when you need to completely bypass the WPF animation system. One scenario for this approach is physics animations, where at each animation step a new direction or position of animated objects needs to be recomputed based on the last set of object interactions.
**Implementation Instructions**
Unlike the other approaches described in this overview, to use per-frame callback you don't need to create a custom animation or key frame class.
Instead, you register for the <xref:System.Windows.Media.CompositionTarget.Rendering> event of the object that contains the objects you want to animate. This event handler method gets called once per frame. Each time that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] marshals the persisted rendering data in the visual tree across to the composition tree, your event handler method is called.
Instead, you register for the <xref:System.Windows.Media.CompositionTarget.Rendering> event of the object that contains the objects you want to animate. This event handler method gets called once per frame. Each time that WPF marshals the persisted rendering data in the visual tree across to the composition tree, your event handler method is called.
In your event handler, perform your whatever calculations necessary for your animation effect and set the properties of the objects you want to animate with these values.
@@ -89,7 +89,7 @@ A 100 by 100 ImageDrawing
## Play Media (Code Only)
> [!NOTE]
> Although you can declare a <xref:System.Windows.Media.VideoDrawing> in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can only load and play its media using code. To play video in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], use a <xref:System.Windows.Controls.MediaElement> instead.
> Although you can declare a <xref:System.Windows.Media.VideoDrawing> in Extensible Application Markup Language (XAML), you can only load and play its media using code. To play video in Extensible Application Markup Language (XAML), use a <xref:System.Windows.Controls.MediaElement> instead.
To play an audio or video file, you use a <xref:System.Windows.Media.VideoDrawing> and a <xref:System.Windows.Media.MediaPlayer>. There are two ways to load and play media. The first is to use a <xref:System.Windows.Media.MediaPlayer> and a <xref:System.Windows.Media.VideoDrawing> by themselves, and the second way is to create your own <xref:System.Windows.Media.MediaTimeline> to use with the <xref:System.Windows.Media.MediaPlayer> and <xref:System.Windows.Media.VideoDrawing>.
@@ -14,7 +14,7 @@ This topic describes how to use From/To/By animations to animate dependency prop
<a name="prereq"></a>
## Prerequisites
To understand this topic, you should be familiar with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animations features. For an introduction to animation features, see the [Animation Overview](animation-overview.md).
To understand this topic, you should be familiar with WPF animations features. For an introduction to animation features, see the [Animation Overview](animation-overview.md).
<a name="whatisanimation"></a>
## What Is a From/To/By Animation?
@@ -34,7 +34,7 @@ This topic describes how to use From/To/By animations to animate dependency prop
Where *\<Type>* is the type of value that the class animates.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides the following From/To/By animation classes.
WPF provides the following From/To/By animation classes.
|Property type|Corresponding From/To/By animation class|
|-------------------|------------------------------------------------|
@@ -126,13 +126,13 @@ This topic describes how to use From/To/By animations to animate dependency prop
<a name="otheranimationtypes"></a>
## Other Animation Types
From/To/By animations are not the only type of animations that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides: it also provides key-frame animations and path animations.
From/To/By animations are not the only type of animations that WPF provides: it also provides key-frame animations and path animations.
- A key-frame animation animates along any number of destination values, described using key frames. For more information, see the [Key-Frame Animations Overview](key-frame-animations-overview.md).
- A path animation generates output values from a <xref:System.Windows.Media.PathGeometry>. For more information, see the [Path Animations Overview](path-animations-overview.md).
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also enables you to create your own custom animation types. For more information, see the [Custom Animations Overview](custom-animations-overview.md).
WPF also enables you to create your own custom animation types. For more information, see the [Custom Animations Overview](custom-animations-overview.md).
## See also
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 9fba8934-98b7-4af6-82f6-f4ef887f963a
---
# Geometry Overview
This overview describes how to use the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] <xref:System.Windows.Media.Geometry> classes to describe shapes. This topic also contrasts the differences between <xref:System.Windows.Media.Geometry> objects and <xref:System.Windows.Shapes.Shape> elements.
This overview describes how to use the Windows Presentation Foundation (WPF) <xref:System.Windows.Media.Geometry> classes to describe shapes. This topic also contrasts the differences between <xref:System.Windows.Media.Geometry> objects and <xref:System.Windows.Shapes.Shape> elements.
<a name="wcpsdk_graphics_geometry_introduction"></a>
## What Is a Geometry?
@@ -137,7 +137,7 @@ A PathGeometry that contains a single LineSegment
The example then adds an <xref:System.Windows.Media.ArcSegment>, which is drawn from the end point of the preceding <xref:System.Windows.Media.LineSegment> to the point specified by its <xref:System.Windows.Media.ArcSegment.Point%2A> property. The example also specifies the arc's x- and y-radius (<xref:System.Windows.Media.ArcSegment.Size%2A>), a rotation angle (<xref:System.Windows.Media.ArcSegment.RotationAngle%2A>), a flag indicating how large the angle of the resulting arc should be (<xref:System.Windows.Media.ArcSegment.IsLargeArc%2A>), and a value indicating in which direction the arc is drawn (<xref:System.Windows.Media.ArcSegment.SweepDirection%2A>). The following illustration shows the shape created by this example.
![A PathGeometry](./media/graphicsmm-path2.gif "graphicsmm_path2")
![A PathGeometry with an arc.](./media/graphicsmm-path2.gif "graphicsmm_path2")
A PathGeometry
[!code-xaml[GeometryOverviewSamples_snip#GraphicsMMPathGeometryComplexExample](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometryOverviewSamples_snip/CS/GeometryExamples.xaml#graphicsmmpathgeometrycomplexexample)]
@@ -149,7 +149,7 @@ A PathGeometry
The following example creates a <xref:System.Windows.Media.PathGeometry> with two <xref:System.Windows.Media.PathFigure> objects, each of which contains multiple <xref:System.Windows.Media.PathSegment> objects. The <xref:System.Windows.Media.PathFigure> from the above example and a <xref:System.Windows.Media.PathFigure> with a <xref:System.Windows.Media.PolyLineSegment> and a <xref:System.Windows.Media.QuadraticBezierSegment> are used. A <xref:System.Windows.Media.PolyLineSegment> is defined with an array of points and the <xref:System.Windows.Media.QuadraticBezierSegment> is defined with a control point and an end point. The following illustration shows the shape created by this example.
![A PathGeometry](./media/graphicsmm-path.gif "graphicsmm_path")
![A PathGeometry with an arc that includes two PathFigure objects.](./media/graphicsmm-path.gif "graphicsmm_path")
A PathGeometry with multiple figures
[!code-xaml[GeometryOverviewSamples_snip#GraphicsMMPathGeometryComplexMultiExample](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometryOverviewSamples_snip/CS/GeometryExamples.xaml#graphicsmmpathgeometrycomplexmultiexample)]
@@ -163,7 +163,7 @@ A PathGeometry with multiple figures
For an example, see [Create a Shape Using a StreamGeometry](how-to-create-a-shape-using-a-streamgeometry.md).
### Path Markup Syntax
The <xref:System.Windows.Media.PathGeometry> and <xref:System.Windows.Media.StreamGeometry> types support a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] attribute syntax using a special series of move and draw commands. For more information, see [Path Markup Syntax](path-markup-syntax.md).
The <xref:System.Windows.Media.PathGeometry> and <xref:System.Windows.Media.StreamGeometry> types support a Extensible Application Markup Language (XAML) attribute syntax using a special series of move and draw commands. For more information, see [Path Markup Syntax](path-markup-syntax.md).
<a name="wcpsdk_graphics_geometry_introduction2"></a>
## Composite Geometries
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 959cb1cc-d26c-4bbc-b637-251091987288
---
# Graphics How-to Topics
The following topics demonstrate how to use the graphic capabilities of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
The following topics demonstrate how to use the graphic capabilities of the Windows Presentation Foundation (WPF).
## In This Section
[Animate a Rectangle](how-to-animate-a-rectangle.md)
@@ -12,11 +12,11 @@ helpviewer_keywords:
ms.assetid: f4b41b42-327d-407c-b398-3ed5f505df8b
---
# Graphics Rendering Registry Settings
This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] graphics rendering registry settings that affect [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications.
This topic provides an overview of the WPF graphics rendering registry settings that affect WPF applications.
<a name="overview"></a>
## When to Use Graphics Rendering Registry Settings
These registry settings are provided for troubleshooting, debugging, and product support purposes. Because changes to the registry affect all [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, your application should never alter these registry keys automatically, or during installation.
These registry settings are provided for troubleshooting, debugging, and product support purposes. Because changes to the registry affect all WPF applications, your application should never alter these registry keys automatically, or during installation.
<a name="xpdmandwddm"></a>
## What are XPDM and WDDM?
@@ -24,16 +24,16 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
<a name="registry_settings"></a>
## Registry Settings
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides four registry settings for controlling [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering:
WPF provides four registry settings for controlling WPF rendering:
|Setting|Description|
|-------------|-----------------|
|**Disable Hardware Acceleration Option**|Specifies whether hardware acceleration should be enabled.|
|**Maximum Multisample Value**|Specifies the degree of multisampling for antialiasing 3D content.|
|**Required Video Driver Date Setting**|Specifies whether the system disables hardware acceleration for drivers released before November 2004.|
|**Use Reference Rasterizer Option**|Specifies whether [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] should use the reference rasterizer.|
|**Use Reference Rasterizer Option**|Specifies whether WPF should use the reference rasterizer.|
These settings can be accessed by any external configuration utility that knows how to reference the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor.
These settings can be accessed by any external configuration utility that knows how to reference the WPF registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor.
<a name="disablehardwareacceleration"></a>
## Disable Hardware Acceleration Option
@@ -57,7 +57,7 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
The **maximum multisample value** is a DWORD value that ranges from 0 to 16. A value of 0 specifies that multisample antialiasing of 3D content should be disabled, and a value of 16 will attempt to use up to 16x multisample antialiasing, if supported by the video card. Beware that setting this registry key value on computers using XPDM drivers will cause applications to use a large amount of additional video memory, decrease the performance of 3D rendering, and has the potential to introduce rendering errors and stability problems.
When this registry key is not set, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] defaults to 0 for XPDM drivers and 4 for WDDM drivers.
When this registry key is not set, WPF defaults to 0 for XPDM drivers and 4 for WDDM drivers.
<a name="requiredvideodriverdatesetting"></a>
## Required Video Driver Date Setting
@@ -66,9 +66,9 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
|------------------|----------------|
|`HKEY_CURRENT_USER\SOFTWARE\Microsoft\Avalon.Graphics\RequiredVideoDriverDate`|String|
In November, 2004, Microsoft released a new version of the driver testing guidelines; the drivers written after this date offer better stability. By default, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] will use the hardware acceleration pipeline for these drivers and will fall back to software rendering for XPDM drivers published before this date.
In November, 2004, Microsoft released a new version of the driver testing guidelines; the drivers written after this date offer better stability. By default, WPF will use the hardware acceleration pipeline for these drivers and will fall back to software rendering for XPDM drivers published before this date.
The **required video driver date setting** enables you to specify an alternate minimum date for XPDM drivers. You should only specify a date earlier than November, 2004 if you are confident that your video driver is stable enough to support [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
The **required video driver date setting** enables you to specify an alternate minimum date for XPDM drivers. You should only specify a date earlier than November, 2004 if you are confident that your video driver is stable enough to support WPF.
The required video driver setting takes a string of the following format:
@@ -76,7 +76,7 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
|---------------|
|*YYYY* `/` *MM* `/` *DD*|
Where *YYYY* is the four-digit year, *MM* is the two-digit month, and *DD* is the two digit day. When this value is unset, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses November, 2004 as its required video driver date.
Where *YYYY* is the four-digit year, *MM* is the two-digit month, and *DD* is the two digit day. When this value is unset, WPF uses November, 2004 as its required video driver date.
<a name="usereferencerasterizeroption"></a>
## Use Reference Rasterizer Option
@@ -85,11 +85,11 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
|------------------|----------------|
|`HKEY_CURRENT_USER\SOFTWARE\Microsoft\Avalon.Graphics\UseReferenceRasterizer`|DWORD|
The **use reference rasterizer option** enables you to force [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] into a simulated hardware rendering mode for debugging: [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] goes into hardware mode, but uses the Microsoft Direct3D reference software rasterizer, d3dref9.dll, instead of an actual hardware device.
The **use reference rasterizer option** enables you to force WPF into a simulated hardware rendering mode for debugging: WPF goes into hardware mode, but uses the Microsoft Direct3D reference software rasterizer, d3dref9.dll, instead of an actual hardware device.
The reference rasterizer is very slow, but bypasses your video driver to avoid any rendering issues caused by driver problems. For this reason, you can use the reference rasterizer to determine if rendering issues are caused by the video driver. The d3dref9.dll file must be in a location where the application can access it, such as in any location in the system path or in the local directory of the application.
The **use reference rasterizer option** takes a DWORD value. A value of 0 indicates that the reference rasterizer is not used. Any other non-zero value forces [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to use the reference rasterizer.
The **use reference rasterizer option** takes a DWORD value. A value of 0 indicates that the reference rasterizer is not used. Any other non-zero value forces WPF to use the reference rasterizer.
## See also
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 3bfc652e-91b7-4697-a4f4-83ff0e98327e
---
# Graphics
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] offers integrated support for multimedia, vector graphics, animation, and content composition, making it easy for developers to build interesting user interfaces and content.
Windows Presentation Foundation (WPF) offers integrated support for multimedia, vector graphics, animation, and content composition, making it easy for developers to build interesting user interfaces and content.
## In This Section
[Bitmap Effects](bitmap-effects.md)
@@ -38,7 +38,7 @@ Diagram of valid hit test region
<a name="hit_testing_and_z-order"></a>
## Hit Testing and Z-Order
The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] visual layer supports hit testing against all objects under a point or geometry, not just the top-most object. Results are returned in z-order. However, the visual object that you pass as the parameter to the <xref:System.Windows.Media.VisualTreeHelper.HitTest%2A> method determines which portion of the visual tree that will be hit test. You can hit test against the entire visual tree, or any portion of it.
The Windows Presentation Foundation (WPF) visual layer supports hit testing against all objects under a point or geometry, not just the top-most object. Results are returned in z-order. However, the visual object that you pass as the parameter to the <xref:System.Windows.Media.VisualTreeHelper.HitTest%2A> method determines which portion of the visual tree that will be hit test. You can hit test against the entire visual tree, or any portion of it.
In the following illustration, the circle object is on top of both the square and triangle objects. If you are only interested in hit testing the visual object whose z-order value is top-most, you can set the visual hit test enumeration to return <xref:System.Windows.Media.HitTestResultBehavior.Stop> from the <xref:System.Windows.Media.HitTestResultCallback> to stop the hit test traversal after the first item.
@@ -15,7 +15,7 @@ This example shows how to use a <xref:System.Windows.Media.Animation.Storyboard>
The type of property determines the type of animation to use. For example, to animate a property that takes <xref:System.Double> values, use a <xref:System.Windows.Media.Animation.DoubleAnimation>. The <xref:System.Windows.Media.Animation.Storyboard.TargetName%2A> and <xref:System.Windows.Media.Animation.Storyboard.TargetProperty> attached properties specify the object and property to which the animation is applied.
To start a storyboard in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], use a <xref:System.Windows.Media.Animation.BeginStoryboard> action and an <xref:System.Windows.EventTrigger>. The <xref:System.Windows.EventTrigger> begins the <xref:System.Windows.Media.Animation.BeginStoryboard> action when the event that is specified by its <xref:System.Windows.EventTrigger.RoutedEvent%2A> property occurs. The <xref:System.Windows.Media.Animation.BeginStoryboard> action starts the <xref:System.Windows.Media.Animation.Storyboard>.
To start a storyboard in Extensible Application Markup Language (XAML), use a <xref:System.Windows.Media.Animation.BeginStoryboard> action and an <xref:System.Windows.EventTrigger>. The <xref:System.Windows.EventTrigger> begins the <xref:System.Windows.Media.Animation.BeginStoryboard> action when the event that is specified by its <xref:System.Windows.EventTrigger.RoutedEvent%2A> property occurs. The <xref:System.Windows.Media.Animation.BeginStoryboard> action starts the <xref:System.Windows.Media.Animation.Storyboard>.
The following example uses <xref:System.Windows.Media.Animation.Storyboard> objects to animate two <xref:System.Windows.Controls.Button> controls. To make the first button change in size, its <xref:System.Windows.FrameworkElement.Width%2A> is animated. To make the second button change color, the <xref:System.Windows.Media.SolidColorBrush.Color%2A> property of the <xref:System.Windows.Media.SolidColorBrush> is used to set the <xref:System.Windows.Controls.Control.Background%2A> of the button that is animated.
@@ -15,7 +15,7 @@ ms.assetid: d411db70-4df7-487d-82bc-95a7c1b2e7f8
This example shows one way to apply an animation to a property without using a <xref:System.Windows.Media.Animation.Storyboard>.
> [!NOTE]
> This functionality is not available in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. For information about animating a property in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], see [Animate a Property by Using a Storyboard](how-to-animate-a-property-by-using-a-storyboard.md).
> This functionality is not available in XAML, see [Animate a Property by Using a Storyboard](how-to-animate-a-property-by-using-a-storyboard.md).
To apply a local animation to a property, use the <xref:System.Windows.UIElement.BeginAnimation%2A> method. This method takes two parameters: a <xref:System.Windows.DependencyProperty> that specifies the property to animate, and the animation to apply to that property.
@@ -21,7 +21,7 @@ This example shows how to control a <xref:System.Windows.Controls.MediaElement>
This example shows how to create a simple media player that uses a <xref:System.Windows.Media.MediaTimeline> to control playback. The media player includes play, pause, resume, and stop buttons. The player also has a <xref:System.Windows.Controls.Slider> control that acts as a progress bar.
The following example creates the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] for the media player.
The following example creates the user interface (UI) for the media player.
[!code-xaml[MediaGallery_snip#MediaTimelineExampleWholePage](~/samples/snippets/visualbasic/VS_Snippets_Wpf/MediaGallery_snip/VB/MediaTimelineExample.xaml#mediatimelineexamplewholepage)]
@@ -10,7 +10,7 @@ ms.assetid: 040f13f0-69f9-4ab5-be2b-079f4f80c7c0
---
# How to: Control a Storyboard After It Starts
This example shows how to use code to control a <xref:System.Windows.Media.Animation.Storyboard> after it has started. To control a storyboard in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], use <xref:System.Windows.Trigger> and <xref:System.Windows.TriggerAction> objects; for an example, see [Use Event Triggers to Control a Storyboard After It Starts](how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md).
This example shows how to use code to control a <xref:System.Windows.Media.Animation.Storyboard> after it has started. To control a storyboard in XAML, use <xref:System.Windows.Trigger> and <xref:System.Windows.TriggerAction> objects; for an example, see [Use Event Triggers to Control a Storyboard After It Starts](how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md).
To start a storyboard, you use its <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method, which distributes the storyboard's animations to the properties they animate and starts the storyboard.
@@ -33,7 +33,7 @@ To make a storyboard controllable, you use the <xref:System.Windows.Media.Animat
In the following example, several storyboard methods are used to interactively control a storyboard.
> [!NOTE]
> To see an example of controlling a storyboard using triggers with [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], see [Use Event Triggers to Control a Storyboard After It Starts](how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md).
> To see an example of controlling a storyboard using triggers with XAML, see [Use Event Triggers to Control a Storyboard After It Starts](how-to-use-event-triggers-to-control-a-storyboard-after-it-starts.md).
## Example
@@ -13,11 +13,11 @@ This example shows how to create a cubic Bezier curve. To create a cubic Bezier
## Example
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you may use abbreviated markup syntax to describe a path.
In Extensible Application Markup Language (XAML), you may use abbreviated markup syntax to describe a path.
[!code-xaml[GeometrySample#53](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/geometryattributesyntaxexample.xaml#53)]
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can also draw a cubic Bezier curve using object tags. The following is equivalent to the previous [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example.
In XAML, you can also draw a cubic Bezier curve using object tags. The following is equivalent to the previous XAML example.
[!code-xaml[GeometrySample#33](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/pathgeometryexample.xaml#33)]
@@ -21,7 +21,7 @@ The following examples draw a <xref:System.Windows.Media.LineSegment> from (10,
![A LineSegment in a PathFigure](./media/graphicsmm-pathgeometrylinesegment.png "graphicsmm_pathgeometrylinesegment")
A LineSegment drawn from (10,50) to (200,70)
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you may use attribute syntax to describe a path.
In Extensible Application Markup Language (XAML), you may use attribute syntax to describe a path.
```xaml
<Path Stroke="Black" StrokeThickness="1"
@@ -30,7 +30,7 @@ In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you may u
(Note that this attribute syntax actually creates a <xref:System.Windows.Media.StreamGeometry>, a lighter-weight version of a <xref:System.Windows.Media.PathGeometry>. For more information, see the [Path Markup Syntax](path-markup-syntax.md) page.)
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you may also draw a line segment by using object element syntax. The following is equivalent to the previous [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example.
In XAML, you may also draw a line segment by using object element syntax. The following is equivalent to the previous XAML example.
```xaml
<Path Stroke="Black" StrokeThickness="1">
@@ -13,13 +13,13 @@ This example shows how to create a quadratic Bezier curve. To create a quadrati
## Example
In the following examples, a quadratic Bezier curve is drawn from (10,100) to (300,100). The curve has a control point of (200,200).
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can use attribute syntax to describe a path.
In Extensible Application Markup Language (XAML), you can use attribute syntax to describe a path.
[!code-xaml[GeometrySample#54](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/geometryattributesyntaxexample.xaml#54)]
(Note that this attribute syntax actually creates a <xref:System.Windows.Media.StreamGeometry>, a lighter-weight version of a <xref:System.Windows.Media.PathGeometry>. For more information, see the [Path Markup Syntax](path-markup-syntax.md) page.)
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you may also draw a quadratic Bezier curve using object element syntax. The following is equivalent to the previous [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example.
In XAML, you may also draw a quadratic Bezier curve using object element syntax. The following is equivalent to the previous XAML example.
[!code-xaml[GeometrySample#34](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/pathgeometryexample.xaml#34)]
@@ -15,7 +15,7 @@ ms.assetid: 08f7c8ce-074b-49cd-9aba-cc9592d4ee51
<xref:System.Windows.Media.StreamGeometry> is lightweight alternative to <xref:System.Windows.Media.PathGeometry> for creating geometric shapes. Use a <xref:System.Windows.Media.StreamGeometry> when you need to describe a complex geometry but do not want the overhead of supporting data binding, animation, or modification. For example, because of its efficiency, the <xref:System.Windows.Media.StreamGeometry> class is a good choice for describing adorners.
## Create a triangular StreamGeometry
The following example uses attribute syntax to create a triangular <xref:System.Windows.Media.StreamGeometry> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
The following example uses attribute syntax to create a triangular <xref:System.Windows.Media.StreamGeometry> in XAML.
[!code-xaml[GeometriesMiscSnippets_snip#StreamGeometryTriangleExampleWholePage](~/samples/snippets/xaml/VS_Snippets_Wpf/GeometriesMiscSnippets_snip/XAML/StreamGeometryExample.xaml#streamgeometrytriangleexamplewholepage)]
@@ -13,13 +13,13 @@ This example shows how to draw an elliptical arc. To create an elliptical arc, u
## Example
In the following examples, an elliptical arc is drawn from (10,100) to (200,100). The arc has a <xref:System.Windows.Media.ArcSegment.Size%2A> of 100 by 50 device-independent pixels, a <xref:System.Windows.Media.ArcSegment.RotationAngle%2A> of 45 degrees, an <xref:System.Windows.Media.ArcSegment.IsLargeArc%2A> setting of `true`, and a <xref:System.Windows.Media.ArcSegment.SweepDirection%2A> of <xref:System.Windows.Media.SweepDirection.Counterclockwise>.
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can use attribute syntax to describe a path.
In Extensible Application Markup Language (XAML), you can use attribute syntax to describe a path.
[!code-xaml[GeometrySample#56](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/geometryattributesyntaxexample.xaml#56)]
(Note that this attribute syntax actually creates a <xref:System.Windows.Media.StreamGeometry>, a lighter-weight version of a <xref:System.Windows.Media.PathGeometry>. For more information, see the [Path Markup Syntax](path-markup-syntax.md) page.)
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can also draw an elliptical arc by explicitly using object tags. The following is equivalent to the preceding [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup.
In XAML, you can also draw an elliptical arc by explicitly using object tags. The following is equivalent to the preceding XAML markup.
[!code-xaml[GeometrySample#36](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/pathgeometryexample.xaml#36)]
@@ -15,7 +15,7 @@ This example shows how to create multiple subpaths in a <xref:System.Windows.Med
[!code-xaml[GeometrySample#38](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/pathgeometryexample.xaml#38)]
The following example shows how to create multiple subpaths by using a <xref:System.Windows.Shapes.Path> and [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attribute syntax. Each `M` creates a new subpath so that the example creates two subpaths that each draw a triangle.
The following example shows how to create multiple subpaths by using a <xref:System.Windows.Shapes.Path> and XAML attribute syntax. Each `M` creates a new subpath so that the example creates two subpaths that each draw a triangle.
[!code-xaml[GeometrySample#58](~/samples/snippets/csharp/VS_Snippets_Wpf/GeometrySample/CS/geometryattributesyntaxexample.xaml#58)]
@@ -12,7 +12,7 @@ ms.assetid: 4b0ca008-29ce-48dd-8bc3-f3a20ffca6a6
This example shows how to draw a closed shape by using the <xref:System.Windows.Shapes.Polygon> element. To draw a closed shape, create a <xref:System.Windows.Shapes.Polygon> element and use its <xref:System.Windows.Shapes.Polygon.Points%2A> property to specify the vertices of a shape. A line is automatically drawn that connects the first and last points. Finally, specify a <xref:System.Windows.Shapes.Shape.Fill%2A>, a <xref:System.Windows.Shapes.Shape.Stroke%2A>, or both.
## Example
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], valid syntax for points is a space-delimited list of comma-separated x- and y-coordinate pairs.
In Extensible Application Markup Language (XAML), valid syntax for points is a space-delimited list of comma-separated x- and y-coordinate pairs.
[!code-xaml[drawingwithshapeelements#PolygonExample1](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingWithShapeElements/CS/polygonexample.xaml#polygonexample1)]
@@ -20,7 +20,7 @@ This example shows how to draw a polyline, which is a series of connected lines,
The following example draws two <xref:System.Windows.Shapes.Polyline> elements inside a <xref:System.Windows.Controls.Canvas>.
## Example
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], valid syntax for points is a space-delimited list of comma-separated x- and y-coordinate pairs.
In Extensible Application Markup Language (XAML), valid syntax for points is a space-delimited list of comma-separated x- and y-coordinate pairs.
[!code-xaml[drawingwithshapeelements#PolylineExample1](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingWithShapeElements/CS/polylineexample.xaml#polylineexample1)]
@@ -24,7 +24,7 @@ You can create visual objects within a Win32 window by providing a host window c
[!code-csharp[VisualsHitTesting#104](~/samples/snippets/csharp/VS_Snippets_Wpf/VisualsHitTesting/CSharp/MyCircle.cs#104)]
[!code-vb[VisualsHitTesting#104](~/samples/snippets/visualbasic/VS_Snippets_Wpf/VisualsHitTesting/VisualBasic/MyCircle.vb#104)]
The <xref:System.Windows.Interop.HwndSource> object presents [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] content within a Win32 window. The value of the <xref:System.Windows.Interop.HwndSource.RootVisual%2A> property of the <xref:System.Windows.Interop.HwndSource> object represents the top-most node in the visual tree hierarchy.
The <xref:System.Windows.Interop.HwndSource> object presents Windows Presentation Foundation (WPF) content within a Win32 window. The value of the <xref:System.Windows.Interop.HwndSource.RootVisual%2A> property of the <xref:System.Windows.Interop.HwndSource> object represents the top-most node in the visual tree hierarchy.
For the complete sample on hit testing objects using a Win32 host container, see [Hit Test with Win32 Interoperation Sample](https://github.com/microsoft/WPF-Samples/tree/master/Visual%20Layer/VisualsHitTesting).
@@ -16,7 +16,7 @@ ms.assetid: 02e055a0-54df-499a-b8b6-ab6ff7535cff
The following examples show how to load an <xref:System.Windows.Controls.Image> as a thumbnail to conserve application memory.
## Set the DecodePixelWidth property in XAML
The following example sets the <xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A> property of a <xref:System.Windows.Media.Imaging.BitmapImage> in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to reduce the memory required to load the image.
The following example sets the <xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A> property of a <xref:System.Windows.Media.Imaging.BitmapImage> in Extensible Application Markup Language (XAML) to reduce the memory required to load the image.
[!code-xaml[ImageElementExample_snip#ImageSimpleExampleInlineMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/ImageElementExample_snip/CSharp/ImageSimpleExample.xaml#imagesimpleexampleinlinemarkup)]
@@ -11,7 +11,7 @@ ms.assetid: 701246cd-66b7-4d69-ada9-17b3b433d95d
---
# How to: Render on a Per Frame Interval Using CompositionTarget
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation engine provides many features for creating frame-based animation. However, there are application scenarios in which you need finer-grained control over rendering on a per frame basis. The <xref:System.Windows.Media.CompositionTarget> object provides the ability to create custom animations based on a per-frame callback.
The WPF animation engine provides many features for creating frame-based animation. However, there are application scenarios in which you need finer-grained control over rendering on a per frame basis. The <xref:System.Windows.Media.CompositionTarget> object provides the ability to create custom animations based on a per-frame callback.
<xref:System.Windows.Media.CompositionTarget> is a static class which represents the display surface on which your application is being drawn. The <xref:System.Windows.Media.CompositionTarget.Rendering> event is raised each time the application's scene is drawn. The rendering frame rate is the number of times the scene is drawn per second.
@@ -20,19 +20,19 @@ The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md
## Example
The <xref:System.Windows.Media.CompositionTarget.Rendering> event fires during the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering process. The following example shows how you register an <xref:System.EventHandler> delegate to the static <xref:System.Windows.Media.CompositionTarget.Rendering> method on <xref:System.Windows.Media.CompositionTarget>.
The <xref:System.Windows.Media.CompositionTarget.Rendering> event fires during the WPF rendering process. The following example shows how you register an <xref:System.EventHandler> delegate to the static <xref:System.Windows.Media.CompositionTarget.Rendering> method on <xref:System.Windows.Media.CompositionTarget>.
[!code-csharp[CompositionTargetSample#CompositionTarget1](~/samples/snippets/csharp/VS_Snippets_Wpf/CompositionTargetSample/CSharp/Window1.xaml.cs#compositiontarget1)]
[!code-vb[CompositionTargetSample#CompositionTarget1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CompositionTargetSample/visualbasic/window1.xaml.vb#compositiontarget1)]
You can use your rendering event handler method to create custom drawing content. This event handler method gets called once per frame. Each time that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] marshals the persisted rendering data in the visual tree across to the composition scene graph, your event handler method is called. In addition, if changes to the visual tree force updates to the composition scene graph, your event handler method is also called. Note that your event handler method is called after layout has been computed. However, you can modify layout in your event handler method, which means that layout will be computed once more before rendering.
You can use your rendering event handler method to create custom drawing content. This event handler method gets called once per frame. Each time that WPF marshals the persisted rendering data in the visual tree across to the composition scene graph, your event handler method is called. In addition, if changes to the visual tree force updates to the composition scene graph, your event handler method is also called. Note that your event handler method is called after layout has been computed. However, you can modify layout in your event handler method, which means that layout will be computed once more before rendering.
The following example shows how you can provide custom drawing in a <xref:System.Windows.Media.CompositionTarget> event handler method. In this case, the background color of the <xref:System.Windows.Controls.Canvas> is drawn with a color value based on the coordinate position of the mouse. If you move the mouse inside the <xref:System.Windows.Controls.Canvas>, its background color changes. In addition, the average frame rate is calculated, based on the current elapsed time and the total number of rendered frames.
[!code-csharp[CompositionTargetSample#CompositionTarget2](~/samples/snippets/csharp/VS_Snippets_Wpf/CompositionTargetSample/CSharp/Window1.xaml.cs#compositiontarget2)]
[!code-vb[CompositionTargetSample#CompositionTarget2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CompositionTargetSample/visualbasic/window1.xaml.vb#compositiontarget2)]
You may discover that your custom drawing runs at different speeds on different computers. This is because your custom drawing is not frame-rate independent. Depending on the system you are running and the workload of that system, the <xref:System.Windows.Media.CompositionTarget.Rendering> event may be called a different number of times per second. For information on determining the graphics hardware capability and performance for a device that runs a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application, see [Graphics Rendering Tiers](../advanced/graphics-rendering-tiers.md).
You may discover that your custom drawing runs at different speeds on different computers. This is because your custom drawing is not frame-rate independent. Depending on the system you are running and the workload of that system, the <xref:System.Windows.Media.CompositionTarget.Rendering> event may be called a different number of times per second. For information on determining the graphics hardware capability and performance for a device that runs a WPF application, see [Graphics Rendering Tiers](../advanced/graphics-rendering-tiers.md).
Adding or removing a rendering <xref:System.EventHandler> delegate while the event is firing will be delayed until after the event is finished firing. This is consistent with how <xref:System.MulticastDelegate>-based events are handled in the Common Language Runtime (CLR). Also note that rendering events are not guaranteed to be called in any particular order. If you have multiple <xref:System.EventHandler> delegates that rely on a particular order, you should register a single <xref:System.Windows.Media.CompositionTarget.Rendering> event and multiplex the delegates in the correct order yourself.
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 5a5733aa-396d-4d72-b0c3-77f8c25d9a42
---
# How to: Use a BitmapImage
This example shows how to use a <xref:System.Windows.Media.Imaging.BitmapImage> as the source of an <xref:System.Windows.Controls.Image> control in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
This example shows how to use a <xref:System.Windows.Media.Imaging.BitmapImage> as the source of an <xref:System.Windows.Controls.Image> control in Extensible Application Markup Language (XAML).
## Example
[!code-xaml[ImageElementExample_snip#ImageSimpleExampleInlineMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/ImageElementExample_snip/CSharp/ImageSimpleExample.xaml#imagesimpleexampleinlinemarkup)]
@@ -9,7 +9,7 @@ ms.assetid: 3b115594-6a93-4972-b24d-61aa16f1c15f
---
# How to: Use Event Triggers to Control a Storyboard After It Starts
This example shows how to control a <xref:System.Windows.Media.Animation.Storyboard> after it starts. To start a <xref:System.Windows.Media.Animation.Storyboard> by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], use <xref:System.Windows.Media.Animation.BeginStoryboard>, which distributes the animations to the objects and properties they animate and then starts the storyboard. If you give <xref:System.Windows.Media.Animation.BeginStoryboard> a name by specifying its <xref:System.Windows.Media.Animation.BeginStoryboard.Name%2A> property, you make it a controllable storyboard. You can then interactively control the storyboard after it starts.
This example shows how to control a <xref:System.Windows.Media.Animation.Storyboard> after it starts. To start a <xref:System.Windows.Media.Animation.Storyboard> by using XAML, use <xref:System.Windows.Media.Animation.BeginStoryboard>, which distributes the animations to the objects and properties they animate and then starts the storyboard. If you give <xref:System.Windows.Media.Animation.BeginStoryboard> a name by specifying its <xref:System.Windows.Media.Animation.BeginStoryboard.Name%2A> property, you make it a controllable storyboard. You can then interactively control the storyboard after it starts.
Use the following storyboard actions together with <xref:System.Windows.EventTrigger> objects to control a storyboard.
@@ -11,7 +11,7 @@ helpviewer_keywords:
ms.assetid: 2fe21d59-b444-4786-b68d-35d94e18ce0d
---
# Images
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides built-in support for multiple image formats, high fidelity image rendering, and codec extensibility.
Windows Presentation Foundation (WPF) provides built-in support for multiple image formats, high fidelity image rendering, and codec extensibility.
## In This Section
[Imaging Overview](imaging-overview.md)
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 96834ee4-a5fc-4dd0-9948-b9bbc9437a5c
---
# Imaging How-to Topics
The topics in this section demonstrate how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] in order to display or alter bitmap images.
The topics in this section demonstrate how to use Windows Presentation Foundation (WPF) in order to display or alter bitmap images.
## In This Section
[Use a BitmapImage in XAML](how-to-use-a-bitmapimage.md)
@@ -44,7 +44,7 @@ This topic provides an introduction to the Microsoft Windows Presentation Founda
- Support for in-file, proprietary metadata.
- The managed component utilizes the unmanaged infrastructure to provide seamless integration of images with other WPF features such as [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], animation, and graphics. The managed component also benefits from the Windows Presentation Foundation (WPF) imaging codec extensibility model which enables automatic recognition of new image formats in WPF applications.
- The managed component utilizes the unmanaged infrastructure to provide seamless integration of images with other WPF features such as user interface (UI), animation, and graphics. The managed component also benefits from the Windows Presentation Foundation (WPF) imaging codec extensibility model which enables automatic recognition of new image formats in WPF applications.
The majority of the managed WPF Imaging API reside in the <xref:System.Windows.Media.Imaging?displayProperty=nameWithType> namespace, though several important types, such as <xref:System.Windows.Media.ImageBrush> and <xref:System.Windows.Media.ImageDrawing> reside in the <xref:System.Windows.Media?displayProperty=nameWithType> namespace and <xref:System.Windows.Controls.Image> resides in the <xref:System.Windows.Controls?displayProperty=nameWithType> namespace.
@@ -93,11 +93,11 @@ This topic provides an introduction to the Microsoft Windows Presentation Founda
### Using the Image Control
<xref:System.Windows.Controls.Image> is a framework element and the primary way to display images in applications. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], <xref:System.Windows.Controls.Image> can be used in two ways; attribute syntax or property syntax. The following example shows how to render an image 200 pixels wide using both attribute syntax and property tag syntax. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md).
<xref:System.Windows.Controls.Image> is a framework element and the primary way to display images in applications. In XAML, <xref:System.Windows.Controls.Image> can be used in two ways; attribute syntax or property syntax. The following example shows how to render an image 200 pixels wide using both attribute syntax and property tag syntax. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md).
[!code-xaml[ImageElementExample_snip#ImageSimpleExampleInlineMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/ImageElementExample_snip/CSharp/ImageSimpleExample.xaml#imagesimpleexampleinlinemarkup)]
Many of the examples use a <xref:System.Windows.Media.Imaging.BitmapImage> object to reference an image file. <xref:System.Windows.Media.Imaging.BitmapImage> is a specialized <xref:System.Windows.Media.Imaging.BitmapSource> that is optimized for [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] loading and is an easy way to display images as the <xref:System.Windows.Controls.Image.Source%2A> of an <xref:System.Windows.Controls.Image> control.
Many of the examples use a <xref:System.Windows.Media.Imaging.BitmapImage> object to reference an image file. <xref:System.Windows.Media.Imaging.BitmapImage> is a specialized <xref:System.Windows.Media.Imaging.BitmapSource> that is optimized for Extensible Application Markup Language (XAML) loading and is an easy way to display images as the <xref:System.Windows.Controls.Image.Source%2A> of an <xref:System.Windows.Controls.Image> control.
The following example shows how to render an image 200 pixels wide using code.
@@ -155,7 +155,7 @@ Different stretch settings
### Painting with Images
Images can also be displayed in an application by painting with a <xref:System.Windows.Media.Brush>. Brushes enable you to paint [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] objects with anything from simple, solid colors to complex sets of patterns and images. To paint with images, use an <xref:System.Windows.Media.ImageBrush>. An <xref:System.Windows.Media.ImageBrush> is a type of <xref:System.Windows.Media.TileBrush> that defines its content as a bitmap image. An <xref:System.Windows.Media.ImageBrush> displays a single image, which is specified by its <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property. You can control how the image is stretched, aligned, and tiled, enabling you to prevent distortion and produce patterns and other effects. The following illustration shows some effects that can be achieved with an <xref:System.Windows.Media.ImageBrush>.
Images can also be displayed in an application by painting with a <xref:System.Windows.Media.Brush>. Brushes enable you to paint UI objects with anything from simple, solid colors to complex sets of patterns and images. To paint with images, use an <xref:System.Windows.Media.ImageBrush>. An <xref:System.Windows.Media.ImageBrush> is a type of <xref:System.Windows.Media.TileBrush> that defines its content as a bitmap image. An <xref:System.Windows.Media.ImageBrush> displays a single image, which is specified by its <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property. You can control how the image is stretched, aligned, and tiled, enabling you to prevent distortion and produce patterns and other effects. The following illustration shows some effects that can be achieved with an <xref:System.Windows.Media.ImageBrush>.
![ImageBrush output examples](./media/wcpsdk-mmgraphics-imagebrushexamples.gif "wcpsdk_mmgraphics_imagebrushexamples")
Image brushes can fill shapes, controls, text, and more
@@ -17,9 +17,9 @@ ms.assetid: 1817d9dc-3d6c-46cb-afc8-63b0bae35e37
# Graphics and Multimedia
<a name="introduction"></a>
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides support for multimedia, vector graphics, animation, and content composition, making it easy for developers to build interesting user interfaces and content. Using Visual Studio, you can create vector graphics or complex animations and integrate media into your applications.
Windows Presentation Foundation (WPF) provides support for multimedia, vector graphics, animation, and content composition, making it easy for developers to build interesting user interfaces and content. Using Visual Studio, you can create vector graphics or complex animations and integrate media into your applications.
This topic introduces the graphics, animation, and media features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], which enable you to add graphics, transition effects, sound, and video to your applications.
This topic introduces the graphics, animation, and media features of WPF, which enable you to add graphics, transition effects, sound, and video to your applications.
> [!NOTE]
> Using WPF types in a Windows service is strongly discouraged. If you attempt to use WPF types in a Windows service, the service may not work as expected.
@@ -88,7 +88,7 @@ Partial Public Class Window1
End Class
```
The following illustration shows the output for the preceding [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup and code-behind.
The following illustration shows the output for the preceding XAML markup and code-behind.
![A message box saying "You clicked the ellipse!"](./media/index/messagebox-text-output.png)
@@ -104,7 +104,7 @@ For more information, see [Geometry Overview](geometry-overview.md). For an intr
### 2D Effects
WPF provides a library of 2D classes that you can use to create a variety of effects. The 2D rendering capability of WPF provides the ability to paint [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements that have gradients, bitmaps, drawings, and videos; and to manipulate them by using rotation, scaling, and skewing. The following illustration gives an example of the many effects you can achieve by using WPF brushes.
WPF provides a library of 2D classes that you can use to create a variety of effects. The 2D rendering capability of WPF provides the ability to paint UI elements that have gradients, bitmaps, drawings, and videos; and to manipulate them by using rotation, scaling, and skewing. The following illustration gives an example of the many effects you can achieve by using WPF brushes.
![Illustration showing the different WPF brushes and paint elements.](./media/index/brushes-paint-elements.png)
@@ -114,7 +114,7 @@ For more information, see [WPF Brushes Overview](wpf-brushes-overview.md). For a
## 3D Rendering
WPF provides a set of 3D rendering capabilities that integrate with 2D graphics support in WPF in order for you to create more exciting layout, [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], and data visualization. At one end of the spectrum, WPF enables you to render 2D images onto the surfaces of 3D shapes, which the following illustration demonstrates.
WPF provides a set of 3D rendering capabilities that integrate with 2D graphics support in WPF in order for you to create more exciting layout, UI, and data visualization. At one end of the spectrum, WPF enables you to render 2D images onto the surfaces of 3D shapes, which the following illustration demonstrates.
![Screenshot of a sample showing 3D shapes with different textures.](./media/index/visual-three-dimensional-shape.png)
@@ -12,7 +12,7 @@ This topic introduces you to key-frame animations. Key-frame animations enable y
<a name="prerequisites"></a>
## Prerequisites
To understand this overview, you should be familiar with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] animations and timelines. For an introduction to animations, see the [Animation Overview](animation-overview.md). It also helps to be familiar with From/To/By animations. For more information, see the From/To/By Animations Overview.
To understand this overview, you should be familiar with Windows Presentation Foundation (WPF) animations and timelines. For an introduction to animations, see the [Animation Overview](animation-overview.md). It also helps to be familiar with From/To/By animations. For more information, see the From/To/By Animations Overview.
<a name="whatisakeyframeanimation"></a>
## What is a Key-Frame Animation?
@@ -44,7 +44,7 @@ This topic introduces you to key-frame animations. Key-frame animations enable y
Where *\<Type>* is the type of value that the class animates.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides the following key-frame animation classes.
WPF provides the following key-frame animation classes.
|Property type|Corresponding from/to/by animation class|Interpolation methods supported|
|-------------------|------------------------------------------------|-------------------------------------|
@@ -166,7 +166,7 @@ A key spline with control points (0.0, 1.0) and (1.0, 0.0)
The following example specifies a <xref:System.Windows.Media.Animation.KeySpline> of 0.5,0.25 0.75,1.0, which creates the following Bezier curve.
![A Bezier curve](./media/graphicsmm-keyspline-025-050-075-10.png "graphicsmm_keyspline_025_050_075_10")
![A second Bezier curve example.](./media/graphicsmm-keyspline-025-050-075-10.png "graphicsmm_keyspline_025_050_075_10")
A key spline with control points (0.25, 0.5) and (0.75, 1.0)
[!code-xaml[keyframes_ovw_snippet#SingleSplineKeyFrameExampleInline3](~/samples/snippets/csharp/VS_Snippets_Wpf/keyframes_ovw_snippet/CS/InterpolationMethodsExample.xaml#singlesplinekeyframeexampleinline3)]
@@ -209,7 +209,7 @@ A key spline with control points (0.25, 0.5) and (0.75, 1.0)
[!code-xaml[keyframes_ovw_snippet#TimeSpanKeyTimeExample](~/samples/snippets/csharp/VS_Snippets_Wpf/keyframes_ovw_snippet/CS/KeyTimesExample.xaml#timespankeytimeexample)]
### Percentage Values
A percentage value specifies that the key frame ends at some percentage of the animation's <xref:System.Windows.Media.Animation.Timeline.Duration%2A>. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you specify the percentage as a number followed by the `%` symbol. In code, you use the <xref:System.Windows.Media.Animation.KeyTime.FromPercent%2A> method and pass it a <xref:System.Double> indicating the percentage. The value must be greater than or equal to 0 and less than or equal to 100 percent. The following example shows an animation with a duration of 10 seconds and four key frames whose key times are specified as percentages.
A percentage value specifies that the key frame ends at some percentage of the animation's <xref:System.Windows.Media.Animation.Timeline.Duration%2A>. In XAML, you specify the percentage as a number followed by the `%` symbol. In code, you use the <xref:System.Windows.Media.Animation.KeyTime.FromPercent%2A> method and pass it a <xref:System.Double> indicating the percentage. The value must be greater than or equal to 0 and less than or equal to 100 percent. The following example shows an animation with a duration of 10 seconds and four key frames whose key times are specified as percentages.
- The first key frame animates from the base value to 100 over the first 3 seconds, ending at time = 0:0:3.
@@ -6,19 +6,19 @@ helpviewer_keywords:
ms.assetid: 4bcf949d-d92f-4d8d-8a9b-1e4c61b25bf6
---
# Maximize WPF 3D Performance
As you use the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to build 3D controls and include 3D scenes in your applications, it is important to consider performance optimization. This topic provides a list of 3D classes and properties that have performance implications for your application, along with recommendations for optimizing performance when you use them.
As you use the Windows Presentation Foundation (WPF) to build 3D controls and include 3D scenes in your applications, it is important to consider performance optimization. This topic provides a list of 3D classes and properties that have performance implications for your application, along with recommendations for optimizing performance when you use them.
This topic assumes an advanced understanding of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 3D features. The suggestions in this document apply to "rendering tier 2"—roughly defined as hardware that supports pixel shader version 2.0 and vertex shader version 2.0. For more details, see [Graphics Rendering Tiers](../advanced/graphics-rendering-tiers.md).
This topic assumes an advanced understanding of Windows Presentation Foundation (WPF) 3D features. The suggestions in this document apply to "rendering tier 2"—roughly defined as hardware that supports pixel shader version 2.0 and vertex shader version 2.0. For more details, see [Graphics Rendering Tiers](../advanced/graphics-rendering-tiers.md).
## Performance Impact: High
|Property|Recommendation|
|-|-|
|<xref:System.Windows.Media.Brush>|Brush speed (fastest to slowest):<br /><br /> <xref:System.Windows.Media.SolidColorBrush><br /><br /> <xref:System.Windows.Media.LinearGradientBrush><br /><br /> <xref:System.Windows.Media.ImageBrush><br /><br /> <xref:System.Windows.Media.DrawingBrush> (cached)<br /><br /> <xref:System.Windows.Media.VisualBrush> (cached)<br /><br /> <xref:System.Windows.Media.RadialGradientBrush><br /><br /> <xref:System.Windows.Media.DrawingBrush> (uncached)<br /><br /> <xref:System.Windows.Media.VisualBrush> (uncached)|
|<xref:System.Windows.UIElement.ClipToBoundsProperty>|Set `Viewport3D.ClipToBounds` to false whenever you do not need to have [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] explicitly clip the content of a <xref:System.Windows.Controls.Viewport3D> to the Viewport3Ds rectangle. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] antialiased clipping can be very slow, and `ClipToBounds` is enabled (slow) by default on <xref:System.Windows.Controls.Viewport3D>.|
|<xref:System.Windows.UIElement.IsHitTestVisible%2A>|Set `Viewport3D.IsHitTestVisible` to false whenever you do not need [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to consider the content of a <xref:System.Windows.Controls.Viewport3D> when performing mouse hit testing. Hit testing 3D content is done in software and can be slow with large meshes. <xref:System.Windows.UIElement.IsHitTestVisible%2A> is enabled (slow) by default on <xref:System.Windows.Controls.Viewport3D>.|
|<xref:System.Windows.UIElement.ClipToBoundsProperty>|Set `Viewport3D.ClipToBounds` to false whenever you do not need to have Windows Presentation Foundation (WPF) explicitly clip the content of a <xref:System.Windows.Controls.Viewport3D> to the Viewport3Ds rectangle. Windows Presentation Foundation (WPF) antialiased clipping can be very slow, and `ClipToBounds` is enabled (slow) by default on <xref:System.Windows.Controls.Viewport3D>.|
|<xref:System.Windows.UIElement.IsHitTestVisible%2A>|Set `Viewport3D.IsHitTestVisible` to false whenever you do not need Windows Presentation Foundation (WPF) to consider the content of a <xref:System.Windows.Controls.Viewport3D> when performing mouse hit testing. Hit testing 3D content is done in software and can be slow with large meshes. <xref:System.Windows.UIElement.IsHitTestVisible%2A> is enabled (slow) by default on <xref:System.Windows.Controls.Viewport3D>.|
|<xref:System.Windows.Media.Media3D.GeometryModel3D>|Create different models only when they require different Materials or Transforms. Otherwise, try to coalesce many <xref:System.Windows.Media.Media3D.GeometryModel3D> instances with the same Materials and Transforms into a few larger <xref:System.Windows.Media.Media3D.GeometryModel3D> and <xref:System.Windows.Media.Media3D.MeshGeometry3D> instances.|
|<xref:System.Windows.Media.Media3D.MeshGeometry3D>|Mesh animation—changing the individual vertices of a mesh on a per-frame basis—is not always efficient in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. To minimize the performance impact of change notifications when each vertex is modified, detach the mesh from the visual tree before performing per-vertex modification. Once the mesh has been modified, reattach it to the visual tree. Also, try to minimize the size of meshes that will be animated in this way.|
|<xref:System.Windows.Media.Media3D.MeshGeometry3D>|Mesh animation—changing the individual vertices of a mesh on a per-frame basis—is not always efficient in Windows Presentation Foundation (WPF). To minimize the performance impact of change notifications when each vertex is modified, detach the mesh from the visual tree before performing per-vertex modification. Once the mesh has been modified, reattach it to the visual tree. Also, try to minimize the size of meshes that will be animated in this way.|
|3D Antialiasing|To increase rendering speed, disable multisampling on a <xref:System.Windows.Controls.Viewport3D> by setting the attached property <xref:System.Windows.Media.RenderOptions.EdgeMode%2A> to `Aliased`. By default, 3D antialiasing is enabled on Windows with 4 samples per pixel.|
|Text|Live text in a 3D scene (live because its in a <xref:System.Windows.Media.DrawingBrush> or <xref:System.Windows.Media.VisualBrush>) can be slow. Try to use images of the text instead (via <xref:System.Windows.Media.Imaging.RenderTargetBitmap>) unless the text will change.|
|<xref:System.Windows.Media.TileBrush>|If you must use a <xref:System.Windows.Media.VisualBrush> or a <xref:System.Windows.Media.DrawingBrush> in a 3D scene because the brushs content is not static, try caching the brush (setting the attached property <xref:System.Windows.Media.RenderOptions.CachingHint%2A> to `Cache`). Set the minimum and maximum scale invalidation thresholds (with the attached properties <xref:System.Windows.Media.RenderOptions.CacheInvalidationThresholdMinimum%2A> and <xref:System.Windows.Media.RenderOptions.CacheInvalidationThresholdMaximum%2A>) so that the cached brushes wont be regenerated too frequently, while still maintaining your desired level of quality. By default, <xref:System.Windows.Media.DrawingBrush> and <xref:System.Windows.Media.VisualBrush> are not cached, meaning that every time something painted with the brush has to be re-rendered, the entire content of the brush must first be re-rendered to an intermediate surface.|
@@ -39,7 +39,7 @@ As you use the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-wincli
|<xref:System.Windows.Media.Media3D.Light>|Light speed (fastest to slowest):<br /><br /> <xref:System.Windows.Media.Media3D.AmbientLight><br /><br /> <xref:System.Windows.Media.Media3D.DirectionalLight><br /><br /> <xref:System.Windows.Media.Media3D.PointLight><br /><br /> <xref:System.Windows.Media.Media3D.SpotLight>|
|<xref:System.Windows.Media.Media3D.MeshGeometry3D>|Try to keep mesh sizes under these limits:<br /><br /> <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A>: 20,001 <xref:System.Windows.Media.Media3D.Point3D> instances<br /><br /> <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A>: 60,003 <xref:System.Int32> instances|
|<xref:System.Windows.Media.Media3D.Material>|Material speed (fastest to slowest):<br /><br /> <xref:System.Windows.Media.Media3D.EmissiveMaterial><br /><br /> <xref:System.Windows.Media.Media3D.DiffuseMaterial><br /><br /> <xref:System.Windows.Media.Media3D.SpecularMaterial>|
|<xref:System.Windows.Media.Brush>|[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] 3D doesn't opt out of invisible brushes (black ambient brushes, clear brushes, etc.) in a consistent way. Consider omitting these from your scene.|
|<xref:System.Windows.Media.Brush>|Windows Presentation Foundation (WPF) 3D doesn't opt out of invisible brushes (black ambient brushes, clear brushes, etc.) in a consistent way. Consider omitting these from your scene.|
|<xref:System.Windows.Media.Media3D.MaterialGroup>|Each <xref:System.Windows.Media.Media3D.Material> in a <xref:System.Windows.Media.Media3D.MaterialGroup> causes another rendering pass, so including many materials, even simple materials, can dramatically increase the fill demands on your GPU. Minimize the number of materials in your <xref:System.Windows.Media.Media3D.MaterialGroup>.|
## Performance Impact: Low
@@ -47,11 +47,11 @@ As you use the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-wincli
|Property|Recommendation|
|-|-|
|<xref:System.Windows.Media.Media3D.Transform3DGroup>|When you dont need animation or data binding, instead of using a transform group containing multiple transforms, use a single <xref:System.Windows.Media.Media3D.MatrixTransform3D>, setting it to be the product of all the transforms that would otherwise exist independently in the transform group.|
|<xref:System.Windows.Media.Media3D.Light>|Minimize the number of lights in your scene. Too many lights in a scene will force [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to fall back to software rendering. The limits are roughly 110 <xref:System.Windows.Media.Media3D.DirectionalLight> objects, 70 <xref:System.Windows.Media.Media3D.PointLight> objects, or 40 <xref:System.Windows.Media.Media3D.SpotLight> objects.|
|<xref:System.Windows.Media.Media3D.Light>|Minimize the number of lights in your scene. Too many lights in a scene will force Windows Presentation Foundation (WPF) to fall back to software rendering. The limits are roughly 110 <xref:System.Windows.Media.Media3D.DirectionalLight> objects, 70 <xref:System.Windows.Media.Media3D.PointLight> objects, or 40 <xref:System.Windows.Media.Media3D.SpotLight> objects.|
|<xref:System.Windows.Media.Media3D.ModelVisual3D>|Separate moving objects from static objects by putting them in separate <xref:System.Windows.Media.Media3D.ModelVisual3D> instances. ModelVisual3D is "heavier" than <xref:System.Windows.Media.Media3D.GeometryModel3D> because it caches transformed bounds. GeometryModel3D is optimized to be a model; ModelVisual3D is optimized to be a scene node. Use ModelVisual3D to put shared instances of GeometryModel3D into the scene.|
|<xref:System.Windows.Media.Media3D.Light>|Minimize the number of times you change the number of lights in the scene. Each change of light count forces a shader regeneration and recompilation unless that configuration has existed previously (and thus had its shader cached).|
|Light|Black lights wont be visible, but they will add to render time; consider omitting them.|
|<xref:System.Windows.Media.Media3D.MeshGeometry3D>|To minimize the construction time of large collections in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], such as a MeshGeometry3Ds <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A>, <xref:System.Windows.Media.Media3D.MeshGeometry3D.Normals%2A>, <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A>, and <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A>, pre-size the collections before value population. If possible, pass the collections constructors prepopulated data structures such as arrays or Lists.|
|<xref:System.Windows.Media.Media3D.MeshGeometry3D>|To minimize the construction time of large collections in Windows Presentation Foundation (WPF), such as a MeshGeometry3Ds <xref:System.Windows.Media.Media3D.MeshGeometry3D.Positions%2A>, <xref:System.Windows.Media.Media3D.MeshGeometry3D.Normals%2A>, <xref:System.Windows.Media.Media3D.MeshGeometry3D.TextureCoordinates%2A>, and <xref:System.Windows.Media.Media3D.MeshGeometry3D.TriangleIndices%2A>, pre-size the collections before value population. If possible, pass the collections constructors prepopulated data structures such as arrays or Lists.|
## See also
@@ -7,13 +7,13 @@ helpviewer_keywords:
ms.assetid: feb25b15-d741-4ac3-818f-1b19f63a3562
---
# Multimedia Overview
The multimedia features in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] enable you to integrate audio and video into your applications to enhance the user experience. This topic introduces the multimedia features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
The multimedia features in WPF.
<a name="mediaapi"></a>
## Media API
The <xref:System.Windows.Controls.MediaElement> and <xref:System.Windows.Media.MediaPlayer> classes are used to present audio or video content. These classes can be controlled interactively or by a clock. These classes can use on the Microsoft Windows Media Player 10 control for media playback. Which class you use, depends on the scenario.
<xref:System.Windows.Controls.MediaElement> is a <xref:System.Windows.UIElement> that is supported by the [Layout](../advanced/layout.md) and can be consumed as the content of many controls. It is also usable in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] as well as code. <xref:System.Windows.Media.MediaPlayer>, on the other hand, is designed for <xref:System.Windows.Media.Drawing> objects and lacks layout support. Media loaded using a <xref:System.Windows.Media.MediaPlayer> can only be presented using a <xref:System.Windows.Media.VideoDrawing> or by directly interacting with a <xref:System.Windows.Media.DrawingContext>. <xref:System.Windows.Media.MediaPlayer> cannot be used in XAML.
<xref:System.Windows.Controls.MediaElement> is a <xref:System.Windows.UIElement> that is supported by the [Layout](../advanced/layout.md) and can be consumed as the content of many controls. It is also usable in Extensible Application Markup Language (XAML) as well as code. <xref:System.Windows.Media.MediaPlayer>, on the other hand, is designed for <xref:System.Windows.Media.Drawing> objects and lacks layout support. Media loaded using a <xref:System.Windows.Media.MediaPlayer> can only be presented using a <xref:System.Windows.Media.VideoDrawing> or by directly interacting with a <xref:System.Windows.Media.DrawingContext>. <xref:System.Windows.Media.MediaPlayer> cannot be used in XAML.
For more information about drawing objects and drawing context, see [Drawing Objects Overview](drawing-objects-overview.md).
@@ -26,7 +26,7 @@ The multimedia features in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasha
> [!NOTE]
> Both <xref:System.Windows.Controls.MediaElement> and <xref:System.Windows.Media.MediaPlayer> have similar members. The links in this section refer to the <xref:System.Windows.Controls.MediaElement> class members. Unless specifically noted, members linked to in the <xref:System.Windows.Controls.MediaElement> class can also be found in the <xref:System.Windows.Media.MediaPlayer> class.
To understand media playback in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], an understanding of the different modes in which media can be played is required. Both <xref:System.Windows.Controls.MediaElement> and <xref:System.Windows.Media.MediaPlayer> can be used in two different media modes, independent mode and clock mode. The media mode is determined by the <xref:System.Windows.Controls.MediaElement.Clock%2A> property. When <xref:System.Windows.Controls.MediaElement.Clock%2A> is `null`, the media object is in independent mode. When the <xref:System.Windows.Controls.MediaElement.Clock%2A> is non-null, the media object is in clock mode. By default, media objects are in independent mode.
To understand media playback in Windows Presentation Foundation (WPF), an understanding of the different modes in which media can be played is required. Both <xref:System.Windows.Controls.MediaElement> and <xref:System.Windows.Media.MediaPlayer> can be used in two different media modes, independent mode and clock mode. The media mode is determined by the <xref:System.Windows.Controls.MediaElement.Clock%2A> property. When <xref:System.Windows.Controls.MediaElement.Clock%2A> is `null`, the media object is in independent mode. When the <xref:System.Windows.Controls.MediaElement.Clock%2A> is non-null, the media object is in clock mode. By default, media objects are in independent mode.
### Independent Mode
In independent mode, the media content drives media playback. Independent mode enables the following options:
@@ -60,7 +60,7 @@ The multimedia features in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasha
<a name="mediaelement"></a>
## MediaElement Class
Adding media to an application is as simple as adding a <xref:System.Windows.Controls.MediaElement> control to the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] of the application and providing a <xref:System.Uri> to the media you wish to include. All media types supported by Microsoft Windows Media Player 10 are supported in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. The following example shows a simple usage of the <xref:System.Windows.Controls.MediaElement> in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
Adding media to an application is as simple as adding a <xref:System.Windows.Controls.MediaElement> control to the user interface (UI) of the application and providing a <xref:System.Uri> to the media you wish to include. All media types supported by Microsoft Windows Media Player 10 are supported in Windows Presentation Foundation (WPF). The following example shows a simple usage of the <xref:System.Windows.Controls.MediaElement> in Extensible Application Markup Language (XAML).
[!code-xaml[MediaElement_snip#SimpleMediaElementUsageWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/MediaElement_snip/CSharp/SimpleUsage.xaml#simplemediaelementusagewholepage)]
@@ -80,11 +80,11 @@ The multimedia features in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasha
4. Interactive control methods. In place when <xref:System.Windows.Controls.MediaElement.LoadedBehavior%2A> is <xref:System.Windows.Controls.MediaState.Manual>. The control methods available are <xref:System.Windows.Controls.MediaElement.Play%2A>, <xref:System.Windows.Controls.MediaElement.Pause%2A>, <xref:System.Windows.Controls.MediaElement.Close%2A>, and <xref:System.Windows.Controls.MediaElement.Stop%2A>.
### Displaying a MediaElement
To display a <xref:System.Windows.Controls.MediaElement> it must have content to render and it will have its <xref:System.Windows.FrameworkElement.ActualWidth%2A> and <xref:System.Windows.FrameworkElement.ActualHeight%2A> properties set to zero until content is loaded. For audio only content, these properties are always zero. For video content, once the <xref:System.Windows.Controls.MediaElement.MediaOpened> event has been raised the <xref:System.Windows.FrameworkElement.ActualWidth%2A> and <xref:System.Windows.FrameworkElement.ActualHeight%2A> will report the size of the loaded media. This means that until media is loaded, the <xref:System.Windows.Controls.MediaElement> will not take up any physical space in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] unless the <xref:System.Windows.FrameworkElement.Width%2A> or <xref:System.Windows.FrameworkElement.Height%2A> properties are set.
To display a <xref:System.Windows.Controls.MediaElement> it must have content to render and it will have its <xref:System.Windows.FrameworkElement.ActualWidth%2A> and <xref:System.Windows.FrameworkElement.ActualHeight%2A> properties set to zero until content is loaded. For audio only content, these properties are always zero. For video content, once the <xref:System.Windows.Controls.MediaElement.MediaOpened> event has been raised the <xref:System.Windows.FrameworkElement.ActualWidth%2A> and <xref:System.Windows.FrameworkElement.ActualHeight%2A> will report the size of the loaded media. This means that until media is loaded, the <xref:System.Windows.Controls.MediaElement> will not take up any physical space in the user interface (UI) unless the <xref:System.Windows.FrameworkElement.Width%2A> or <xref:System.Windows.FrameworkElement.Height%2A> properties are set.
Setting both the <xref:System.Windows.FrameworkElement.Width%2A> and <xref:System.Windows.FrameworkElement.Height%2A> properties will cause the media to stretch to fill the area provided for the <xref:System.Windows.Controls.MediaElement>. To preserve the media's original aspect ratio, either the <xref:System.Windows.FrameworkElement.Width%2A> or <xref:System.Windows.FrameworkElement.Height%2A> property should be set but not both. Setting both the <xref:System.Windows.FrameworkElement.Width%2A> and <xref:System.Windows.FrameworkElement.Height%2A> properties will cause the media to present in a fixed element size that may not be desirable.
To avoid having a fixed size element which, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] can preroll the media. This is done by setting the <xref:System.Windows.Controls.MediaElement.LoadedBehavior%2A> to either <xref:System.Windows.Controls.MediaState.Play> or <xref:System.Windows.Controls.MediaState.Pause>. In a <xref:System.Windows.Controls.MediaState.Pause> state, the media will preroll and will present the first frame. In a <xref:System.Windows.Controls.MediaState.Play> state, the media will preroll and begin to play.
To avoid having a fixed size element which, Windows Presentation Foundation (WPF) can preroll the media. This is done by setting the <xref:System.Windows.Controls.MediaElement.LoadedBehavior%2A> to either <xref:System.Windows.Controls.MediaState.Play> or <xref:System.Windows.Controls.MediaState.Pause>. In a <xref:System.Windows.Controls.MediaState.Pause> state, the media will preroll and will present the first frame. In a <xref:System.Windows.Controls.MediaState.Play> state, the media will preroll and begin to play.
<a name="mediaplayer"></a>
## MediaPlayer Class
@@ -67,7 +67,7 @@ DrawingBrush opacity masking example
<a name="argbsyntax"></a>
### Specifying Color Opacity in "XAML"
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you use ARGB hexadecimal notation to specify the opacity of individual colors. ARGB hexadecimal notation uses the following syntax:
In Extensible Application Markup Language (XAML), you use ARGB hexadecimal notation to specify the opacity of individual colors. ARGB hexadecimal notation uses the following syntax:
`#` **aa** *rrggbb*
@@ -18,13 +18,13 @@ This topic describes how to use <xref:System.Windows.Media.ImageBrush>, <xref:Sy
<a name="prereqs"></a>
## Prerequisites
To understand this topic, you should be familiar with the different types of brushes [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides and their basic features. For an introduction, see the [WPF Brushes Overview](wpf-brushes-overview.md).
To understand this topic, you should be familiar with the different types of brushes Windows Presentation Foundation (WPF) provides and their basic features. For an introduction, see the [WPF Brushes Overview](wpf-brushes-overview.md).
<a name="image"></a>
## Paint an Area with an Image
An <xref:System.Windows.Media.ImageBrush> paints an area with an <xref:System.Windows.Media.ImageSource>. The most common type of <xref:System.Windows.Media.ImageSource> to use with an <xref:System.Windows.Media.ImageBrush> is a <xref:System.Windows.Media.Imaging.BitmapImage>, which describes a bitmap graphic. You can use a <xref:System.Windows.Media.DrawingImage> to paint using a <xref:System.Windows.Media.Drawing> object, but it is simpler to use a <xref:System.Windows.Media.DrawingBrush> instead. For more information about <xref:System.Windows.Media.ImageSource> objects, see the [Imaging Overview](imaging-overview.md).
To paint with an <xref:System.Windows.Media.ImageBrush>, create a <xref:System.Windows.Media.Imaging.BitmapImage> and use it to load the bitmap content. Then, use the <xref:System.Windows.Media.Imaging.BitmapImage> to set the <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property of the <xref:System.Windows.Media.ImageBrush>. Finally, apply the <xref:System.Windows.Media.ImageBrush> to the object you want to paint. In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can also just set the <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property of the <xref:System.Windows.Media.ImageBrush> with the path of the image to load.
To paint with an <xref:System.Windows.Media.ImageBrush>, create a <xref:System.Windows.Media.Imaging.BitmapImage> and use it to load the bitmap content. Then, use the <xref:System.Windows.Media.Imaging.BitmapImage> to set the <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property of the <xref:System.Windows.Media.ImageBrush>. Finally, apply the <xref:System.Windows.Media.ImageBrush> to the object you want to paint. In Extensible Application Markup Language (XAML), you can also just set the <xref:System.Windows.Media.ImageBrush.ImageSource%2A> property of the <xref:System.Windows.Media.ImageBrush> with the path of the image to load.
Like all <xref:System.Windows.Media.Brush> objects, an <xref:System.Windows.Media.ImageBrush> can be used to paint objects such as shapes, panels, controls, and text. The following illustration shows some effects that can be achieved with an <xref:System.Windows.Media.ImageBrush>.
@@ -76,7 +76,7 @@ Objects painted by a DrawingBrush
<a name="visualbrushsection"></a>
## Paint an Area with a Visual
The most versatile and powerful of all the brushes, the <xref:System.Windows.Media.VisualBrush> paints an area with a <xref:System.Windows.Media.Visual>. A <xref:System.Windows.Media.Visual> is a low-level graphical type that serves as the ancestor of many useful graphical components. For example, the <xref:System.Windows.Window>, <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.Controls.Control> classes are all types of <xref:System.Windows.Media.Visual> objects. Using a <xref:System.Windows.Media.VisualBrush>, you can paint areas with almost any [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] graphical object.
The most versatile and powerful of all the brushes, the <xref:System.Windows.Media.VisualBrush> paints an area with a <xref:System.Windows.Media.Visual>. A <xref:System.Windows.Media.Visual> is a low-level graphical type that serves as the ancestor of many useful graphical components. For example, the <xref:System.Windows.Window>, <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.Controls.Control> classes are all types of <xref:System.Windows.Media.Visual> objects. Using a <xref:System.Windows.Media.VisualBrush>, you can paint areas with almost any Windows Presentation Foundation (WPF) graphical object.
> [!NOTE]
> Although <xref:System.Windows.Media.VisualBrush> is a type of <xref:System.Windows.Freezable> object, it cannot be frozen (made read-only) when its <xref:System.Windows.Media.VisualBrush.Visual%2A> property is set to a value other than `null`.
@@ -87,7 +87,7 @@ Objects painted by a DrawingBrush
- Use an existing <xref:System.Windows.Media.Visual>, which creates a duplicate image of the target <xref:System.Windows.Media.Visual>. You can then use the <xref:System.Windows.Media.VisualBrush> to create interesting effects, such as reflection and magnification. For an example, see the [Example: Create a Reflection](#examplevisualbrush2) section.
When you define a new <xref:System.Windows.Media.VisualBrush.Visual%2A> for a <xref:System.Windows.Media.VisualBrush> and that <xref:System.Windows.Media.Visual> is a <xref:System.Windows.UIElement> (such as a panel or control), the layout system runs on the <xref:System.Windows.UIElement> and its child elements when the <xref:System.Windows.Media.VisualBrush.AutoLayoutContent%2A> property is set to `true`. However, the root <xref:System.Windows.UIElement> is essentially isolated from the rest of the system: styles, and external layout can't permeate this boundary. Therefore, you should explicitly specify the size of the root <xref:System.Windows.UIElement>, because its only parent is the <xref:System.Windows.Media.VisualBrush> and therefore it cannot automatically size itself to the area being painted. For more information about layout in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], see the [Layout](../advanced/layout.md).
When you define a new <xref:System.Windows.Media.VisualBrush.Visual%2A> for a <xref:System.Windows.Media.VisualBrush> and that <xref:System.Windows.Media.Visual> is a <xref:System.Windows.UIElement> (such as a panel or control), the layout system runs on the <xref:System.Windows.UIElement> and its child elements when the <xref:System.Windows.Media.VisualBrush.AutoLayoutContent%2A> property is set to `true`. However, the root <xref:System.Windows.UIElement> is essentially isolated from the rest of the system: styles, and external layout can't permeate this boundary. Therefore, you should explicitly specify the size of the root <xref:System.Windows.UIElement>, because its only parent is the <xref:System.Windows.Media.VisualBrush> and therefore it cannot automatically size itself to the area being painted. For more information about layout in Windows Presentation Foundation (WPF), see the [Layout](../advanced/layout.md).
Like <xref:System.Windows.Media.ImageBrush> and <xref:System.Windows.Media.DrawingBrush>, a <xref:System.Windows.Media.VisualBrush> stretches its content to fill its output area. You can override this behavior by changing the <xref:System.Windows.Media.TileBrush.Stretch%2A> property from its default setting of <xref:System.Windows.Media.Stretch.Fill>. For more information, see the <xref:System.Windows.Media.TileBrush.Stretch%2A> property.
@@ -19,13 +19,13 @@ This topic describes how to use <xref:System.Windows.Media.SolidColorBrush>, <xr
## Painting an Area with a Solid Color
One of the most common operations in any platform is to paint an area with a solid <xref:System.Windows.Media.Color>. To accomplish this task, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides the <xref:System.Windows.Media.SolidColorBrush> class. The following sections describe the different ways to paint with a <xref:System.Windows.Media.SolidColorBrush>.
One of the most common operations in any platform is to paint an area with a solid <xref:System.Windows.Media.Color>. To accomplish this task, Windows Presentation Foundation (WPF) provides the <xref:System.Windows.Media.SolidColorBrush> class. The following sections describe the different ways to paint with a <xref:System.Windows.Media.SolidColorBrush>.
<a name="solidcolorinxaml"></a>
### Using a SolidColorBrush in "XAML"
To paint an area with a solid color in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], use one of the following options.
To paint an area with a solid color in XAML, use one of the following options.
- Select a predefined solid color brush by name. For example, you can set a button's <xref:System.Windows.Controls.Control.Background%2A> to "Red" or "MediumBlue". For a list of other predefined solid color brushes, see the static properties of the <xref:System.Windows.Media.Brushes> class. The following is an example.
@@ -65,7 +65,7 @@ For additional ways to specify color, see the <xref:System.Windows.Media.Color>
## Painting an Area with a Gradient
A gradient brush paints an area with multiple colors that blend into each other along an axis. You can use them to create impressions of light and shadow, giving your controls a three-dimensional feel. You can also use them to simulate glass, chrome, water, and other smooth surfaces. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides two types of gradient brushes: <xref:System.Windows.Media.LinearGradientBrush> and <xref:System.Windows.Media.RadialGradientBrush>.
A gradient brush paints an area with multiple colors that blend into each other along an axis. You can use them to create impressions of light and shadow, giving your controls a three-dimensional feel. You can also use them to simulate glass, chrome, water, and other smooth surfaces. WPF provides two types of gradient brushes: <xref:System.Windows.Media.LinearGradientBrush> and <xref:System.Windows.Media.RadialGradientBrush>.
<a name="lineargradientbrush"></a>
@@ -88,7 +88,7 @@ This code produces the following gradient:
The <xref:System.Windows.Media.GradientStop> is the basic building block of a gradient brush. A gradient stop specifies a <xref:System.Windows.Media.GradientStop.Color%2A> at an <xref:System.Windows.Media.GradientStop.Offset%2A> along the gradient axis.
- The gradient stop's <xref:System.Windows.Media.GradientStop.Color%2A> property specifies the color of the gradient stop. You may set the color by using a predefined color (provided by the <xref:System.Windows.Media.Colors> class) or by specifying ScRGB or ARGB values. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you may also use hexadecimal notation to describe a color. For more information, see the <xref:System.Windows.Media.Color> structure.
- The gradient stop's <xref:System.Windows.Media.GradientStop.Color%2A> property specifies the color of the gradient stop. You may set the color by using a predefined color (provided by the <xref:System.Windows.Media.Colors> class) or by specifying ScRGB or ARGB values. In XAML, you may also use hexadecimal notation to describe a color. For more information, see the <xref:System.Windows.Media.Color> structure.
- The gradient stop's <xref:System.Windows.Media.GradientStop.Offset%2A> property specifies the position of the gradient stop's color on the gradient axis. The offset is a <xref:System.Double> that ranges from 0 to 1. The closer a gradient stop's offset value is to 0, the closer the color is to the start of the gradient. The closer the gradient's offset value is to 1, the closer the color is to the end of the gradient.
@@ -155,13 +155,13 @@ RadialGradientBrushes with different GradientOrigin, Center, RadiusX, and Radius
## Specifying Transparent or Partially-Transparent Gradient Stops
Because gradient stops do not provide an opacity property, you must specify the alpha channel of colors using ARGB hexadecimal notation in markup or use the <xref:System.Windows.Media.Color.FromScRgb%2A?displayProperty=nameWithType> method to create gradient stops that are transparent or partially transparent. The following sections explain how to create partially transparent gradient stops in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and code.
Because gradient stops do not provide an opacity property, you must specify the alpha channel of colors using ARGB hexadecimal notation in markup or use the <xref:System.Windows.Media.Color.FromScRgb%2A?displayProperty=nameWithType> method to create gradient stops that are transparent or partially transparent. The following sections explain how to create partially transparent gradient stops in XAML and code.
<a name="argbsyntax"></a>
### Specifying Color Opacity in "XAML"
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use ARGB hexadecimal notation to specify the opacity of individual colors. ARGB hexadecimal notation uses the following syntax:
In XAML, you use ARGB hexadecimal notation to specify the opacity of individual colors. ARGB hexadecimal notation uses the following syntax:
`#` **aa** *rrggbb*
@@ -14,7 +14,7 @@ ms.assetid: 979c732c-df74-47a6-be96-8e07b3707d53
<a name="prerequisites"></a>
## Prerequisites
To understand this topic, you should be familiar with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animations features. For an introduction to animation features, see the [Animation Overview](animation-overview.md).
To understand this topic, you should be familiar with WPF animations features. For an introduction to animation features, see the [Animation Overview](animation-overview.md).
Because you use a <xref:System.Windows.Media.PathGeometry> object to define a path animation, you should also be familiar with <xref:System.Windows.Media.PathGeometry> and the different types of <xref:System.Windows.Media.PathSegment> objects. For more information, see the [Geometry Overview](geometry-overview.md).
@@ -29,9 +29,9 @@ ms.assetid: 979c732c-df74-47a6-be96-8e07b3707d53
[!code-csharp[PathAnimationGallery_procedural_snip#MatrixAnimationUsingPathDoesRotateWithTangentWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/PathAnimationGallery_procedural_snip/CSharp/MatrixAnimationUsingPathDoesRotateWithTangentExample.cs#matrixanimationusingpathdoesrotatewithtangentwholepage)]
[!code-vb[PathAnimationGallery_procedural_snip#MatrixAnimationUsingPathDoesRotateWithTangentWholePage](~/samples/snippets/visualbasic/VS_Snippets_Wpf/PathAnimationGallery_procedural_snip/VisualBasic/MatrixAnimationUsingPathDoesRotateWithTangentExample.vb#matrixanimationusingpathdoesrotatewithtangentwholepage)]
For more information about the path syntax that is used in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example, see the [Path Markup Syntax](path-markup-syntax.md) overview. For the complete sample, see [Path Animation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Animation/PathAnimations).
For more information about the path syntax that is used in the XAML example, see the [Path Markup Syntax](path-markup-syntax.md) overview. For the complete sample, see [Path Animation Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Animation/PathAnimations).
You can apply a path animation to a property by using a <xref:System.Windows.Media.Animation.Storyboard> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and code, or by using the <xref:System.Windows.Media.Animation.Animatable.BeginAnimation%2A> method in code. You can also use a path animation to create an <xref:System.Windows.Media.Animation.AnimationClock> and apply it to one or more properties. For more information about the different methods for applying animations, see [Property Animation Techniques Overview](property-animation-techniques-overview.md).
You can apply a path animation to a property by using a <xref:System.Windows.Media.Animation.Storyboard> in XAML and code, or by using the <xref:System.Windows.Media.Animation.Animatable.BeginAnimation%2A> method in code. You can also use a path animation to create an <xref:System.Windows.Media.Animation.AnimationClock> and apply it to one or more properties. For more information about the different methods for applying animations, see [Property Animation Techniques Overview](property-animation-techniques-overview.md).
<a name="animation_types"></a>
## Path Animation Types
@@ -43,7 +43,7 @@ ms.assetid: 979c732c-df74-47a6-be96-8e07b3707d53
Where *\<Type>* is the type of value that the class animates.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides the following path animation classes.
WPF provides the following path animation classes.
|Property type|Corresponding path animation class|Example|
|-------------------|----------------------------------------|-------------|
@@ -79,9 +79,9 @@ ms.assetid: 979c732c-df74-47a6-be96-8e07b3707d53
For more information about <xref:System.Windows.Media.PathGeometry> objects, see the [Geometry Overview](geometry-overview.md).
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can also use a special abbreviated syntax to set the <xref:System.Windows.Media.PathGeometry.Figures%2A> property of a <xref:System.Windows.Media.PathGeometry>. For more information, see [Path Markup Syntax](path-markup-syntax.md) overview.
In XAML, you can also use a special abbreviated syntax to set the <xref:System.Windows.Media.PathGeometry.Figures%2A> property of a <xref:System.Windows.Media.PathGeometry>. For more information, see [Path Markup Syntax](path-markup-syntax.md) overview.
For more information about the path syntax that is used in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example, see the [Path Markup Syntax](path-markup-syntax.md) overview.
For more information about the path syntax that is used in the XAML example, see the [Path Markup Syntax](path-markup-syntax.md) overview.
## See also
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: b8586241-a02d-486e-9223-e1e98e047f41
---
# Path Markup Syntax
Paths are discussed in [Shapes and Basic Drawing in WPF Overview](shapes-and-basic-drawing-in-wpf-overview.md) and the [Geometry Overview](geometry-overview.md), however, this topic describes in detail the powerful and complex mini-language you can use to specify path geometries more compactly using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
Paths are discussed in [Shapes and Basic Drawing in WPF Overview](shapes-and-basic-drawing-in-wpf-overview.md) and the [Geometry Overview](geometry-overview.md), however, this topic describes in detail the powerful and complex mini-language you can use to specify path geometries more compactly using Extensible Application Markup Language (XAML).
<a name="prerequisites"></a>
## Prerequisites
@@ -18,7 +18,7 @@ Paths are discussed in [Shapes and Basic Drawing in WPF Overview](shapes-and-bas
<a name="abouthisdocument"></a>
## StreamGeometry and PathFigureCollection Mini-Languages
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides two classes that provide mini-languages for describing geometric paths: <xref:System.Windows.Media.StreamGeometry> and <xref:System.Windows.Media.PathFigureCollection>.
WPF provides two classes that provide mini-languages for describing geometric paths: <xref:System.Windows.Media.StreamGeometry> and <xref:System.Windows.Media.PathFigureCollection>.
- You use the <xref:System.Windows.Media.StreamGeometry> mini-language when setting a property of type <xref:System.Windows.Media.Geometry>, such as the <xref:System.Windows.UIElement.Clip%2A> property of a <xref:System.Windows.UIElement> or the <xref:System.Windows.Shapes.Path.Data%2A> property of a <xref:System.Windows.Shapes.Path> element. The following example uses attribute syntax to create a <xref:System.Windows.Media.StreamGeometry>.
@@ -38,13 +38,13 @@ Paths are discussed in [Shapes and Basic Drawing in WPF Overview](shapes-and-bas
Two numbers dont actually have to be separated by a comma or white space, but this can only be done when the resulting string is unambiguous. For instance, `2..3` is actually two numbers: "2." And ".3". Similarly, `2-3` is "2" and "-3". Spaces are not required before or after commands, either.
### Syntax
The [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] attribute usage syntax for a <xref:System.Windows.Media.StreamGeometry> is composed of an optional <xref:System.Windows.Media.FillRule> value and one or more figure descriptions.
The Extensible Application Markup Language (XAML) attribute usage syntax for a <xref:System.Windows.Media.StreamGeometry> is composed of an optional <xref:System.Windows.Media.FillRule> value and one or more figure descriptions.
|StreamGeometry XAML Attribute Usage|
|-----------------------------------------|
|`<` *object* *property* `="`[ `fillRule`] `figureDescription`[ `figureDescription`]* `" ... />`|
The [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] attribute usage syntax for a <xref:System.Windows.Media.PathFigureCollection> is composed of one or more figure descriptions.
The Extensible Application Markup Language (XAML) attribute usage syntax for a <xref:System.Windows.Media.PathFigureCollection> is composed of one or more figure descriptions.
|PathFigureCollection XAML Attribute Usage|
|-----------------------------------------------|
@@ -24,9 +24,9 @@ This topic describes the different approaches for animating properties: storyboa
## Different Ways to Animate
Because there are many different scenarios for animating properties, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides several approaches for animating properties.
Because there are many different scenarios for animating properties, WPF provides several approaches for animating properties.
For each approach, the following table indicates whether it can be used per-instance, in styles, in control templates, or in data templates; whether it can be used in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]; and whether the approach enables you to interactively control the animation. "Per-Instance" refers to the technique of applying an animation or storyboard directly to instances of an object, rather than in a style, control template, or data template.
For each approach, the following table indicates whether it can be used per-instance, in styles, in control templates, or in data templates; whether it can be used in XAML; and whether the approach enables you to interactively control the animation. "Per-Instance" refers to the technique of applying an animation or storyboard directly to instances of an object, rather than in a style, control template, or data template.
|Animation technique|Scenarios|Supports XAML|Interactively controllable|
|-------------------------|---------------|-------------------|--------------------------------|
@@ -39,7 +39,7 @@ This topic describes the different approaches for animating properties: storyboa
## Storyboard Animations
Use a <xref:System.Windows.Media.Animation.Storyboard> when you want to define and apply your animations in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], interactively control your animations after they start, create a complex tree of animations, or animate in a <xref:System.Windows.Style>, <xref:System.Windows.Controls.ControlTemplate> or <xref:System.Windows.DataTemplate>. For an object to be animated by a <xref:System.Windows.Media.Animation.Storyboard>, it must be a <xref:System.Windows.FrameworkElement> or <xref:System.Windows.FrameworkContentElement>, or it must be used to set a <xref:System.Windows.FrameworkElement> or <xref:System.Windows.FrameworkContentElement>. For more details, see the [Storyboards Overview](storyboards-overview.md).
Use a <xref:System.Windows.Media.Animation.Storyboard> when you want to define and apply your animations in XAML, interactively control your animations after they start, create a complex tree of animations, or animate in a <xref:System.Windows.Style>, <xref:System.Windows.Controls.ControlTemplate> or <xref:System.Windows.DataTemplate>. For an object to be animated by a <xref:System.Windows.Media.Animation.Storyboard>, it must be a <xref:System.Windows.FrameworkElement> or <xref:System.Windows.FrameworkContentElement>, or it must be used to set a <xref:System.Windows.FrameworkElement> or <xref:System.Windows.FrameworkContentElement>. For more details, see the [Storyboards Overview](storyboards-overview.md).
A <xref:System.Windows.Media.Animation.Storyboard> is a special type of container <xref:System.Windows.Media.Animation.Timeline> that provides targeting information for the animations it contains. To animate with a <xref:System.Windows.Media.Animation.Storyboard>, you complete the following three steps.
@@ -51,7 +51,7 @@ This topic describes the different approaches for animating properties: storyboa
4. Begin the <xref:System.Windows.Media.Animation.Storyboard>.
Beginning a <xref:System.Windows.Media.Animation.Storyboard> applies animations to the properties they animate and starts them. There are two ways to begin a <xref:System.Windows.Media.Animation.Storyboard>: you can use the <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method provided by the <xref:System.Windows.Media.Animation.Storyboard> class, or you can use a <xref:System.Windows.Media.Animation.BeginStoryboard> action. The only way to animate in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is to use a <xref:System.Windows.Media.Animation.BeginStoryboard> action. A <xref:System.Windows.Media.Animation.BeginStoryboard> action can be used in an <xref:System.Windows.EventTrigger>, property <xref:System.Windows.Trigger>, or a <xref:System.Windows.DataTrigger>.
Beginning a <xref:System.Windows.Media.Animation.Storyboard> applies animations to the properties they animate and starts them. There are two ways to begin a <xref:System.Windows.Media.Animation.Storyboard>: you can use the <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method provided by the <xref:System.Windows.Media.Animation.Storyboard> class, or you can use a <xref:System.Windows.Media.Animation.BeginStoryboard> action. The only way to animate in XAML is to use a <xref:System.Windows.Media.Animation.BeginStoryboard> action. A <xref:System.Windows.Media.Animation.BeginStoryboard> action can be used in an <xref:System.Windows.EventTrigger>, property <xref:System.Windows.Trigger>, or a <xref:System.Windows.DataTrigger>.
The following table shows the different places where each <xref:System.Windows.Media.Animation.Storyboard> begin technique is supported: per-instance, style, control template, and data template.
@@ -113,11 +113,11 @@ This topic describes the different approaches for animating properties: storyboa
## Per-Frame Animation: Bypass the Animation and Timing System
Use this approach when you need to completely bypass the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] animation system. One scenario for this approach is physics animations, where each step in the animation requires objects to be recomputed based on the last set of object interactions.
Use this approach when you need to completely bypass the WPF animation system. One scenario for this approach is physics animations, where each step in the animation requires objects to be recomputed based on the last set of object interactions.
Per-frame animations cannot be defined inside styles, control templates, or data templates.
To animate frame-by-frame, you register for the <xref:System.Windows.Media.CompositionTarget.Rendering> event of the object that contains the objects you want to animate. This event handler method gets called once per frame. Each time that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] marshals the persisted rendering data in the visual tree across to the composition tree, your event handler method is called.
To animate frame-by-frame, you register for the <xref:System.Windows.Media.CompositionTarget.Rendering> event of the object that contains the objects you want to animate. This event handler method gets called once per frame. Each time that WPF marshals the persisted rendering data in the visual tree across to the composition tree, your event handler method is called.
In your event handler, perform whatever calculations are necessary for your animation effect and set the properties of the objects you want to animate with these values.
@@ -17,11 +17,11 @@ ms.assetid: 66d7a6d6-e3b6-47bc-8dfe-8a1b26f7d901
# Shapes and Basic Drawing in WPF Overview
This topic gives an overview of how to draw with <xref:System.Windows.Shapes.Shape> objects. A <xref:System.Windows.Shapes.Shape> is a type of <xref:System.Windows.UIElement> that enables you to draw a shape to the screen. Because they are UI elements, <xref:System.Windows.Shapes.Shape> objects can be used inside <xref:System.Windows.Controls.Panel> elements and most controls.
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] offers several layers of access to graphics and rendering services. At the top layer, <xref:System.Windows.Shapes.Shape> objects are easy to use and provide many useful features, such as layout and participation in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] event system.
Windows Presentation Foundation (WPF) offers several layers of access to graphics and rendering services. At the top layer, <xref:System.Windows.Shapes.Shape> objects are easy to use and provide many useful features, such as layout and participation in the Windows Presentation Foundation (WPF) event system.
<a name="shapes"></a>
## Shape Objects
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a number of ready-to-use <xref:System.Windows.Shapes.Shape> objects. All shape objects inherit from the <xref:System.Windows.Shapes.Shape> class. Available shape objects include <xref:System.Windows.Shapes.Ellipse>, <xref:System.Windows.Shapes.Line>, <xref:System.Windows.Shapes.Path>, <xref:System.Windows.Shapes.Polygon>, <xref:System.Windows.Shapes.Polyline>, and <xref:System.Windows.Shapes.Rectangle>. <xref:System.Windows.Shapes.Shape> objects share the following common properties.
WPF provides a number of ready-to-use <xref:System.Windows.Shapes.Shape> objects. All shape objects inherit from the <xref:System.Windows.Shapes.Shape> class. Available shape objects include <xref:System.Windows.Shapes.Ellipse>, <xref:System.Windows.Shapes.Line>, <xref:System.Windows.Shapes.Path>, <xref:System.Windows.Shapes.Polygon>, <xref:System.Windows.Shapes.Polyline>, and <xref:System.Windows.Shapes.Rectangle>. <xref:System.Windows.Shapes.Shape> objects share the following common properties.
- <xref:System.Windows.Shapes.Shape.Stroke%2A>: Describes how the shape's outline is painted.
@@ -80,7 +80,7 @@ This topic gives an overview of how to draw with <xref:System.Windows.Shapes.Sha
<a name="pathdatastring"></a>
### XAML Abbreviated Syntax
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you may also use a special abbreviated syntax to describe a <xref:System.Windows.Shapes.Path>. In the following example, abbreviated syntax is used to draw a complex shape.
In Extensible Application Markup Language (XAML), you may also use a special abbreviated syntax to describe a <xref:System.Windows.Shapes.Path>. In the following example, abbreviated syntax is used to draw a complex shape.
```xaml
<Path Stroke="DarkGoldenRod" StrokeThickness="3"
@@ -89,7 +89,7 @@ Data="M 100,200 C 100,25 400,350 400,175 H 280" />
The following image shows a rendered <xref:System.Windows.Shapes.Path>.
![Path illustration](./media/shape-ovw-path.PNG "shape_ovw_path")
![A second Path illustration.](./media/shape-ovw-path.PNG "shape_ovw_path")
The <xref:System.Windows.Shapes.Path.Data%2A> attribute string begins with the "moveto" command, indicated by M, which establishes a start point for the path in the coordinate system of the <xref:System.Windows.Controls.Canvas>. <xref:System.Windows.Shapes.Path> data parameters are case-sensitive. The capital M indicates an absolute location for the new current point. A lowercase m would indicate relative coordinates. The first segment is a cubic Bezier curve beginning at (100,200) and ending at (400,175), drawn using the two control points (100,25) and (400,350). This segment is indicated by the C command in the <xref:System.Windows.Shapes.Path.Data%2A> attribute string. Again, the capital C indicates an absolute path; the lowercase c would indicate a relative path.
@@ -16,7 +16,7 @@ helpviewer_keywords:
ms.assetid: 893253b8-c2df-4f22-961d-cbc533d64c79
---
# Shapes
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides support for drawing basic shapes using the <xref:System.Windows.Shapes.Shape> class. Shape objects derive from <xref:System.Windows.FrameworkElement> and as such, participate in the layout system and can be drawn simply using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
Windows Presentation Foundation (WPF) provides support for drawing basic shapes using the <xref:System.Windows.Shapes.Shape> class. Shape objects derive from <xref:System.Windows.FrameworkElement> and as such, participate in the layout system and can be drawn simply using Extensible Application Markup Language (XAML).
## In This Section
[Shapes and Basic Drawing in WPF Overview](shapes-and-basic-drawing-in-wpf-overview.md)
@@ -58,7 +58,7 @@ However, you could not use a <xref:System.Windows.Media.Animation.Storyboard> to
To use a <xref:System.Windows.Media.Animation.Storyboard> to organize and apply animations, you add the animations as child timelines of the <xref:System.Windows.Media.Animation.Storyboard>. The <xref:System.Windows.Media.Animation.Storyboard> class provides the <xref:System.Windows.Media.Animation.Storyboard.TargetName%2A?displayProperty=nameWithType> and <xref:System.Windows.Media.Animation.Storyboard.TargetProperty?displayProperty=nameWithType> attached properties. You set these properties on an animation to specify its target object and property.
To apply animations to their targets, you begin the <xref:System.Windows.Media.Animation.Storyboard> using a trigger action or a method. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use a <xref:System.Windows.Media.Animation.BeginStoryboard> object with an <xref:System.Windows.EventTrigger>, <xref:System.Windows.Trigger>, or <xref:System.Windows.DataTrigger>. In code, you can also use the <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method.
To apply animations to their targets, you begin the <xref:System.Windows.Media.Animation.Storyboard> using a trigger action or a method. In XAML, you use a <xref:System.Windows.Media.Animation.BeginStoryboard> object with an <xref:System.Windows.EventTrigger>, <xref:System.Windows.Trigger>, or <xref:System.Windows.DataTrigger>. In code, you can also use the <xref:System.Windows.Media.Animation.Storyboard.Begin%2A> method.
The following table shows the different places where each <xref:System.Windows.Media.Animation.Storyboard> begin technique is supported: per-instance, style, control template, and data template. "Per-Instance" refers to the technique of applying an animation or storyboard directly to instances of an object, rather than in a style, control template, or data template.
@@ -88,11 +88,11 @@ The previous section mentioned that, for an animation to find its target, it mus
> [!CAUTION]
> While you can use the `Target` property to bind directly to an object as an alternative to `TargetName`, it isn't serializable. There is no guaranteed that the `Target` object can be correctly referenced in XAML.
For the <xref:System.Windows.Setter.TargetName%2A> property to work, the targeted object must have a name. Assigning a name to a <xref:System.Windows.FrameworkElement> or a <xref:System.Windows.FrameworkContentElement> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is different than assigning a name to a <xref:System.Windows.Freezable> object.
For the <xref:System.Windows.Setter.TargetName%2A> property to work, the targeted object must have a name. Assigning a name to a <xref:System.Windows.FrameworkElement> or a <xref:System.Windows.FrameworkContentElement> in XAML is different than assigning a name to a <xref:System.Windows.Freezable> object.
Framework elements are those classes that inherit from the <xref:System.Windows.FrameworkElement> class. Examples of framework elements include <xref:System.Windows.Window>, <xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Button>, and <xref:System.Windows.Shapes.Rectangle>. Essentially all windows, panels, and controls are elements. Framework content elements are those classes that inherit from the <xref:System.Windows.FrameworkContentElement> class. Examples of framework content elements include <xref:System.Windows.Documents.FlowDocument> and <xref:System.Windows.Documents.Paragraph>. If you're not sure whether a type is a framework element or a framework content element, check to see whether it has a Name property. If it does, it's probably a framework element or a framework content element. To be sure, check the Inheritance Hierarchy section of its type page.
To enable the targeting of a framework element or a framework content element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you set its <xref:System.Windows.FrameworkElement.Name%2A> property. In code, you also need to use the <xref:System.Windows.NameScope.RegisterName%2A> method to register the element's name with the element for which you've created a <xref:System.Windows.NameScope>.
To enable the targeting of a framework element or a framework content element in XAML, you set its <xref:System.Windows.FrameworkElement.Name%2A> property. In code, you also need to use the <xref:System.Windows.NameScope.RegisterName%2A> method to register the element's name with the element for which you've created a <xref:System.Windows.NameScope>.
The following example, taken from the preceding example, assigns the name `MyRectangle` a <xref:System.Windows.Shapes.Rectangle>, a type of <xref:System.Windows.FrameworkElement>.
@@ -108,7 +108,7 @@ After it has a name, you can animate a property of that element.
<xref:System.Windows.Freezable> types are those classes that inherit from the <xref:System.Windows.Freezable> class. Examples of <xref:System.Windows.Freezable> include <xref:System.Windows.Media.SolidColorBrush>, <xref:System.Windows.Media.RotateTransform>, and <xref:System.Windows.Media.GradientStop>.
To enable the targeting of a <xref:System.Windows.Freezable> by an animation in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you use the [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) to assign it a name. In code, you use the <xref:System.Windows.NameScope.RegisterName%2A> method to register its name with the element for which you've created a <xref:System.Windows.NameScope>.
To enable the targeting of a <xref:System.Windows.Freezable> by an animation in XAML, you use the [x:Name Directive](/dotnet/desktop/xaml-services/xname-directive) to assign it a name. In code, you use the <xref:System.Windows.NameScope.RegisterName%2A> method to register its name with the element for which you've created a <xref:System.Windows.NameScope>.
The following example assigns a name to a <xref:System.Windows.Freezable> object.
@@ -146,7 +146,7 @@ The following sections describe indirect property targeting syntax in more detai
### Indirectly Targeting a Property of a Freezable in XAML
To target a property of a freezable in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], use the following syntax.
To target a property of a freezable in XAML, use the following syntax.
| Property syntax |
|-----------------|
@@ -240,7 +240,7 @@ The previous sections described how to indirectly target a <xref:System.Windows.
## Interactively Controlling a Storyboard in XAML
To start a storyboard in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you use a <xref:System.Windows.Media.Animation.BeginStoryboard> trigger action. <xref:System.Windows.Media.Animation.BeginStoryboard> distributes the animations to the objects and properties they animate, and starts the storyboard. (For details about this process, see the [Animation and Timing System Overview](animation-and-timing-system-overview.md).) If you give the <xref:System.Windows.Media.Animation.BeginStoryboard> a name by specifying its <xref:System.Windows.Media.Animation.BeginStoryboard.Name%2A> property, you make it a controllable storyboard. You can then interactively control the storyboard after it's started. The following is a list of controllable storyboard actions that you use with event triggers to control a storyboard.
To start a storyboard in Extensible Application Markup Language (XAML), you use a <xref:System.Windows.Media.Animation.BeginStoryboard> trigger action. <xref:System.Windows.Media.Animation.BeginStoryboard> distributes the animations to the objects and properties they animate, and starts the storyboard. (For details about this process, see the [Animation and Timing System Overview](animation-and-timing-system-overview.md).) If you give the <xref:System.Windows.Media.Animation.BeginStoryboard> a name by specifying its <xref:System.Windows.Media.Animation.BeginStoryboard.Name%2A> property, you make it a controllable storyboard. You can then interactively control the storyboard after it's started. The following is a list of controllable storyboard actions that you use with event triggers to control a storyboard.
- <xref:System.Windows.Media.Animation.PauseStoryboard>: Pauses the storyboard.
@@ -300,7 +300,7 @@ You can use <xref:System.Windows.Media.Animation.Storyboard> objects to define a
- You can't use dynamic resource references or data binding expressions to set <xref:System.Windows.Media.Animation.Storyboard> or animation property values. That's because everything inside a <xref:System.Windows.Style> must be thread-safe, and the timing system must <xref:System.Windows.Freezable.Freeze%2A><xref:System.Windows.Media.Animation.Storyboard> objects to make them thread-safe. A <xref:System.Windows.Media.Animation.Storyboard> cannot be frozen if it or its child timelines contain dynamic resource references or data binding expressions. For more information about freezing and other <xref:System.Windows.Freezable> features, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md).
- In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can't declare event handlers for <xref:System.Windows.Media.Animation.Storyboard> or animation events.
- In XAML, you can't declare event handlers for <xref:System.Windows.Media.Animation.Storyboard> or animation events.
For an example showing how to define a storyboard in a style, see the [Animate in a Style](how-to-animate-in-a-style.md) example.
@@ -316,7 +316,7 @@ You can use <xref:System.Windows.Media.Animation.Storyboard> objects to define a
- You can't use dynamic resource references or data binding expressions to set <xref:System.Windows.Media.Animation.Storyboard> or animation property values. That's because everything inside a <xref:System.Windows.Controls.ControlTemplate> must be thread-safe, and the timing system must <xref:System.Windows.Freezable.Freeze%2A><xref:System.Windows.Media.Animation.Storyboard> objects to make them thread-safe. A <xref:System.Windows.Media.Animation.Storyboard> cannot be frozen if it or its child timelines contain dynamic resource references or data binding expressions. For more information about freezing and other <xref:System.Windows.Freezable> features, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md).
- In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can't declare event handlers for <xref:System.Windows.Media.Animation.Storyboard> or animation events.
- In XAML, you can't declare event handlers for <xref:System.Windows.Media.Animation.Storyboard> or animation events.
For an example showing how to define a storyboard in a <xref:System.Windows.Controls.ControlTemplate>, see the [Animate in a ControlTemplate](how-to-animate-in-a-controltemplate.md) example.
@@ -19,7 +19,7 @@ This topic describes the timing behaviors of animations and other <xref:System.W
## Timeline Types
A <xref:System.Windows.Media.Animation.Timeline> represents a segment of time. It provides properties that enable you to specify the length of that segment, when it should start, how many times it will repeat, how fast time progresses in that segment, and more.
Classes that inherit from the timeline class provide additional functionality, such as animation and media playback. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides the following <xref:System.Windows.Media.Animation.Timeline> types.
Classes that inherit from the timeline class provide additional functionality, such as animation and media playback. WPF provides the following <xref:System.Windows.Media.Animation.Timeline> types.
|Timeline type|Description|
|-------------------|-----------------|
@@ -88,7 +88,7 @@ This topic describes the timing behaviors of animations and other <xref:System.W
<a name="timelinebegin"></a>
## The BeginTime Property
The <xref:System.Windows.Media.Animation.Timeline.BeginTime%2A> property enables you to specify when a timeline starts. A timeline's begin time is relative to its parent timeline. A begin time of zero seconds means the timeline starts as soon as it parent starts; any other value creates an offset between when the parent timeline starts playing and when the child timeline plays. For example, a begin time of two seconds means the timeline starts playing when its parent has reached a time of two seconds. By default, all timelines have a begin time of zero seconds. You may also set a timeline's begin time to `null`, which prevents the timeline from starting. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], you specify null using the [x:Null Markup Extension](/dotnet/desktop/xaml-services/xnull-markup-extension).
The <xref:System.Windows.Media.Animation.Timeline.BeginTime%2A> property enables you to specify when a timeline starts. A timeline's begin time is relative to its parent timeline. A begin time of zero seconds means the timeline starts as soon as it parent starts; any other value creates an offset between when the parent timeline starts playing and when the child timeline plays. For example, a begin time of two seconds means the timeline starts playing when its parent has reached a time of two seconds. By default, all timelines have a begin time of zero seconds. You may also set a timeline's begin time to `null`, which prevents the timeline from starting. In WPF, you specify null using the [x:Null Markup Extension](/dotnet/desktop/xaml-services/xnull-markup-extension).
Note that the begin time is not applied each time a timeline repeats because of its <xref:System.Windows.Media.Animation.Timeline.RepeatBehavior%2A> setting. If you were to create an animation with a <xref:System.Windows.Media.Animation.Timeline.BeginTime%2A> of 10 seconds and a <xref:System.Windows.Media.Animation.RepeatBehavior> of <xref:System.Windows.Media.Animation.RepeatBehavior.Forever%2A>, there would be a 10-second delay before the animation played for the first time, but not for each successive repetition. However, if the animation's parent timeline were to restart or repeat, the 10-second delay would occur.
@@ -15,7 +15,7 @@ This topic describes how to use the five timing events available on <xref:System
## Prerequisites
To understand this topic, you should understand how to create and use animations. To get started with animation, see the [Animation Overview](animation-overview.md).
There are multiple ways to animate properties in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]:
There are multiple ways to animate properties in WPF:
- **Using storyboard objects** (markup and code): You can use <xref:System.Windows.Media.Animation.Storyboard> objects to arrange and distribute animations to one or more objects. For an example, see [Animate a Property by Using a Storyboard](how-to-animate-a-property-by-using-a-storyboard.md).
@@ -57,7 +57,7 @@ This topic describes how to use the five timing events available on <xref:System
|**RemoveRequested**|Remove||
## Ticking and Event Consolidation
When you animate objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], its the timing engine that manages your animations. The timing engine tracks the progression of time and computes the state of each animation. It makes many such evaluation passes in a second. These evaluation passes are known as "ticks."
When you animate objects in WPF, its the timing engine that manages your animations. The timing engine tracks the progression of time and computes the state of each animation. It makes many such evaluation passes in a second. These evaluation passes are known as "ticks."
While ticks occur frequently, it's possible for a lot of things to happen between ticks. For example, a timeline might be stopped, started, and stopped again, in which case its current state will have changed three times. In theory, the event could be raised multiple times in a single tick; however, the timing engine consolidates events, so that each event can be raised at most once per tick.
@@ -68,7 +68,7 @@ This topic describes how to use the five timing events available on <xref:System
## Registering for Clock Events with a Timeline
Although a timeline's <xref:System.Windows.Media.Animation.Timeline.Completed>, <xref:System.Windows.Media.Animation.Timeline.CurrentGlobalSpeedInvalidated>, <xref:System.Windows.Media.Animation.Timeline.CurrentStateInvalidated>, <xref:System.Windows.Media.Animation.Timeline.CurrentTimeInvalidated>, and <xref:System.Windows.Media.Animation.Timeline.RemoveRequested> events appear to be associated with the timeline, registering for these events actually associates an event handler with the <xref:System.Windows.Media.Animation.Clock> created for the timeline.
When you register for the <xref:System.Windows.Media.Animation.Timeline.Completed> event on a timeline, for example, you're actually telling the system to register for the <xref:System.Windows.Media.Animation.Clock.Completed> event of each clock that is created for the timeline. In code, you must register for this event before the <xref:System.Windows.Media.Animation.Clock> is created for this timeline; otherwise, you won't receive notification. This happens automatically in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]; the parser automatically registers for the event before the <xref:System.Windows.Media.Animation.Clock> is created.
When you register for the <xref:System.Windows.Media.Animation.Timeline.Completed> event on a timeline, for example, you're actually telling the system to register for the <xref:System.Windows.Media.Animation.Clock.Completed> event of each clock that is created for the timeline. In code, you must register for this event before the <xref:System.Windows.Media.Animation.Clock> is created for this timeline; otherwise, you won't receive notification. This happens automatically in XAML; the parser automatically registers for the event before the <xref:System.Windows.Media.Animation.Clock> is created.
## See also
@@ -25,7 +25,7 @@ This topic describes how to use the 2D <xref:System.Windows.Media.Transform> cla
> [!NOTE]
> Windows Presentation Foundation (WPF) uses row-major matrices. Vectors are expressed as row-vectors, not column vectors.
The following table shows the structure of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] matrix.
The following table shows the structure of a WPF matrix.
### A 2D transformation matrix
@@ -103,7 +103,7 @@ A Rectangle element rotated 45 degrees about the point (25, 25)
Which property should you use? Because of the performance benefits that it provides, use the <xref:System.Windows.UIElement.RenderTransform%2A> property whenever possible, especially when you use animated <xref:System.Windows.Media.Transform> objects. Use the <xref:System.Windows.FrameworkElement.LayoutTransform%2A> property when scaling, rotating, or skewing and you need the parent of the element to adjust to the transformed size of the element. Note that, when they are used with the <xref:System.Windows.FrameworkElement.LayoutTransform%2A> property, <xref:System.Windows.Media.TranslateTransform> objects appear to have no effect on elements. That is because the layout system returns the translated element to its original position as part of its processing.
For additional information about layout in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], see [Layout](../advanced/layout.md) overview.
For additional information about layout in Windows Presentation Foundation (WPF), see [Layout](../advanced/layout.md) overview.
<a name="exampleRotateAnElement45degSection"></a>
## Example: Rotate a FrameworkElement 45 Degrees
@@ -11,20 +11,20 @@ helpviewer_keywords:
ms.assetid: f0e1600c-3217-43d5-875d-1864fa7fe628
---
# Tutorial: Hosting Visual Objects in a Win32 Application
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a rich environment for creating applications. However, when you have a substantial investment in Win32 code, it might be more effective to add [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] functionality to your application rather than rewrite your code. To provide support for Win32 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] graphics subsystems used concurrently in an application, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a mechanism for hosting objects in a Win32 window.
WPF functionality to your application rather than rewrite your code. To provide support for Win32 and WPF graphics subsystems used concurrently in an application, WPF provides a mechanism for hosting objects in a Win32 window.
This tutorial describes how to write a sample application, [Hit Test with Win32 Interoperation Sample](https://github.com/microsoft/WPF-Samples/tree/master/Visual%20Layer/VisualsHitTesting), that hosts [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual objects in a Win32 window.
This tutorial describes how to write a sample application, [Hit Test with Win32 Interoperation Sample](https://github.com/microsoft/WPF-Samples/tree/master/Visual%20Layer/VisualsHitTesting), that hosts WPF visual objects in a Win32 window.
<a name="requirements"></a>
## Requirements
This tutorial assumes a basic familiarity with both [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Win32 programming. For a basic introduction to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] programming, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md). For an introduction to Win32 programming, see any of the numerous books on the subject, in particular *Programming Windows* by Charles Petzold.
This tutorial assumes a basic familiarity with both WPF and Win32 programming. For a basic introduction to WPF programming, see [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md). For an introduction to Win32 programming, see any of the numerous books on the subject, in particular *Programming Windows* by Charles Petzold.
> [!NOTE]
> This tutorial includes a number of code examples from the associated sample. However, for readability, it does not include the complete sample code. For the complete sample code, see [Hit Test with Win32 Interoperation Sample](https://github.com/microsoft/WPF-Samples/tree/master/Visual%20Layer/VisualsHitTesting).
<a name="creating_the_host_win32_window"></a>
## Creating the Host Win32 Window
The key to hosting [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects in a Win32 window is the <xref:System.Windows.Interop.HwndSource> class. This class wraps the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] objects in a Win32 window, allowing them to be incorporated into your [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] as a child window.
The key to hosting WPF objects in a Win32 window is the <xref:System.Windows.Interop.HwndSource> class. This class wraps the WPF objects in a Win32 window, allowing them to be incorporated into your user interface (UI) as a child window.
The following example shows the code for creating the <xref:System.Windows.Interop.HwndSource> object as the Win32 container window for the visual objects. To set the window style, position, and other parameters for the Win32 window, use the <xref:System.Windows.Interop.HwndSourceParameters> object.
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 0b4e711d-e640-40cb-81c3-8f5c59909b7d
---
# Using DrawingVisual Objects
This topic provides an overview of how to use <xref:System.Windows.Media.DrawingVisual> objects in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual layer.
This topic provides an overview of how to use <xref:System.Windows.Media.DrawingVisual> objects in the WPF visual layer.
<a name="drawingvisual_object"></a>
## DrawingVisual Object
@@ -11,7 +11,7 @@ helpviewer_keywords:
ms.assetid: d82c89db-077f-4c3c-a4f8-310ebfbe0fe2
---
# Visual Layer Programming
The <xref:System.Windows.Media.Visual> object is a core [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] object, whose primary role is to provide rendering support. User interface controls, such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TextBox>, derive from the <xref:System.Windows.Media.Visual> class, and use it for persisting their rendering data.
The <xref:System.Windows.Media.Visual> object is a core WPF object, whose primary role is to provide rendering support. User interface controls, such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TextBox>, derive from the <xref:System.Windows.Media.Visual> class, and use it for persisting their rendering data.
## In This Section
[Hit Testing in the Visual Layer](hit-testing-in-the-visual-layer.md)
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: ecea1955-420b-45c6-bf43-c1404c072c41
---
# WPF Brushes Overview
Everything visible on your screen is visible because it was painted by a brush. For example, a brush is used to describe the background of a button, the foreground of text, and the fill of a shape. This topic introduces the concepts of painting with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] brushes and provides examples. Brushes enable you to paint [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] objects with anything from simple, solid colors to complex sets of patterns and images.
Everything visible on your screen is visible because it was painted by a brush. For example, a brush is used to describe the background of a button, the foreground of text, and the fill of a shape. This topic introduces the concepts of painting with user interface (UI) objects with anything from simple, solid colors to complex sets of patterns and images.
<a name="paintingwithbrush"></a>
## Painting with a Brush
@@ -11,13 +11,13 @@ helpviewer_keywords:
ms.assetid: 6dec9657-4d8c-4e46-8c54-40fb80008265
---
# WPF Graphics Rendering Overview
This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual layer. It focuses on the role of the <xref:System.Windows.Media.Visual> class for rendering support in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] model.
This topic provides an overview of the WPF visual layer. It focuses on the role of the <xref:System.Windows.Media.Visual> class for rendering support in the WPF model.
<a name="role_of_visual_object"></a>
## Role of the Visual Object
The <xref:System.Windows.Media.Visual> class is the basic abstraction from which every <xref:System.Windows.FrameworkElement> object derives. It also serves as the entry point for writing new controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], and in many ways can be thought of as the window handle (HWND) in the Win32 application model.
The <xref:System.Windows.Media.Visual> class is the basic abstraction from which every <xref:System.Windows.FrameworkElement> object derives. It also serves as the entry point for writing new controls in WPF, and in many ways can be thought of as the window handle (HWND) in the Win32 application model.
The <xref:System.Windows.Media.Visual> object is a core [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] object, whose primary role is to provide rendering support. User interface controls, such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TextBox>, derive from the <xref:System.Windows.Media.Visual> class, and use it for persisting their rendering data. The <xref:System.Windows.Media.Visual> object provides support for:
The <xref:System.Windows.Media.Visual> object is a core WPF object, whose primary role is to provide rendering support. User interface controls, such as <xref:System.Windows.Controls.Button> and <xref:System.Windows.Controls.TextBox>, derive from the <xref:System.Windows.Media.Visual> class, and use it for persisting their rendering data. The <xref:System.Windows.Media.Visual> object provides support for:
- Output display: Rendering the persisted, serialized drawing content of a visual.
@@ -41,7 +41,7 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
- Globalization
<xref:System.Windows.Media.Visual> is exposed as a public abstract class from which child classes must be derived. The following illustration shows the hierarchy of the visual objects that are exposed in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
<xref:System.Windows.Media.Visual> is exposed as a public abstract class from which child classes must be derived. The following illustration shows the hierarchy of the visual objects that are exposed in WPF.
![Diagram of classes derived from the Visual object](./media/wpf-graphics-rendering-overview/classes-derived-visual-object.png)
@@ -49,7 +49,7 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
The <xref:System.Windows.Media.DrawingVisual> is a lightweight drawing class that is used to render shapes, images, or text. This class is considered lightweight because it does not provide layout or event handling, which improves its runtime performance. For this reason, drawings are ideal for backgrounds and clip art. The <xref:System.Windows.Media.DrawingVisual> can be used to create a custom visual object. For more information, see [Using DrawingVisual Objects](using-drawingvisual-objects.md).
### Viewport3DVisual Class
The <xref:System.Windows.Media.Media3D.Viewport3DVisual> provides a bridge between 2D <xref:System.Windows.Media.Visual> and <xref:System.Windows.Media.Media3D.Visual3D> objects. The <xref:System.Windows.Media.Media3D.Visual3D> class is the base class for all 3D visual elements. The <xref:System.Windows.Media.Media3D.Viewport3DVisual> requires that you define a <xref:System.Windows.Media.Media3D.Viewport3DVisual.Camera%2A> value and a <xref:System.Windows.Media.Media3D.Viewport3DVisual.Viewport%2A> value. The camera allows you to view the scene. The viewport establishes where the projection maps onto the 2D surface. For more information on 3D in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [3D Graphics Overview](3-d-graphics-overview.md).
The <xref:System.Windows.Media.Media3D.Viewport3DVisual> provides a bridge between 2D <xref:System.Windows.Media.Visual> and <xref:System.Windows.Media.Media3D.Visual3D> objects. The <xref:System.Windows.Media.Media3D.Visual3D> class is the base class for all 3D visual elements. The <xref:System.Windows.Media.Media3D.Viewport3DVisual> requires that you define a <xref:System.Windows.Media.Media3D.Viewport3DVisual.Camera%2A> value and a <xref:System.Windows.Media.Media3D.Viewport3DVisual.Viewport%2A> value. The camera allows you to view the scene. The viewport establishes where the projection maps onto the 2D surface. For more information on 3D in WPF, see [3D Graphics Overview](3-d-graphics-overview.md).
### ContainerVisual Class
The <xref:System.Windows.Media.ContainerVisual> class is used as a container for a collection of <xref:System.Windows.Media.Visual> objects. The <xref:System.Windows.Media.DrawingVisual> class derives from the <xref:System.Windows.Media.ContainerVisual> class, allowing it to contain a collection of visual objects.
@@ -66,7 +66,7 @@ This topic provides an overview of the [!INCLUDE[TLA2#tla_winclient](../../../in
The <xref:System.Windows.Media.DrawingContext> allows you to populate a <xref:System.Windows.Media.Visual> with visual content. When you use a <xref:System.Windows.Media.DrawingContext> object's draw commands, you are actually storing a set of render data that will later be used by the graphics system; you are not drawing to the screen in real-time.
When you create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, such as a <xref:System.Windows.Controls.Button>, the control implicitly generates render data for drawing itself. For example, setting the <xref:System.Windows.Controls.ContentControl.Content%2A> property of the <xref:System.Windows.Controls.Button> causes the control to store a rendering representation of a glyph.
When you create a WPF control, such as a <xref:System.Windows.Controls.Button>, the control implicitly generates render data for drawing itself. For example, setting the <xref:System.Windows.Controls.ContentControl.Content%2A> property of the <xref:System.Windows.Controls.Button> causes the control to store a rendering representation of a glyph.
A <xref:System.Windows.Media.Visual> describes its content as one or more <xref:System.Windows.Media.Drawing> objects contained within a <xref:System.Windows.Media.DrawingGroup>. A <xref:System.Windows.Media.DrawingGroup> also describes opacity masks, transforms, bitmap effects, and other operations that are applied to its contents. <xref:System.Windows.Media.DrawingGroup> operations are applied in the following order when content is rendered: <xref:System.Windows.Media.DrawingGroup.OpacityMask%2A>, <xref:System.Windows.Media.DrawingGroup.Opacity%2A>, <xref:System.Windows.Media.DrawingGroup.BitmapEffect%2A>, <xref:System.Windows.Media.DrawingGroup.ClipGeometry%2A>, <xref:System.Windows.Media.DrawingGroup.GuidelineSet%2A>, and then <xref:System.Windows.Media.DrawingGroup.Transform%2A>.
@@ -95,7 +95,7 @@ Order of DrawingGroup operations
<a name="how_visual_objects_are_used_to_build_controls"></a>
## How Visual Objects are Used to Build Controls
Many of the objects in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are composed of other visual objects, meaning they can contain varying hierarchies of descendant objects. Many of the user interface elements in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], such as controls, are composed of multiple visual objects, representing different types of rendering elements. For example, the <xref:System.Windows.Controls.Button> control can contain a number of other objects, including <xref:Microsoft.Windows.Themes.ClassicBorderDecorator>, <xref:System.Windows.Controls.ContentPresenter>, and <xref:System.Windows.Controls.TextBlock>.
Many of the objects in WPF are composed of other visual objects, meaning they can contain varying hierarchies of descendant objects. Many of the user interface elements in WPF, such as controls, are composed of multiple visual objects, representing different types of rendering elements. For example, the <xref:System.Windows.Controls.Button> control can contain a number of other objects, including <xref:Microsoft.Windows.Themes.ClassicBorderDecorator>, <xref:System.Windows.Controls.ContentPresenter>, and <xref:System.Windows.Controls.TextBlock>.
The following code shows a <xref:System.Windows.Controls.Button> control defined in markup.
@@ -140,10 +140,10 @@ Order of DrawingGroup operations
If you were to enumerate the visual objects that comprise the <xref:System.Windows.Controls.StackPanel> element in the markup example, you would find the hierarchy of visual objects illustrated below:
![Diagram of visual tree hierarchy](./media/wpf-graphics-rendering-overview/visual-tree-hierarchy.gif)
![Diagram of visual tree hierarchy of a StackPanel control.](./media/wpf-graphics-rendering-overview/visual-tree-hierarchy.gif)
### Rendering Order
The visual tree determines the rendering order of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual and drawing objects. The order of traversal starts with the root visual, which is the top-most node in the visual tree. The root visuals children are then traversed, left to right. If a visual has children, its children are traversed before the visuals siblings. This means that the content of a child visual is rendered in front of the visual's own content.
The visual tree determines the rendering order of WPF visual and drawing objects. The order of traversal starts with the root visual, which is the top-most node in the visual tree. The root visuals children are then traversed, left to right. If a visual has children, its children are traversed before the visuals siblings. This means that the content of a child visual is rendered in front of the visual's own content.
![Diagram of the visual tree rendering order](./media/wpf-graphics-rendering-overview/visual-tree-rendering-order.gif)
@@ -151,7 +151,7 @@ Order of DrawingGroup operations
The **root visual** is the top-most element in a visual tree hierarchy. In most applications, the base class of the root visual is either <xref:System.Windows.Window> or <xref:System.Windows.Navigation.NavigationWindow>. However, if you were hosting visual objects in a Win32 application, the root visual would be the top-most visual you were hosting in the Win32 window. For more information, see [Tutorial: Hosting Visual Objects in a Win32 Application](tutorial-hosting-visual-objects-in-a-win32-application.md).
### Relationship to the Logical Tree
The logical tree in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] represents the elements of an application at run time. Although you do not manipulate this tree directly, this view of the application is useful for understanding property inheritance and event routing. Unlike the visual tree, the logical tree can represent non-visual data objects, such as <xref:System.Windows.Documents.ListItem>. In many cases, the logical tree maps very closely to an application's markup definitions. The following code shows a <xref:System.Windows.Controls.DockPanel> element defined in markup.
The logical tree in WPF represents the elements of an application at run time. Although you do not manipulate this tree directly, this view of the application is useful for understanding property inheritance and event routing. Unlike the visual tree, the logical tree can represent non-visual data objects, such as <xref:System.Windows.Documents.ListItem>. In many cases, the logical tree maps very closely to an application's markup definitions. The following code shows a <xref:System.Windows.Controls.DockPanel> element defined in markup.
[!code-xaml[VisualsOverview#VisualsOverviewSnippet5](~/samples/snippets/csharp/VS_Snippets_Wpf/VisualsOverview/CSharp/Window1.xaml#visualsoverviewsnippet5)]
@@ -165,36 +165,36 @@ Diagram of logical tree
For more information on the logical tree, see [Trees in WPF](../advanced/trees-in-wpf.md).
### Viewing the Visual Tree with XamlPad
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] tool, XamlPad, provides an option for viewing and exploring the visual tree that corresponds to the currently defined XAML content. Click the **Show Visual Tree** button on the menu bar to display the visual tree. The following illustrates the expansion of XAML content into visual tree nodes in the **Visual Tree Explorer** panel of XamlPad:
The WPF tool, XamlPad, provides an option for viewing and exploring the visual tree that corresponds to the currently defined XAML content. Click the **Show Visual Tree** button on the menu bar to display the visual tree. The following illustrates the expansion of XAML content into visual tree nodes in the **Visual Tree Explorer** panel of XamlPad:
![Visual Tree Explorer panel in XamlPad](./media/wpf-graphics-rendering-overview/visual-tree-explorer.png)
Notice how the <xref:System.Windows.Controls.Label>, <xref:System.Windows.Controls.TextBox>, and <xref:System.Windows.Controls.Button> controls each display a separate visual object hierarchy in the **Visual Tree Explorer** panel of XamlPad. This is because [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls have a <xref:System.Windows.Controls.ControlTemplate> that contains the visual tree of that control. When you explicitly reference a control, you implicitly reference its visual hierarchy.
Notice how the <xref:System.Windows.Controls.Label>, <xref:System.Windows.Controls.TextBox>, and <xref:System.Windows.Controls.Button> controls each display a separate visual object hierarchy in the **Visual Tree Explorer** panel of XamlPad. This is because WPF controls have a <xref:System.Windows.Controls.ControlTemplate> that contains the visual tree of that control. When you explicitly reference a control, you implicitly reference its visual hierarchy.
### Profiling Visual Performance
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The Visual Profiler tool provides a rich, graphical view of performance data by mapping directly to the application's visual tree. In this screenshot, the **CPU Usage** section of the Visual Profiler gives you a precise breakdown of an object's use of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] services, such as rendering and layout.
WPF provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The Visual Profiler tool provides a rich, graphical view of performance data by mapping directly to the application's visual tree. In this screenshot, the **CPU Usage** section of the Visual Profiler gives you a precise breakdown of an object's use of WPF services, such as rendering and layout.
![Visual Profiler display output](./media/wpfperf-visualprofiler-04.png "WPFPerf_VisualProfiler_04")
Visual Profiler display output
<a name="visual_rendering_behavior"></a>
## Visual Rendering Behavior
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] introduces several features that affect the rendering behavior of visual objects: retained mode graphics, vector graphics, and device independent graphics.
WPF introduces several features that affect the rendering behavior of visual objects: retained mode graphics, vector graphics, and device independent graphics.
### Retained Mode Graphics
One of the keys to understanding the role of the Visual object is to understand the difference between **immediate mode** and **retained mode** graphics systems. A standard Win32 application based on GDI or GDI+ uses an immediate mode graphics system. This means that the application is responsible for repainting the portion of the client area that is invalidated, due to an action such as a window being resized, or an object changing its visual appearance.
![Diagram of Win32 rendering sequence](./media/wpf-graphics-rendering-overview/win32-rendering-squence.png)
In contrast, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses a retained mode system. This means application objects that have a visual appearance define a set of serialized drawing data. Once the drawing data is defined, the system is responsible thereafter for responding to all repaint requests for rendering the application objects. Even at run time, you can modify or create application objects, and still rely on the system for responding to paint requests. The power in a retained mode graphics system is that drawing information is always persisted in a serialized state by the application, but rendering responsibility left to the system. The following diagram shows how the application relies on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] for responding to paint requests.
In contrast, WPF uses a retained mode system. This means application objects that have a visual appearance define a set of serialized drawing data. Once the drawing data is defined, the system is responsible thereafter for responding to all repaint requests for rendering the application objects. Even at run time, you can modify or create application objects, and still rely on the system for responding to paint requests. The power in a retained mode graphics system is that drawing information is always persisted in a serialized state by the application, but rendering responsibility left to the system. The following diagram shows how the application relies on WPF for responding to paint requests.
![Diagram of WPF rendering sequence](./media/wpf-graphics-rendering-overview/wpf-rendering-sequence.png)
#### Intelligent Redrawing
One of the biggest benefits in using retained mode graphics is that [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can efficiently optimize what needs to be redrawn in the application. Even if you have a complex scene with varying levels of opacity, you generally do not need to write special-purpose code to optimize redrawing. Compare this with Win32 programming in which you can spend a great deal of effort in optimizing your application by minimizing the amount of redrawing in the update region. See [Redrawing in the Update Region](/windows/desktop/gdi/redrawing-in-the-update-region) for an example of the type of complexity involved in optimizing redrawing in Win32 applications.
One of the biggest benefits in using retained mode graphics is that WPF can efficiently optimize what needs to be redrawn in the application. Even if you have a complex scene with varying levels of opacity, you generally do not need to write special-purpose code to optimize redrawing. Compare this with Win32 programming in which you can spend a great deal of effort in optimizing your application by minimizing the amount of redrawing in the update region. See [Redrawing in the Update Region](/windows/desktop/gdi/redrawing-in-the-update-region) for an example of the type of complexity involved in optimizing redrawing in Win32 applications.
### Vector Graphics
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses **vector graphics** as its rendering data format. Vector graphics—which include Scalable Vector Graphics (SVG), Windows metafiles (.wmf), and TrueType fonts—store rendering data and transmit it as a list of instructions that describe how to recreate an image using graphics primitives. For example, TrueType fonts are outline fonts that describe a set of lines, curves, and commands, rather than an array of pixels. One of the key benefits of vector graphics is the ability to scale to any size and resolution.
WPF uses **vector graphics** as its rendering data format. Vector graphics—which include Scalable Vector Graphics (SVG), Windows metafiles (.wmf), and TrueType fonts—store rendering data and transmit it as a list of instructions that describe how to recreate an image using graphics primitives. For example, TrueType fonts are outline fonts that describe a set of lines, curves, and commands, rather than an array of pixels. One of the key benefits of vector graphics is the ability to scale to any size and resolution.
Unlike vector graphics, bitmap graphics store rendering data as a pixel-by-pixel representation of an image, pre-rendered for a specific resolution. One of the key differences between bitmap and vector graphic formats is fidelity to the original source image. For example, when the size of a source image is modified, bitmap graphics systems stretch the image, whereas vector graphics systems scale the image, preserving the image fidelity.
@@ -211,16 +211,16 @@ Visual Profiler display output
The other system setting, DPI, describes the size of a screen inch in pixels. Most Windows systems have a DPI of 96, which means a screen inch is 96 pixels. Increasing the DPI setting makes the screen inch larger; decreasing the DPI makes the screen inch smaller. This means that a screen inch isn't the same size as a real-world inch; on most systems, it's probably not. As you increase the DPI, DPI-aware graphics and text become larger because you've increased the size of the screen inch. Increasing the DPI can make text easier to read, especially at high resolutions.
Not all applications are DPI-aware: some use hardware pixels as the primary unit of measurement; changing the system DPI has no effect on these applications. Many other applications use DPI-aware units to describe font sizes, but use pixels to describe everything else. Making the DPI too small or too large can cause layout problems for these applications, because the applications' text scales with the system's DPI setting, but the applications' UI does not. This problem has been eliminated for applications developed using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
Not all applications are DPI-aware: some use hardware pixels as the primary unit of measurement; changing the system DPI has no effect on these applications. Many other applications use DPI-aware units to describe font sizes, but use pixels to describe everything else. Making the DPI too small or too large can cause layout problems for these applications, because the applications' text scales with the system's DPI setting, but the applications' UI does not. This problem has been eliminated for applications developed using WPF.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports automatic scaling by using the device independent pixel as its primary unit of measurement, instead of hardware pixels; graphics and text scale properly without any extra work from the application developer. The following illustration shows an example of how [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] text and graphics are appear at different DPI settings.
WPF supports automatic scaling by using the device independent pixel as its primary unit of measurement, instead of hardware pixels; graphics and text scale properly without any extra work from the application developer. The following illustration shows an example of how WPF text and graphics are appear at different DPI settings.
![Graphics and text at different DPI settings](./media/graphicsmm-dpi-setting-examples.png "graphicsmm_dpi_setting_examples")
Graphics and text at different DPI settings
<a name="visualtreehelper_class"></a>
## VisualTreeHelper Class
The <xref:System.Windows.Media.VisualTreeHelper> class is a static helper class that provides low-level functionality for programming at the visual object level, which is useful in very specific scenarios, such as developing high-performance custom controls. In most case, the higher-level [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] framework objects, such as <xref:System.Windows.Controls.Canvas> and <xref:System.Windows.Controls.TextBlock>, offer greater flexibility and ease of use.
The <xref:System.Windows.Media.VisualTreeHelper> class is a static helper class that provides low-level functionality for programming at the visual object level, which is useful in very specific scenarios, such as developing high-performance custom controls. In most case, the higher-level WPF framework objects, such as <xref:System.Windows.Controls.Canvas> and <xref:System.Windows.Controls.TextBlock>, offer greater flexibility and ease of use.
### Hit Testing
The <xref:System.Windows.Media.VisualTreeHelper> class provides methods for hit testing on visual objects when the default hit test support does not meet your needs. You can use the <xref:System.Windows.Media.VisualTreeHelper.HitTest%2A> methods in the <xref:System.Windows.Media.VisualTreeHelper> class to determine whether a geometry or point coordinate value is within the boundary of a given object, such as a control or graphic element. For example, you could use hit testing to determine whether a mouse click within the bounding rectangle of an object falls within the geometry of a circle You can also choose to override the default implementation of hit testing to perform your own custom hit test calculations.
@@ -235,7 +235,7 @@ Graphics and text at different DPI settings
[!code-csharp[VisualsOverview#101](~/samples/snippets/csharp/VS_Snippets_Wpf/VisualsOverview/CSharp/Window1.xaml.cs#101)]
[!code-vb[VisualsOverview#101](~/samples/snippets/visualbasic/VS_Snippets_Wpf/VisualsOverview/visualbasic/window1.xaml.vb#101)]
In most cases, the logical tree is a more useful representation of the elements in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. Although you do not modify the logical tree directly, this view of the application is useful for understanding property inheritance and event routing. Unlike the visual tree, the logical tree can represent non-visual data objects, such as <xref:System.Windows.Documents.ListItem>. For more information on the logical tree, see [Trees in WPF](../advanced/trees-in-wpf.md).
In most cases, the logical tree is a more useful representation of the elements in a WPF application. Although you do not modify the logical tree directly, this view of the application is useful for understanding property inheritance and event routing. Unlike the visual tree, the logical tree can represent non-visual data objects, such as <xref:System.Windows.Documents.ListItem>. For more information on the logical tree, see [Trees in WPF](../advanced/trees-in-wpf.md).
The <xref:System.Windows.Media.VisualTreeHelper> class provides methods for returning the bounding rectangle of visual objects. You can return the bounding rectangle of a visual object by calling <xref:System.Windows.Media.VisualTreeHelper.GetContentBounds%2A>. You can return the bounding rectangle of all the descendants of a visual object, including the visual object itself, by calling <xref:System.Windows.Media.VisualTreeHelper.GetDescendantBounds%2A>. The following code shows how you would calculate the bounding rectangle of a visual object and all its descendants.