WriteableBitmap Class
 

Provides a BitmapSource that can be written to and updated.

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

SystemObject
   System.Windows.ThreadingDispatcherObject
     System.WindowsDependencyObject
       System.WindowsFreezable
         System.Windows.Media.AnimationAnimatable
           System.Windows.MediaImageSource
             System.Windows.Media.ImagingBitmapSource
              System.Windows.Media.ImagingWriteableBitmap

public sealed class WriteableBitmap : BitmapSource
public ref class WriteableBitmap sealed : BitmapSource
[<Sealed>]
type WriteableBitmap = 
    class
        inherit BitmapSource
    end
Public NotInheritable Class WriteableBitmap
	Inherits BitmapSource
NameDescription
System_CAPS_pubmethod WriteableBitmap

Initializes a new instance of the WriteableBitmap class using the given BitmapSource.

System_CAPS_pubmethod WriteableBitmap

Initializes a new instance of the WriteableBitmap class with the specified parameters.

NameDescription
System_CAPS_pubproperty

Gets a pointer to the back buffer.

System_CAPS_pubproperty

Gets a value indicating the number of bytes in a single row of pixel data.

System_CAPS_pubproperty

Gets a value that indicates whether the object can be made unmodifiable. (Inherited from Freezable.)

System_CAPS_pubproperty

Gets the DependencyObjectType that wraps the CLR type of this instance. (Inherited from DependencyObject.)

System_CAPS_pubproperty

Gets the Dispatcher this DispatcherObject is associated with. (Inherited from DispatcherObject.)

System_CAPS_pubproperty

Gets the horizontal dots per inch (dpi) of the image. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the vertical dots per inch (dpi) of the image. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the native PixelFormat of the bitmap data. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets a value that indicates whether one or more AnimationClock objects is associated with any of this object's dependency properties.(Inherited from Animatable.)

System_CAPS_pubproperty

