BitmapImage class

Applies to Windows and Windows Phone

Provides the practical object source type for the Image.Source and ImageBrush.ImageSource properties. You can define a BitmapImage by using a URI that references an image source file, or by calling SetSourceAsync and supplying a stream.

Inheritance

Object
  DependencyObject
    ImageSource
      BitmapSource
        BitmapImage

Syntax


public sealed class BitmapImage : BitmapSource


<BitmapImage .../>

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The BitmapImage class has these types of members:

Constructors

The BitmapImage class has these constructors.

ConstructorDescription
BitmapImage() Initializes a new instance of the BitmapImage class.
BitmapImage(Uri) Initializes a new instance of the BitmapImage class, using the supplied Uniform Resource Identifier (URI).

 

Events

The BitmapImage class has these events.

EventDescription
DownloadProgress Occurs when a significant change has occurred in the download progress of the BitmapImage content.
ImageFailed Occurs when there is an error associated with image retrieval or format.
ImageOpened Occurs when the image source is downloaded and decoded with no failure. You can use this event to determine the size of an image before rendering it.

 

Methods

The BitmapImage class has these methods. It also inherits methods from the Object class.

MethodDescription
ClearValue Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
SetSource Sets the source image for a BitmapSource by accessing a stream. Most callers should use SetSourceAsync instead. (Inherited from BitmapSource)
SetSourceAsync Sets the source image for a BitmapSource by accessing a stream and processing the result asynchronously. (Inherited from BitmapSource)
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)

 

Properties

The BitmapImage class has these properties.

PropertyAccess typeDescription

CreateOptions

Read/writeGets or sets the BitmapCreateOptions for a BitmapImage.

CreateOptionsProperty

Read-onlyIdentifies the CreateOptions dependency property.

DecodePixelHeight

Read/writeGets or sets the height to use for image decoding operations.

DecodePixelHeightProperty

Read-onlyIdentifies the DecodePixelHeight dependency property.

DecodePixelType

Read/writeGets or sets a value that determines how DecodePixelWidth and DecodePixelHeight values are interpreted for decoding operations.

DecodePixelTypeProperty

Read-onlyIdentifies the DecodePixelType dependency property.

DecodePixelWidth

Read/writeGets or sets the width to use for image decoding operations.

DecodePixelWidthProperty

Read-onlyIdentifies the DecodePixelWidth dependency property.

Dispatcher

Read-onlyGets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)

PixelHeight

Read-onlyGets the height of the bitmap in pixels. (Inherited from BitmapSource)

PixelWidth

Read-onlyGets the width of the bitmap in pixels. (Inherited from BitmapSource)

UriSource

Read/writeGets or sets the Uniform Resource Identifier (URI) of the graphics source file that generated this BitmapImage.

UriSourceProperty

Read-onlyIdentifies the UriSource dependency property.

 

Remarks

A BitmapImage can be sourced from these image file formats:

  • Joint Photographic Experts Group (JPEG)
  • Portable Network Graphics (PNG)
  • bitmap (BMP)
  • Graphics Interchange Format (GIF)
  • Tagged Image File Format (TIFF)
  • JPEG XR
  • icons (ICO)

If the image source is a stream, that stream is expected to contain an image file in one of these formats.

The BitmapImage class represents an abstraction so that an image source can be set asynchronously but still be referenced in XAML markup as a property value, or in code as an object that doesn't use awaitable syntax. When you create a BitmapImage object in code, it initially has no valid source. You should then set its source using one of these techniques:

  • Use the BitmapImage(Uri) constructor rather than the default constructor. Although it's a constructor you can think of this as having an implicit asynchronous behavior: the BitmapImage won't be ready for use until it fires an ImageOpened event that indicates a successful async source set operation.
  • Set the UriSource property. As with using the Uri constructor, this action is implicitly asynchronous, and the BitmapImage won't be ready for use until it fires an ImageOpened event.
  • Use SetSourceAsync. This method is explicitly asynchronous.

The properties where you might use a BitmapImage, such as Image.Source, are designed for this asynchronous behavior, and won't throw exceptions if they are set using a BitmapImage that doesn't have a complete source yet. Rather than handling exceptions, you should handle ImageOpened or ImageFailed events either on the BitmapImage directly or on the control that uses the source (if those events are available on the control class).

ImageFailed and ImageOpened are mutually exclusive. One event or the other will always file whenever a BitmapImage object has its source value set or reset.

BitmapImage and encoding

The underlying codec support for image files is supplied by Windows Imaging Component (WIC) API in Windows 8. For more info on specific image formats as documented for the codecs, see Native WIC Codecs. For more info on formats and how to use Uniform Resource Identifiers (URIs) to access image source files that come from app resources, see Quickstart: Image and ImageBrush.

The API for Image, BitmapImage and BitmapSource doesn't include any dedicated methods for encoding and decoding of media formats. All of the encode and decode operations are built-in, and at most will surface aspects of encode or decode as part of event data for load events. If you want to do any special work with image encode or decode, which you might use if your app is doing image conversions or manipulation, you should use the APIs that are available in the Windows.Graphics.Imaging namespace. These imaging APIs can be used by either Windows Store apps using C++, C#, or Visual Basic or Windows Store apps using JavaScript. These APIs are also supported by the WIC component of Windows 8.

Examples

Here's an example of using a BitmapImage object to set Image.Source in C#. In this example, the Image object was created in XAML but doesn't have a source or any other property values; instead these values are provided at run-time when the Image is loaded from XAML.


void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image; 
    BitmapImage bitmapImage = new BitmapImage();
    img.Width = bitmapImage.DecodePixelWidth = 80; //natural px width of image source
    // don't need to set Height, system maintains aspect ratio, and calculates the other
    // dimension, so long as one dimension measurement is provided
    bitmapImage.UriSource = new Uri(img.BaseUri,"Images/myimage.png");
}

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Media.Imaging
Windows::UI::Xaml::Media::Imaging [C++]

Metadata

Windows.winmd

See also

Image
BitmapSource
Image.Source
ImageBrush.ImageSource
Quickstart: Image and ImageBrush

 

 

Show:
© 2014 Microsoft. All rights reserved.