LoadedImageSurface LoadedImageSurface LoadedImageSurface LoadedImageSurface Class

Definition

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 : sealed class LoadedImageSurface : IClosable, ICompositionSurface, ILoadedImageSurface
struct winrt::Windows::UI::Xaml::Media::LoadedImageSurface : IClosable, ICompositionSurface, ILoadedImageSurface
public sealed class LoadedImageSurface : IDisposable, ICompositionSurface, ILoadedImageSurface
Public NotInheritable Class LoadedImageSurface Implements IDisposable, ICompositionSurface, ILoadedImageSurface
Attributes
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

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 DecodedPhysicalSize DecodedPhysicalSize DecodedPhysicalSize

Gets the size of the decoded image in physical pixels.

DecodedSize DecodedSize DecodedSize DecodedSize

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

NaturalSize NaturalSize NaturalSize NaturalSize

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

Methods

Close() Close() Close() Close()

Disposes of the LoadedImageSurface and associated resources.

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

StartLoadFromStream(IRandomAccessStream) StartLoadFromStream(IRandomAccessStream) StartLoadFromStream(IRandomAccessStream) StartLoadFromStream(IRandomAccessStream)

Loads an image onto a LoadedImageSurface from the provided IRandomAccessStream at the natural size defined in the image source.

StartLoadFromStream(IRandomAccessStream, Size) StartLoadFromStream(IRandomAccessStream, Size) StartLoadFromStream(IRandomAccessStream, Size) StartLoadFromStream(IRandomAccessStream, Size)

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

StartLoadFromUri(Uri) StartLoadFromUri(Uri) StartLoadFromUri(Uri) StartLoadFromUri(Uri)

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

StartLoadFromUri(Uri, Size) StartLoadFromUri(Uri, Size) StartLoadFromUri(Uri, Size) StartLoadFromUri(Uri, Size)

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

Events

LoadCompleted LoadCompleted LoadCompleted LoadCompleted

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

See Also

  • T:Windows.UI.Composition.ICompositionSurface