--- title: "Drawing Objects Overview" description: Get acquainted with objects and how to use them to efficiently draw shapes, bitmaps, text, and media in Windows Presentation Foundation (WPF). ms.date: "03/30/2017" ms.topic: overview helpviewer_keywords: - "ImageDrawing objects [WPF]" - "GlyphRunDrawing objects [WPF]" - "GeometryDrawing objects [WPF]" - "drawings [WPF], about drawings" - "Drawing objects [WPF]" - "DrawingGroup objects [WPF]" ms.assetid: 9b5ce5c0-e204-4320-a7a8-0b2210d62f88 --- # Drawing Objects Overview This topic introduces objects and describes how to use them to efficiently draw shapes, bitmaps, text, and media. Use objects when you create clip art, paint with a , or use objects. ## What Is a Drawing Object A object describes visible content, such as a shape, bitmap, video, or a line of text. Different types of drawings describe different types of content. The following is a list of the different types of drawing objects. - – Draws a shape. - – Draws an image. - – Draws text. - – Plays an audio or video file. - – Draws other drawings. Use a drawing group to combine other drawings into a single composite drawing. objects are versatile; there are many ways you can use a object. - You can display it as an image by using a and an control. - You can use it with a to paint an object, such as the of a . - You can use it to describe the appearance of a . - You can use it to enumerate the contents of a . WPF provides other types of objects that are capable of drawing shapes, bitmaps, text, and media. For example, you can also use objects to draw shapes, and the control provides another way to add video to your application. So when should you use objects? When you can sacrifice framework level features to gain performance benefits or when you need features. Because objects lack support for [Layout](../advanced/layout.md), input, and focus, they provide performance benefits that make them ideal for describing backgrounds, clip art, and for low-level drawing with objects. Because they are a type object, objects gain several special features, which include the following: they can be declared as [resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define), shared among multiple objects, made read-only to improve performance, cloned, and made thread-safe. For more information about the different features provided by objects, see the [Freezable Objects Overview](../advanced/freezable-objects-overview.md). ## Draw a Shape To draw a shape, you use a . A geometry drawing's property describes the shape to draw, its property describes how the interior of the shape should be painted, and its property describes how its outline should be drawn. The following example uses a to draw a shape. The shape is described by a and two objects. The shape's interior is painted with a and its outline is drawn with a . This example creates the following . ![A GeometryDrawing of two ellipses](./media/graphicsmm-geodraw.jpg "graphicsmm_geodraw") A GeometryDrawing [!code-csharp[DrawingMiscSnippets_snip#GeometryDrawingExampleInline](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/GeometryDrawingExample.cs#geometrydrawingexampleinline)] [!code-xaml[DrawingMiscSnippets_snip#GeometryDrawingExampleInline](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/GeometryDrawingExample.xaml#geometrydrawingexampleinline)] For the complete example, see [Create a GeometryDrawing](how-to-create-a-geometrydrawing.md). Other classes, such as enable you to create more complex shapes by creating curves and arcs. For more information about objects, see the [Geometry Overview](geometry-overview.md). For more information about other ways to draw shapes that don't use objects, see [Shapes and Basic Drawing in WPF Overview](shapes-and-basic-drawing-in-wpf-overview.md). ## Draw an Image To draw an image, you use an . An object's property describes the image to draw, and its property defines the region where the image is drawn. The following example draws an image into a rectangle located at (75,75) that is 100 by 100 pixel. The following illustration shows the created by the example. A gray border was added to show the bounds of the . ![A 100 by 100 ImageDrawing drawn at (75,75)](./media/graphicsmm-simple-imagedrawing-offset.png "graphicsmm_simple_imagedrawing_offset") A 100 by 100 ImageDrawing [!code-csharp[DrawingMiscSnippets_snip#ImageDrawing100by100Inline](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/ImageDrawingExample.cs#imagedrawing100by100inline)] [!code-xaml[DrawingMiscSnippets_snip#ImageDrawing100by100Inline](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/ImageDrawingExample.xaml#imagedrawing100by100inline)] For more information about images, see the [Imaging Overview](imaging-overview.md). ## Play Media (Code Only) > [!NOTE] > Although you can declare a 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 instead. To play an audio or video file, you use a and a . There are two ways to load and play media. The first is to use a and a by themselves, and the second way is to create your own to use with the and . > [!NOTE] > When distributing media with your application, you cannot use a media file as a project resource, like you would an image. In your project file, you must instead set the media type to `Content` and set `CopyToOutputDirectory` to `PreserveNewest` or `Always`. To play media without creating your own , you perform the following steps. 1. Create a object. [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline1](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline1)] 2. Use the method to load the media file. [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline2](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline2)] 3. Create a . [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline3](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline3)] 4. Specify the size and location to draw the media by setting the property of the . [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline4](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline4)] 5. Set the property of the with the you created. [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline5](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline5)] 6. Use the method of the to start playing the media. [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline6](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline6)] The following example uses a and a to play a video file once. [!code-csharp[DrawingMiscSnippets_snip#VideoDrawingExampleInline](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#videodrawingexampleinline)] To gain additional timing control over the media, use a with the and objects. The enables you to specify whether the video should repeat. To use a with a , you perform the following steps: 1. Declare the and set its timing behaviors. [!code-csharp[DrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline1](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#repeatingvideodrawingexampleinline1)] 2. Create a from the . [!code-csharp[DrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline2](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#repeatingvideodrawingexampleinline2)] 3. Create a and use the to set its property. [!code-csharp[DrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline3](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#repeatingvideodrawingexampleinline3)] 4. Create a and assign the to the property of the . [!code-csharp[DrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline4](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#repeatingvideodrawingexampleinline4)] The following example uses a with a and a to play a video repeatedly. [!code-csharp[DrawingMiscSnippets_snip#RepeatingVideoDrawingExampleInline](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/VideoDrawingExample.cs#repeatingvideodrawingexampleinline)] Note that, when you use a , you use the interactive returned from the property of the to control media playback instead of the interactive methods of . ## Draw Text To draw text, you use a and a . The following example uses a to draw the text "Hello World". [!code-csharp[DrawingMiscSnippets_snip#GlyphRunDrawingExampleInline](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/GlyphRunDrawingExample.cs#glyphrundrawingexampleinline)] [!code-xaml[DrawingMiscSnippets_snip#GlyphRunDrawingExampleInline](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/GlyphRunExample.xaml#glyphrundrawingexampleinline)] A is a low-level object intended for use with fixed-format document presentation and print scenarios. A simpler way to draw text to the screen is to use a or a . For more information about , see the [Introduction to the GlyphRun Object and Glyphs Element](../advanced/introduction-to-the-glyphrun-object-and-glyphs-element.md) overview. ## Composite Drawings A enables you to combine multiple drawings into a single composite drawing. By using a , you can combine shapes, images, and text into a single object. The following example uses a to combine two objects and an object. This example produces the following output. ![A DrawingGroup with multiple drawings](./media/graphicsmm-simple.jpg "graphicsmm_simple") A composite drawing [!code-csharp[DrawingMiscSnippets_snip#GraphicsMMSimpleDrawingGroupExample](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/DrawingGroupExample.cs#graphicsmmsimpledrawinggroupexample)] [!code-xaml[DrawingMiscSnippets_snip#GraphicsMMSimpleDrawingGroupExample](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/DrawingGroupExample.xaml#graphicsmmsimpledrawinggroupexample)] A also enables you to apply opacity masks, transforms, bitmap effects, and other operations to its contents. operations are applied in the following order: , , , , , and then . The following illustration shows the order in which operations are applied. ![DrawingGroup order of operations](./media/graphcismm-drawinggroup-order.png "graphcismm_drawinggroup_order") Order of DrawingGroup operations The following table describes the properties you can use to manipulate a object's contents. |Property|Description|Illustration| |--------------|-----------------|------------------| ||Alters the opacity of selected portions of the contents. For an example, see [How to: Control the Opacity of a Drawing](/previous-versions/dotnet/netframework-3.5/ms748242(v=vs.90)).|![A DrawingGroup with an opacity mask](./media/graphicsmm-opmask.png "graphicsmm_opmask")| ||Uniformly changes the opacity of the contents. Use this property to make a transparent or partially transparent. For an example, see [How to: Apply an Opacity Mask to a Drawing](/previous-versions/dotnet/netframework-3.5/ms753195(v=vs.90)).|![DrawingGroups with different opacity settings](./media/graphicsmm-opacity.png "graphicsmm_opacity")| ||Applies a to the contents. For an example, see [How to: Apply a BitmapEffect to a Drawing](/previous-versions/dotnet/netframework-3.5/ms752341(v=vs.90)).|![DrawingGroup with a BlurBitmapEffect](./media/graphicsmm-bitmap.png "graphicsmm_bitmap")| ||Clips the contents to a region you describe using a . For an example, see [How to: Clip a Drawing](/previous-versions/dotnet/netframework-3.5/ms743068(v=vs.90)) .|![DrawingGroup with a defined clip region](./media/graphicsmm-clipgeom.png "graphicsmm_clipgeom")| ||Snaps device independent pixels to device pixels along the specified guidelines. This property is useful for ensuring that finely detailed graphics render sharply on low-DPI displays. For an example, see [Apply a GuidelineSet to a Drawing](how-to-apply-a-guidelineset-to-a-drawing.md).|![A DrawingGroup with and without a GuidelineSet](./media/graphicsmm-drawinggroup-guidelineset.png "graphicsmm_drawinggroup_guidelineset")| ||Transforms the contents. For an example, see [How to: Apply a Transform to a Drawing](/previous-versions/dotnet/netframework-3.5/ms742304(v=vs.90)).|![A rotated DrawingGroup](./media/graphicsmm-rotate.png "graphicsmm_rotate")| ## Display a Drawing as an Image To display a with an control, use a as the control's and set the object's property to the drawing you want to display. The following example uses a and an control to display a . This example produces the following output. ![A GeometryDrawing of two ellipses](./media/graphicsmm-geodraw.jpg "graphicsmm_geodraw") A DrawingImage [!code-csharp[DrawingMiscSnippets_snip#DrawingImageExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/DrawingImageExample.cs#drawingimageexamplewholepage)] [!code-xaml[DrawingMiscSnippets_snip#DrawingImageExampleWholePage](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/DrawingImageExample.xaml#drawingimageexamplewholepage)] ## Paint an Object with a Drawing A is a type of brush that paints an area with a drawing object. You can use it to paint just about any graphical object with a drawing. The property of a describes its . To render a with a , add it to the brush using the brush's property and use the brush to paint a graphical object, such as a control or panel. The following examples uses a to paint the of a with a pattern created from a . This example produces the following output. ![A tiled DrawingBrush](./media/graphicsmm-drawingbrush-geometrydrawing.png "graphicsmm_drawingbrush_geometrydrawing") A GeometryDrawing used with a DrawingBrush [!code-csharp[DrawingMiscSnippets_snip#DrawingBrushExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/DrawingBrushExample.cs#drawingbrushexamplewholepage)] [!code-xaml[DrawingMiscSnippets_snip#DrawingBrushExampleWholePage](~/samples/snippets/xaml/VS_Snippets_Wpf/DrawingMiscSnippets_snip/XAML/DrawingBrushExample.xaml#drawingbrushexamplewholepage)] The class provides a variety of options for stretching and tiling its content. For more information about , see the [Painting with Images, Drawings, and Visuals](painting-with-images-drawings-and-visuals.md) overview. ## Render a Drawing with a Visual A is a type of visual object designed to render a drawing. Working directly at the visual layer is an option for developers who want to build a highly customized graphical environment, and is not described in this overview. For more information, see the [Using DrawingVisual Objects](using-drawingvisual-objects.md) overview. ## DrawingContext Objects The class enables you to populate a or a with visual content. Many such lower-level graphics objects use a because it describes graphical content very efficiently. Although the draw methods appear similar to the draw methods of the type, they are actually very different. is used with a retained mode graphics system, while the type is used with an immediate mode graphics system. When you use a object's draw commands, you are actually storing a set of rendering instructions (although the exact storage mechanism depends on the type of object that supplies the ) that will later be used by the graphics system; you are not drawing to the screen in real-time. For more information about how the Windows Presentation Foundation (WPF) graphics system works, see the [WPF Graphics Rendering Overview](wpf-graphics-rendering-overview.md). You never directly instantiate a ; you can, however, acquire a drawing context from certain methods, such as and . ## Enumerate the Contents of a Visual In addition to their other uses, objects also provide an object model for enumerating the contents of a . The following example uses the method to retrieve the value of a and enumerate it. [!code-csharp[DrawingMiscSnippets_snip#GraphicsMMRetrieveDrawings](~/samples/snippets/csharp/VS_Snippets_Wpf/DrawingMiscSnippets_snip/CSharp/EnumerateDrawingsExample.xaml.cs#graphicsmmretrievedrawings)] ## See also - - - [2D Graphics and Imaging](../advanced/optimizing-performance-2d-graphics-and-imaging.md) - [Painting with Images, Drawings, and Visuals](painting-with-images-drawings-and-visuals.md) - [Geometry Overview](geometry-overview.md) - [Shapes and Basic Drawing in WPF Overview](shapes-and-basic-drawing-in-wpf-overview.md) - [WPF Graphics Rendering Overview](wpf-graphics-rendering-overview.md) - [Freezable Objects Overview](../advanced/freezable-objects-overview.md) - [How-to Topics](drawings-how-to-topics.md)