WriteableBitmap Class

July 28, 2014

Provides a BitmapSource that can be written to and updated.

Namespace:  System.Windows.Media.Imaging
Assembly:  System.Windows (in System.Windows.dll)

public sealed class WriteableBitmap : BitmapSource

The WriteableBitmap type exposes the following members.

  NameDescription
Public methodWriteableBitmap(BitmapSource)Initializes a new instance of the WriteableBitmap class using the provided BitmapSource.
Public methodWriteableBitmap(Int32, Int32)Initializes a new instance of the WriteableBitmap class using the provided dimensions.
Public methodWriteableBitmap(UIElement, Transform)Initializes a new instance of the WriteableBitmap class using the provided element and transform.
Top

  NameDescription
Public propertyDispatcherGets the Dispatcher this object is associated with. (Inherited from DependencyObject.)
Public propertyPixelHeightGets the height of the bitmap in pixels. (Inherited from BitmapSource.)
Public propertyPixelsGets an array representing the 2-D texture of the bitmap.
Public propertyPixelWidthGets the width of the bitmap in pixels. (Inherited from BitmapSource.)
Top

  NameDescription
Public methodCheckAccessDetermines whether the calling thread has access to this object. (Inherited from DependencyObject.)
Public methodClearValueClears the local value of a dependency property. (Inherited from DependencyObject.)
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetAnimationBaseValueReturns any base value established for a Windows Phone dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodGetValueReturns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject.)
Public methodInvalidateRequests a draw or redraw of the entire bitmap.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodReadLocalValueReturns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject.)
Public methodRenderRenders an element within the bitmap.
Public methodSetSourceSets the source of the BitmapSource. (Inherited from BitmapSource.)
Public methodSetValueSets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Public Extension MethodLoadJpegDecodes a JPEG stream into a WriteableBitmap object. (Defined by Extensions.)
Public Extension MethodSaveJpegEncodes a WriteableBitmap object into a JPEG stream, with parameters for setting the target width and height of the JPEG file. (Defined by Extensions.)
Top

When you specify a BitmapImage as the parameter for the WriteableBitmap constructor, you must set the CreateOptions property of the BitmapImage before you use it to construct the WriteableBitmap; otherwise, an exception will occur.

Use the WriteableBitmap class to update and render a bitmap on a per-frame basis. The following are some example scenarios where a WriteableBitmap is useful, and a list of the relevant WriteableBitmap API that enables the scenario:

Generate algorithmic imaging content such as a fractal image

  • Construct an initially empty but dimensioned WriteableBitmap using WriteableBitmap(Int32, Int32).

  • Get the pixel array from Pixels.

  • Loop through the array, setting the individual pixel values as integer values that are evaluated as premultiplied ARGB32.

  • Call Invalidate.

  • To display the image in UI, use the WriteableBitmap as the source for an imaging control such as Image, or as the source image for an ImageBrush.

Generate a bitmap snapshot of a visual tree starting from any UIElement

  • Construct a WriteableBitmap using WriteableBitmap.WriteableBitmap.

  • To display the image in UI, use the WriteableBitmap as the source for an imaging control such as Image, or as the source image for an ImageBrush.

  • If you want to render the bitmap multiple times and reuse the instance for additional snapshots, use the Render method. You will need to call Invalidate after Render to render the new image.

  • You have the option to preserve any existing RenderTransform on the UIElement by passing the transform to the constructor, or canceling any existing transform by passing an identity transform or null.

NoteNote:

WriteableBitmap does not capture the content of the WebBrowser control or MediaElement. Furthermore, it captures your app's client area only, meaning it won't capture the app bar or the system tray.

Get a pixel array from an existing image

  • Construct a WriteableBitmap using WriteableBitmap.WriteableBitmap. The original source might have been loaded through URL or through a stream. If from a URL, this URL cannot be cross-domain. See "Protected Content" section of this topic.

  • Get the pixel array from Pixels.

  • Loop through the array, getting the individual pixel values as integer values that are evaluated as premultiplied ARGB32.

WriteableBitmap Pixel Format

When assigning colors to pixels in your bitmap, use pre-multiplied colors. The format used by the WriteableBitmap is ARGB32 (premultiplied RGB). The format becomes relevant if you are populating the integer values in the Pixels array.

The initial pixel values in the dimensioned array are 0, which will render as black if left unaltered.

Protected Content

The WriteableBitmap class has a security model that restricts access to the Pixels array, if the WriteableBitmap is constructed using cross-domain content. For example, a WriteableBitmap that is constructed using a BitmapImage referencing a URL that comes from another domain does not permit access to its Pixels array. The restriction extends to any UI element that uses a URL-derived property for setting some or all of its content.

You can still access PixelHeight and PixelWidth properties of WriteableBitmap even if created from protected content. This information can be useful for determining the natural size of content.

The following example demonstrates how to use a WriteableBitmap to take snapshots of an image and display those snapshots as thumbnails.


<Grid x:Name="LayoutRoot" Background="Transparent">
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>

    <StackPanel Name="mainLayout" Orientation="Vertical" 
        HorizontalAlignment="Stretch" Margin="10" Grid.Row="0">
        <Button Content="Create WriteableBitmap" Height="71" Name="createWB" Click="createWB_Click" />
        <Image Source="Background.png" />
    </StackPanel>

    <!-- thumbnails go here -->
    <StackPanel Name="thumbs" Orientation="Horizontal" 
            Margin="10,10,10,10" Grid.Row="1">
    </StackPanel>
</Grid>



private void createWB_Click(object sender, RoutedEventArgs e)
{
    // Create a WriteableBitmap and set it to the main StackPanel.
    WriteableBitmap wb = new WriteableBitmap(mainLayout, null);

    // Create an image of the desired size and set its source to
    // the WriteableBitmap representing the StackPanel.
    Image image = new Image();
    image.Height = 64;
    image.Margin = new Thickness(10);
    image.Source = wb;

    // Display the WriteableBitmap as a thumbnail. 
    thumbs.Children.Add(image);
}


Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Windows Phone

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Show:
© 2014 Microsoft