WriteableBitmap Class
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Provides a BitmapSource that can be written to and updated.
System.Windows::DependencyObject
System.Windows.Media::ImageSource
System.Windows.Media.Imaging::BitmapSource
System.Windows.Media.Imaging::WriteableBitmap
Assembly: System.Windows (in System.Windows.dll)
The WriteableBitmap type exposes the following members.
| Name | Description | |
|---|---|---|
 | WriteableBitmap(BitmapSource) | Initializes a new instance of the WriteableBitmap class using the provided BitmapSource. |
| WriteableBitmap(Int32, Int32) | Initializes a new instance of the WriteableBitmap class using the provided dimensions. |
| WriteableBitmap(UIElement, Transform) | Initializes a new instance of the WriteableBitmap class using the provided element and transform. |
| Name | Description | |
|---|---|---|
 | Dispatcher | Gets the Dispatcher this object is associated with. (Inherited from DependencyObject.) |
| PixelHeight | Gets the height of the bitmap in pixels. (Inherited from BitmapSource.) |
| Pixels | Gets an array representing the 2-D texture of the bitmap. |
| PixelWidth | Gets the width of the bitmap in pixels. (Inherited from BitmapSource.) |
| Name | Description | |
|---|---|---|
| CheckAccess | Determines whether the calling thread has access to this object. (Inherited from DependencyObject.) |
| ClearValue | Clears the local value of a dependency property. (Inherited from DependencyObject.) |
| Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
 | Finalize | Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.) |
| GetAnimationBaseValue | Returns any base value established for a Windows Phone dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject.) |
| GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
| GetType | Gets the Type of the current instance. (Inherited from Object.) |
| GetValue | Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject.) |
| Invalidate | Requests a draw or redraw of the entire bitmap. |
| MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
| ReadLocalValue | Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject.) |
| Render | Renders an element within the bitmap. |
| SetSource | Sets the source of the BitmapSource. (Inherited from BitmapSource.) |
| SetValue | Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject.) |
| ToString | Returns a string that represents the current object. (Inherited from Object.) |
| Name | Description | |
|---|---|---|
 | LoadJpeg | Decodes a JPEG stream into a WriteableBitmap object. (Defined by Extensions.) |
| SaveJpeg | Encodes a WriteableBitmap object into a JPEG stream, with parameters for setting the target width and height of the JPEG file. (Defined by Extensions.) |
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.
 Note: |
|---|
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); }