Silverlight Imaging Overview

This overview provides an introduction to working with images in Microsoft Silverlight.

This topic contains the following sections:

• Creating an Image
• Stretching an Image
• Cropping an Image
• Applying an OpacityMask
• Painting with an Image (ImageBrush)

Creating an Image

To render an image, you can use either the Image or the ImageBrush object. The following example shows how to create an image that is positioned 30 pixels from the left and top of the Canvas.

  ...
  <Image
    Source="myPicture.png"
    Canvas.Left="30" Canvas.Top="30" />
  ...

In this example, the Source property is used to specify the location of the image you want to display. If you are not accessing cross-domain sources, you might consider using SetSource instead of setting Source directly. This gives you the advantage of being able to track the download. Also, you can download multiple images as a package and access parts from within the package. See SetSource for an example.

You use the ImageBrush to use an image to paint an area that takes a brush. For example, ImageBrush can be used for the value of the Background property of a Canvas or InkPresenter. See Painting with an Image (ImageBrush) for more information on using ImageBrush.

Stretching an Image

If you do not set a Width or Height value of an Image (as in the previous example), it will display with the natural dimensions of the image specified by the Source. Setting the Height and Width creates a containing rectangular area that the image is displayed in. You can specify how the image fills this containing area by using the Stretch property. The Stretch property accepts the following values, which the Stretch enumeration defines:

• None: The image does not stretch to fill the output dimensions.

• Uniform: The image is scaled to fit the output dimensions. However, the aspect ratio of the content is preserved. This is the default value.

• UniformToFill: The image is scaled so that it completely fills the output area but preserves its original aspect ratio.

• Fill: The video is scaled to fit the output dimensions. Because the content's height and width are scaled independently, the original aspect ratio of the image might not be preserved. That is, the image might be distorted to completely fill the output area.

The following illustration shows the different Stretch settings.

Stretch settings

The following example displays an Image that fills a 300-by-300 pixel output area but preserves its original aspect ratio, because the Stretch property is set to UniformToFill.

<Canvas xmlns="https://schemas.microsoft.com/client/2007"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  Width="300" Height="300" x:Name="rootCanvas" Background="Gray">
  
  <Image Source="myImage.jpg" Stretch="UniformToFill" Width="300" Height="300" />
</Canvas>

Note   When only one constraint attribute is set (for example, Height), the other attribute (in this case, Width) is automatically calculated based on the aspect ratio of the natural image. Because of this behavior, setting the Stretch property will not change the behavior unless it is set to None.

Cropping an Image

You can crop an image by using the Clip property to clip out an area of the image's output. You set the Clip property to a Geometry, which means that you can clip out a variety of geometric shapes from your image (for example, ellipse, line, or complex path). See Geometry Overview for more information about creating geometries.

The following example shows how to use an EllipseGeometry as the clip region for an image. An Image object is defined with a Width of 200 and a Height of 150. An EllipseGeometry with a RadiusX value of 100, a RadiusY value of 75, and a Center value of 100,75 is set to the Clip property of the image. Only the part of the image that is within the area of the ellipse will be displayed. The following illustration shows the output from the example.

An EllipseGeometry used to clip an image

<Canvas  
  xmlns="https://schemas.microsoft.com/client/2007"  
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">
  <Image
    Source="sampleImages/Waterlilies.jpg"
    Width="200" Height="150">
    <Image.Clip>
      <EllipseGeometry
        RadiusX="100"
        RadiusY="75"
        Center="100,75"/>
    </Image.Clip>
  </Image> 
</Canvas>

Note   A variety of objects can be clipped besides Image. See How to: Crop an Object for more information.

Note   An alternate way to create a cropping effect is to apply an OpacityMask by using a gradient. In this case, because you are using Opacity, you are able to create a blurry edge to your cropping. See OpacityMask for more information.

Applying an OpacityMask

You can apply an OpacityMask to an image to create a variety of opacity-related photo masking techniques such as vignette effects, as shown in the following illustration. See OpacityMask for more information.

Example of a vignette effect created by an OpacityMask

Painting with an Image (ImageBrush)

You use ImageBrush to use an image to paint an area that takes a brush. For example, ImageBrush can be used for the value of the Background property of a Canvas or InkPresenter. See Brushes Overview for more information about brushes.

The following XAML example shows how to set the Foreground property to an ImageBrush whose image is used as the fill for the TextBlock's rendered text.

<!-- TextBlock with an image brush applied to the text. -->
<TextBlock
  Canvas.Top="120"
  FontFamily="Verdana"
  FontSize="72"
  FontStyle="Italic"
  FontWeight="Bold">
  SHRUBBERY
  <TextBlock.Foreground>
    <ImageBrush ImageSource="forest.jpg"/>
  </TextBlock.Foreground>
</TextBlock>

The following illustration shows the results of this XAML example.

The output of the code

See Also

Brushes Overview
VideoBrush Overview
Overviews and How-to Topics