Gets the height of the source bitmap in device-independent units (1/96th inch per unit). (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets a value that indicates whether the BitmapSource content is currently downloading. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets a value that indicates whether the object is currently modifiable. (Inherited from Freezable.)

System_CAPS_pubproperty

Gets a value that indicates whether this instance is currently sealed (read-only).(Inherited from DependencyObject.)

System_CAPS_pubproperty

Gets the metadata that is associated with this bitmap image. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the color palette of the bitmap, if one is specified. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the height of the bitmap in pixels. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the width of the bitmap in pixels. (Inherited from BitmapSource.)

System_CAPS_pubproperty

Gets the width of the bitmap in device-independent units (1/96th inch per unit). (Inherited from BitmapSource.)

NameDescription
System_CAPS_pubmethod AddDirtyRect

Specifies the area of the bitmap that changed.

System_CAPS_pubmethod ApplyAnimationClock

Applies an AnimationClock to the specified DependencyProperty. If the property is already animated, the SnapshotAndReplace handoff behavior is used.(Inherited from Animatable.)

System_CAPS_pubmethod ApplyAnimationClock

Applies an AnimationClock to the specified DependencyProperty. If the property is already animated, the specified HandoffBehavior is used.(Inherited from Animatable.)

System_CAPS_pubmethod BeginAnimation

Applies an animation to the specified DependencyProperty. The animation is started when the next frame is rendered. If the specified property is already animated, the SnapshotAndReplace handoff behavior is used.(Inherited from Animatable.)

System_CAPS_pubmethod BeginAnimation

Applies an animation to the specified DependencyProperty. The animation is started when the next frame is rendered. If the specified property is already animated, the specified HandoffBehavior is used. (Inherited from Animatable.)

System_CAPS_pubmethod CheckAccess

Determines whether the calling thread has access to this DispatcherObject.(Inherited from DispatcherObject.)

System_CAPS_pubmethod ClearValue

Clears the local value of a property. The property to be cleared is specified by a DependencyProperty identifier. (Inherited from DependencyObject.)

System_CAPS_pubmethod ClearValue

Clears the local value of a read-only property. The property to be cleared is specified by a DependencyPropertyKey. (Inherited from DependencyObject.)

System_CAPS_pubmethod Clone

Creates a modifiable clone of this WriteableBitmap, making deep copies of this object's values. When copying dependency properties, this method copies resource references and data bindings (but they might no longer resolve) but not animations or their current values.

System_CAPS_pubmethod CloneCurrentValue

Creates a modifiable clone of this ByteAnimationUsingKeyFrames object, making deep copies of this object's current values. Resource references, data bindings, and animations are not copied, but their current values are.

System_CAPS_pubmethod CoerceValue

Coerces the value of the specified dependency property. This is accomplished by invoking any CoerceValueCallback function specified in property metadata for the dependency property as it exists on the calling DependencyObject.(Inherited from DependencyObject.)

System_CAPS_pubmethod CopyPixels

Copies the bitmap pixel data into an array of pixels with the specified stride, starting at the specified offset.(Inherited from BitmapSource.)

System_CAPS_pubmethod CopyPixels

Copies the bitmap pixel data within the specified rectangle into an array of pixels that has the specified stride starting at the specified offset.(Inherited from BitmapSource.)

System_CAPS_pubmethod CopyPixels

Copies the bitmap pixel data within the specified rectangle (Inherited from BitmapSource.)

System_CAPS_pubmethod Equals

Determines whether a provided DependencyObject is equivalent to the current DependencyObject.(Inherited from DependencyObject.)

System_CAPS_pubmethod Freeze

Makes the current object unmodifiable and sets its property to true. (Inherited from Freezable.)

System_CAPS_pubmethod GetAnimationBaseValue

Returns the non-animated value of the specified DependencyProperty.(Inherited from Animatable.)

System_CAPS_pubmethod GetAsFrozen

Creates a frozen copy of the Freezable, using base (non-animated) property values. Because the copy is frozen, any frozen sub-objects are copied by reference. (Inherited from Freezable.)

System_CAPS_pubmethod GetCurrentValueAsFrozen

Creates a frozen copy of the Freezable using current property values. Because the copy is frozen, any frozen sub-objects are copied by reference.(Inherited from Freezable.)

System_CAPS_pubmethod GetHashCode

Gets a hash code for this DependencyObject.(Inherited from DependencyObject.)

System_CAPS_pubmethod GetLocalValueEnumerator

Creates a specialized enumerator for determining which dependency properties have locally set values on this DependencyObject. (Inherited from DependencyObject.)

System_CAPS_pubmethod GetType

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethod GetValue

Returns the current effective value of a dependency property on this instance of a DependencyObject. (Inherited from DependencyObject.)

System_CAPS_pubmethod InvalidateProperty

Re-evaluates the effective value for the specified dependency property(Inherited from DependencyObject.)

System_CAPS_pubmethod Lock

Reserves the back buffer for updates.

System_CAPS_pubmethod ReadLocalValue

Returns the local value of a dependency property, if it exists. (Inherited from DependencyObject.)

System_CAPS_pubmethod SetCurrentValue

Sets the value of a dependency property without changing its value source. (Inherited from DependencyObject.)

System_CAPS_pubmethod SetValue

Sets the local value of a dependency property, specified by its dependency property identifier. (Inherited from DependencyObject.)

System_CAPS_pubmethod SetValue

Sets the local value of a read-only dependency property, specified by the DependencyPropertyKey identifier of the dependency property. (Inherited from DependencyObject.)

System_CAPS_protmethod ShouldSerializeProperty

Returns a value that indicates whether serialization processes should serialize the value for the provided dependency property.(Inherited from DependencyObject.)

System_CAPS_pubmethod ToString

Creates a string representation of this object based on the current culture. (Inherited from ImageSource.)

System_CAPS_pubmethod ToString

Creates a string representation of this object based on the IFormatProvider passed in. If the provider is null, the is used. (Inherited from ImageSource.)

System_CAPS_pubmethod TryLock

Attempts to lock the bitmap, waiting for no longer than the specified length of time.

System_CAPS_pubmethod Unlock

Releases the back buffer to make it available for display.

System_CAPS_pubmethod VerifyAccess

Enforces that the calling thread has access to this DispatcherObject.(Inherited from DispatcherObject.)

System_CAPS_pubmethod WritePixels

Updates the pixels in the specified region of the bitmap.

System_CAPS_pubmethod WritePixels

Updates the pixels in the specified region of the bitmap.

System_CAPS_pubmethod WritePixels

Updates the pixels in the specified region of the bitmap.

System_CAPS_pubmethod WritePixels

Updates the pixels in the specified region of the bitmap.

NameDescription
System_CAPS_pubevent Changed

Occurs when the Freezable or an object it contains is modified. (Inherited from Freezable.)

System_CAPS_pubevent DecodeFailed

Occurs when the image fails to load, due to a corrupt image header.(Inherited from BitmapSource.)

System_CAPS_pubevent DownloadCompleted

Occurs when the bitmap content has been completely downloaded.(Inherited from BitmapSource.)

System_CAPS_pubevent DownloadFailed

Occurs when the bitmap content failed to download.(Inherited from BitmapSource.)

System_CAPS_pubevent DownloadProgress

Occurs when the download progress of the bitmap content has changed.(Inherited from BitmapSource.)

NameDescription
System_CAPS_pubinterface System_CAPS_privmethod IFormattableToString

Formats the value of the current instance using the specified format.(Inherited from ImageSource.)

Use the WriteableBitmap class to update and render a bitmap on a per-frame basis. This is useful for generating algorithmic content, such as a fractal image, and for data visualization, such as a music visualizer.

The WriteableBitmap class uses two buffers. The back buffer is allocated in system memory and accumulates content that is not currently displayed. The front buffer is allocated in system memory and contains the content that is currently displayed. The rendering system copies the front buffer to video memory for display.

Two threads use these buffers. The user interface (UI) thread generates the UI but does not present it to the screen. The UI thread responds to user input, timers, and other events. An application can have multiple UI threads. The render thread composes and renders changes from the UI thread. There is only one render thread per application.

The UI thread writes content to the back buffer. The render thread reads content from the front buffer and copies it to video memory. Changes to the back buffer are tracked with changed rectangular regions.

Call one of the WritePixels overloads to update and display content in the back buffer automatically.

For greater control over updates, and for multi-threaded access to the back buffer, use the following workflow.

  1. Call the Lock method to reserve the back buffer for updates.

  2. Obtain a pointer to the back buffer by accessing the property.

  3. Write changes to the back buffer. Other threads may write changes to the back buffer when the WriteableBitmap is locked.

  4. Call the AddDirtyRect method to indicate areas that have changed.

  5. Call the Unlock method to release the back buffer and allow presentation to the screen.

When updates are sent to the rendering thread, the rendering thread copies the changed rectangles from the back buffer to the front buffer. The rendering system controls this exchange to avoid deadlocks and redraw artifacts, such as "tearing".

The following example demonstrates how a WriteableBitmap can be used as the source of an Image to draw pixels when the mouse moves.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Media;
using System.Windows.Media.Imaging;
using System.Windows.Input;

namespace WriteableBitmapDemo
{
    class Program
    {
        static WriteableBitmap writeableBitmap;
        static Window w;
        static Image i;

        [STAThread]
        static void Main(string[] args)
        {
            i = new Image();
            RenderOptions.SetBitmapScalingMode(i, BitmapScalingMode.NearestNeighbor);
            RenderOptions.SetEdgeMode(i, EdgeMode.Aliased);

            w = new Window();
            w.Content = i;
            w.Show();

            writeableBitmap = new WriteableBitmap(
                (int)w.ActualWidth, 
                (int)w.ActualHeight, 
                96, 
                96, 
                PixelFormats.Bgr32, 
                null);

            i.Source = writeableBitmap;

            i.Stretch = Stretch.None;
            i.HorizontalAlignment = HorizontalAlignment.Left;
            i.VerticalAlignment = VerticalAlignment.Top;

            i.MouseMove += new MouseEventHandler(i_MouseMove);
            i.MouseLeftButtonDown += 
                new MouseButtonEventHandler(i_MouseLeftButtonDown);
            i.MouseRightButtonDown += 
                new MouseButtonEventHandler(i_MouseRightButtonDown);

            w.MouseWheel += new MouseWheelEventHandler(w_MouseWheel);

            Application app = new Application();
            app.Run();
        }

        // The DrawPixel method updates the WriteableBitmap by using
        // unsafe code to write a pixel into the back buffer.
        static void DrawPixel(MouseEventArgs e)
        {
            int column = (int)e.GetPosition(i).X;
            int row = (int)e.GetPosition(i).Y;

            // Reserve the back buffer for updates.
            writeableBitmap.Lock();

            unsafe
            {
                // Get a pointer to the back buffer.
                int pBackBuffer = (int)writeableBitmap.BackBuffer;

                // Find the address of the pixel to draw.
                pBackBuffer += row * writeableBitmap.BackBufferStride;
                pBackBuffer += column * 4;

                // Compute the pixel's color.
                int color_data = 255 << 16; // R
                color_data |= 128 << 8;   // G
                color_data |= 255 << 0;   // B

                // Assign the color data to the pixel.
                *((int*) pBackBuffer) = color_data;
            }

            // Specify the area of the bitmap that changed.
            writeableBitmap.AddDirtyRect(new Int32Rect(column, row, 1, 1));

            // Release the back buffer and make it available for display.
            writeableBitmap.Unlock();
        }

        static void ErasePixel(MouseEventArgs e)
        {
            byte[] ColorData = { 0, 0, 0, 0 }; // B G R

            Int32Rect rect = new Int32Rect(
                    (int)(e.GetPosition(i).X), 
                    (int)(e.GetPosition(i).Y), 
                    1, 
                    1);

            writeableBitmap.WritePixels( rect, ColorData, 4, 0);
        }

        static void i_MouseRightButtonDown(object sender, MouseButtonEventArgs e)
        {
            ErasePixel(e);
        }

        static void i_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
        {
            DrawPixel(e);
        }

        static void i_MouseMove(object sender, MouseEventArgs e)
        {
            if (e.LeftButton == MouseButtonState.Pressed)
            {
                DrawPixel(e);
            }
            else if (e.RightButton == MouseButtonState.Pressed)
            {
                ErasePixel(e);
            }
        }

        static void w_MouseWheel(object sender, MouseWheelEventArgs e)
        {
            System.Windows.Media.Matrix m = i.RenderTransform.Value;

            if (e.Delta > 0)
            {
                m.ScaleAt(
                    1.5, 
                    1.5, 
                    e.GetPosition(w).X, 
                    e.GetPosition(w).Y);
            }
            else
            {
                m.ScaleAt(
                    1.0 / 1.5, 
                    1.0 / 1.5, 
                    e.GetPosition(w).X, 
                    e.GetPosition(w).Y);
            }

            i.RenderTransform = new MatrixTransform(m);
        }
    }
}
.NET Framework
Available since 3.0
Silverlight
Available since 3.0
Windows Phone Silverlight
Available since 7.0

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

Return to top