LoadedImageSurface Class

  • Reference

Definition

Namespace:
Windows.UI.Xaml.Media
Edit

Represents a composition surface that an image can be downloaded, decoded and loaded onto. You can load an image using a Uniform Resource Identifier (URI) that references an image source file, or supplying a IRandomAccessStream.

public ref class LoadedImageSurface sealed : IClosable, ICompositionSurface
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 262144)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class LoadedImageSurface final : IClosable, ICompositionSurface
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 262144)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class LoadedImageSurface : System.IDisposable, ICompositionSurface
Public NotInheritable Class LoadedImageSurface
Implements ICompositionSurface, IDisposable
Inheritance
Object Platform::Object IInspectable LoadedImageSurface
Attributes
ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute
Implements
IClosable IDisposable ICompositionSurface

Windows requirements

Device family
Windows 10 Creators Update (introduced in 10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v4.0)

Examples

This example shows how to load an image from a local URI onto a surface and use it in a CompositionSurfaceBrush.

Compositor compositor = new Compositor();
CompositionSurfaceBrush imageBrush = compositor.CreateSurfaceBrush();

LoadedImageSurface loadedSurface = LoadedImageSurface.StartLoadFromUri(new Uri("ms-appx:///Assets/myPic.jpg"), new Size(200.0, 400.0));

// The loadedSurface currently has a size of 0x0 since it has not been downloaded, decoded and loaded to the surface yet
imageBrush.Surface = loadedSurface;

Remarks

A LoadedImageSurface 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)

[!NOTE] LoadedImageSurface does not support animated GIF images, so only the first frame of an animated GIF will be shown.

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

LoadedImageSurface encoding and decoding

The underlying codec support for image files is supplied by Windows Imaging Component (WIC) API in Windows. For more info on specific image formats as documented for the codes, see Native WIC Codecs.

Using one of the factory methods, you can create an instance of LoadedImageSurface from different types of image sources and control the max size that the image decodes at. If no max size is specified, then the image will decode to its natural size.

Lifetime management

When a LoadedImageSurface is created using one of the factory methods, the underlying surface is immediately initialized to a size of 0x0 and the image content begins downloading and decoding off of the UI thread. When the image source has been successfully decoded, it then gets loaded onto the surface and the LoadCompleted event gets fired when the surface has been populated. During the loading process, the surface will get resized from 0x0 to its final size based on the decoded size of the image source.

LoadedImageSurface automatically retains all of its resources until it loses its final reference. However, you may explicitly dispose of its resources through the Close method.

[!NOTE] LoadedImageSurface is not available prior to Windows 10, version 1703. If your app's 'minum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you cannot use this class.

Properties

DecodedPhysicalSize

Gets the size of the decoded image in physical pixels.
DecodedSize

Gets the size of the decoded image in device independent pixels.
NaturalSize

Gets the natural size of the image in physical pixels, which is defined in the original image source.

Methods

Close()

Disposes of the LoadedImageSurface and associated resources.
Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
StartLoadFromStream(IRandomAccessStream, Size)

Loads an image into a LoadedImageSurface from the provided IRandomAccessStream with the desired maximum size.
StartLoadFromStream(IRandomAccessStream)

Loads an image onto a LoadedImageSurface from the provided IRandomAccessStream at the natural size defined in the image source.
StartLoadFromUri(Uri, Size)

Loads an image into a LoadedImageSurface from the provided Uniform Resource Identifier (URI) with the desired maximum size.
StartLoadFromUri(Uri)

Loads an image into a LoadedImageSurface from the provided Uniform Resource Identifier (URI) at the natural size defined in the image source.

Events

LoadCompleted

Occurs when the image has been downloaded, decoded and loaded to the underlying ICompositionSurface.

Applies to

See also