In Silverlight, you have several options for displaying images such as pictures and diagrams. This QuickStart describes how to integrate images into your Silverlight-based applications.

This QuickStart contains the following sections:

Image and ImageBrush

To render an image, you can use either the Image or the ImageBrush object. The following example shows how to create an image by using the Image object.

XAML

<Image Width="400" Source="licorice.JPG" />

In this example, the Source property specifies the location of the image that you want to display. You can set the Source by specifying an absolute URL (for example, http://contoso.com/myPicture.jpg) or by specifying a URL that is relative to the XAP file of your application. For the previous example, you would put the XAP file in the same folder as licorice.jpg.

The ImageBrush object enables you to use an image to paint an area that takes a Brush object. For example, ImageBrush can be used for the value of the Background property of a Panel. For more information about brushes, see Brushes Overview in the Silverlight documentation on MSDN.

The following example shows how to use the licorice image to paint the inside of some text.

XAML

<!-- TextBlock with an image brush applied to the text. -->
<TextBlock Margin="20" FontFamily="Verdana" FontSize="86"
FontWeight="Bold">
LICORICE
<TextBlock.Foreground>
  <ImageBrush ImageSource="licorice.JPG"/>
</TextBlock.Foreground>
</TextBlock>

Stretching an Image

If you do not set the Width or Height values of an Image, it is displayed with the dimensions of the image specified by the Source. Setting the Width and Height 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 image 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.

Cropping an Image

You can use the Clip property to clip an area from the image output. You set the Clip property to a Geometry, which means that you can clip a variety of geometric shapes from your image (for example, an ellipse, line, or complex path). For more information about how to create geometries, see Geometries Overview in the Silverlight documentation on MSDN.

The following example shows how to use an EllipseGeometry as the clip region for an image. In this example, 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 is displayed.

XAML

<Grid x:Name="LayoutRoot" Background="White">
  <Image Source="Water_lilies.jpg"
    Width="200" Height="150">
    <Image.Clip>
      <EllipseGeometry RadiusX="100" RadiusY="75" Center="100,75"/>
    </Image.Clip>
  </Image>
</Grid>

The following illustration shows the output from the example.

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. The following example shows how to apply a radial gradient to an image so that it fades out on the edges (vignette effect).

XAML

<Image Source="licorice.jpg" >
    <Image.OpacityMask>
        <RadialGradientBrush GradientOrigin="0.5,0.5" Center="0.5,0.5"
         RadiusX="0.5" RadiusY="0.5">
            <!-- These Gradient Stop colors are only changing the
                 alpha values so the image fades out toward the edges. -->
            <GradientStop Color="#ffffffff" Offset="0.5" />
            <GradientStop Color="#00ffffff" Offset="0.8" />
        </RadialGradientBrush>

    </Image.OpacityMask>
</Image>

Creating WritableBitmaps

A WritableBitmap provides a BitmapSource which can be modified. This enables you to alter images on the fly and re-render the updated image.

You can pass a BitmapSource, the dimensions of a new bitmap, or a UIElement to the WritableBitmap constructor. Passing in a UIElement will create a bitmap image of the visual element. For example, if you wanted a bitmap of the entire visual tree, you could pass in the root UIElement to the constructor.

The following example shows how to create a WritableBitmap image from a video frame and how to modify the captured bitmap image. A MediaElement and a ScaleTransform are passed to the WritableBitmap constructor. The transform scales down the image by 50%. The "Modify Pixels" button on the sample iterates through the Pixels array of the bitmap and sets each forth pixel to white. The modified bitmap is then re-rendered.

XAML

<StackPanel Orientation="Horizontal" />

    <Border  Width="320" Height="240" 
             Margin="5" BorderBrush="Black" 
             BorderThickness="1" >  
       <MediaElement x:Name="media" Source="xbox.wmv" />
    </Border>

    <Border  Width="160" Height="120" 
             Margin="5" BorderBrush="Black" 
             BorderThickness="1" >
       <Image Name="CapturedImage" Stretch="None" />
    </Border >

</StackPanel >

C#

private void CaptureImage(object sender, RoutedEventArgs e)
{
    // Transform to scale the image by 50%. 
    ScaleTransform transform = new ScaleTransform();
    transform.ScaleX = .5;
    transform.ScaleY = .5;

    // Get bitmap image from the current frame of video.
    WriteableBitmap bitmap = new WriteableBitmap(media, transform);

    // Set the Image object, defined in XAML, to the new bitmap.
    CapturedImage.Source = bitmap;
}

private void ModifyPixels(object sender, RoutedEventArgs e)
{
    // Get WriteableBitmap.
    if (CapturedImage.Source != null)
    {
        WriteableBitmap bitmap =
             new WriteableBitmap((BitmapSource)CapturedImage.Source);

        // Iterate through each pixel.
        for (int x = 0; x < bitmap.Pixels.Length; x++)
        {
            // Set every 4th pixel.
            if (x % 4 == 0)
            {
                bitmap.Pixels[x] = 0;
            }
        }

        // Set Image object, defined in XAML, to the modified bitmap.
        CapturedImage.Source = bitmap;
    }
}

Zooming and Panning Images

Deep Zoom is a technology that enables zooming into and panning across large images or collections of high-resolution images.

To see an example of a Web site that uses Deep Zoom, see Deep Zoom example. To zoom in and out, use the mouse wheel. To move the images, drag with the mouse.

To learn more about Deep Zoom, see QuickStart: Deep Zoom.

What's Next

Next, we'll learn about Silverlight scalable vector graphics, such shapes and lines: Silverlight Graphics.

See Also

• Graphics
• QuickStart: Deep Zoom
• Deep Zoom Overview
• MediaElement States
• Imaging