BitmapSource BitmapSource BitmapSource Class

Provides a source object for properties that use a bitmap-format image source.

Syntax

Declaration

public class BitmapSourcepublic class BitmapSourcePublic Class BitmapSource

Inheritance Hierarchy

Remarks

Important

You don't typically use or create a BitmapSource type directly, that's why you don't see code examples on this page. It's more common to create a BitmapImage and use that as a value. For code examples and more info, see the reference page for BitmapImage.

ImageSource and BitmapSource are intermediate base classes for BitmapImage. For more info on how to create an image source to use for Source and ImageSource, see Image and ImageBrush and BitmapImage.

BitmapSource derived classes

BitmapSource is the parent class for BitmapImage and WriteableBitmap.

Constructors summary

Provides base class initialization behavior for BitmapSource -derived classes.

Properties summary

Gets the height of the bitmap in pixels.

Identifies the PixelHeight dependency property.

Gets the width of the bitmap in pixels.

Identifies the PixelWidth dependency property.

Methods summary

Sets the source image for a BitmapSource by accessing a stream. Most callers should use SetSourceAsync(IRandomAccessStream) instead.

Sets the source image for a BitmapSource by accessing a stream and processing the result asynchronously.

Constructors

  • BitmapSource()
    BitmapSource()
    BitmapSource()
    BitmapSource()

    Provides base class initialization behavior for BitmapSource -derived classes.

    protected BitmapSource()protected New()Protected Sub New()protected BitmapSource()

Properties

  • PixelHeight
    PixelHeight
    PixelHeight
    PixelHeight

    Gets the height of the bitmap in pixels.

    public int PixelHeight { get; }public int PixelHeight { get; }Public ReadOnly Property PixelHeight As intpublic int PixelHeight { get; }

    Property Value

    • int
      int
      int

      The height of the bitmap in pixels.

  • PixelHeightProperty
    PixelHeightProperty
    PixelHeightProperty
    PixelHeightProperty

    Identifies the PixelHeight dependency property.

    public static DependencyProperty PixelHeightProperty { get; }public static DependencyProperty PixelHeightProperty { get; }Public Static ReadOnly Property PixelHeightProperty As DependencyPropertypublic static DependencyProperty PixelHeightProperty { get; }

    Property Value

  • PixelWidth
    PixelWidth
    PixelWidth
    PixelWidth

    Gets the width of the bitmap in pixels.

    public int PixelWidth { get; }public int PixelWidth { get; }Public ReadOnly Property PixelWidth As intpublic int PixelWidth { get; }

    Property Value

    • int
      int
      int

      The width of the bitmap in pixels.

  • PixelWidthProperty
    PixelWidthProperty
    PixelWidthProperty
    PixelWidthProperty

    Identifies the PixelWidth dependency property.

    public static DependencyProperty PixelWidthProperty { get; }public static DependencyProperty PixelWidthProperty { get; }Public Static ReadOnly Property PixelWidthProperty As DependencyPropertypublic static DependencyProperty PixelWidthProperty { get; }

    Property Value

Methods

  • SetSource(IRandomAccessStream)
    SetSource(IRandomAccessStream)
    SetSource(IRandomAccessStream)
    SetSource(IRandomAccessStream)

    Sets the source image for a BitmapSource by accessing a stream. Most callers should use SetSourceAsync(IRandomAccessStream) instead.

    public void SetSource(IRandomAccessStream streamSource)public void SetSource(IRandomAccessStream streamSource)Public Function SetSource(streamSource As IRandomAccessStream) As voidpublic void SetSource(IRandomAccessStream streamSource)

    Parameters

    Remarks

    Calling SetSource(IRandomAccessStream) rather than SetSourceAsync(IRandomAccessStream) has the potential to block the UI thread until the image source file is returned and processed. It is for this reason that we generally recommend calling SetSourceAsync(IRandomAccessStream) instead of calling SetSource(IRandomAccessStream).

    In low memory situations (most likely on lower-memory phones), it is possible for an exception to be raised with the message "The image is unrecognized" and an HRESULT of 0x88982F60. While this exception ordinarily indicates bad data, if your app is close to its memory limit then the cause of the exception is likely to be low memory. In that case, we recommend that you free memory and try again.

  • SetSourceAsync(IRandomAccessStream)
    SetSourceAsync(IRandomAccessStream)
    SetSourceAsync(IRandomAccessStream)
    SetSourceAsync(IRandomAccessStream)

    Sets the source image for a BitmapSource by accessing a stream and processing the result asynchronously.

    public IAsyncAction SetSourceAsync(IRandomAccessStream streamSource)public IAsyncAction SetSourceAsync(IRandomAccessStream streamSource)Public Function SetSourceAsync(streamSource As IRandomAccessStream) As IAsyncActionpublic IAsyncAction SetSourceAsync(IRandomAccessStream streamSource)

    Parameters

    Returns

    Remarks

    Setting an image source by calling the asynchronous SetSourceAsync(IRandomAccessStream) method rather than the similar SetSource(IRandomAccessStream) method avoids blocking the UI thread. The SetSourceAsync(IRandomAccessStream) behavior is similar to what the system does internally when you set an image source as a URI in markup: the system doesn't wait to retrieve and decode, but it does run layout again once the image source is available. The markup parsing equivalent doesn't expose the async infrastructure, but the SetSourceAsync(IRandomAccessStream) method does. For more info on how to use async, await, or how to work with an IAsyncAction value, see Call asynchronous APIs in C# or Visual Basic.

    If the app changes the image source again via SetSourceAsync(IRandomAccessStream), SetSource(IRandomAccessStream) or UriSource while a SetSourceAsync(IRandomAccessStream) call is already in progress, the pending SetSourceAsync(IRandomAccessStream) action will throw a TaskCanceledException and set the Status to Canceled.

    If you have a Microsoft .NET stream that you want to use as a source, you can use the AsRandomAccessStream extension method to convert it to the IRandomAccessStream type that's needed as input for SetSourceAsync(IRandomAccessStream).

    In low memory situations (most likely on lower-memory phones), it is possible for an exception to be raised with the message "The image is unrecognized" and an HRESULT of 0x88982F60. While this exception ordinarily indicates bad data, if your app is close to its memory limit then the cause of the exception is likely to be low memory. In that case, we recommend that you free memory and try again.

    Examples

    This example shown here uses a file stream (obtained using a file picker, not shown) to load an image source by calling SetSourceAsync(IRandomAccessStream). The file picker, stream and call to SetSourceAsync(IRandomAccessStream) are all asynchronous. The code shown here comes from a larger code sample, the SDK XAML images sample.

    // Ensure the stream is disposed once the image is loaded
    using (IRandomAccessStream fileStream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
    {
         // Set the image source to the selected bitmap
         BitmapImage bitmapImage = new BitmapImage();
         bitmapImage.DecodePixelHeight = decodePixelHeight;
         bitmapImage.DecodePixelWidth = decodePixelWidth;
    
         await bitmapImage.SetSourceAsync(fileStream);
         Scenario2Image.Source = bitmapImage;
    }
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Media.Imaging.dll