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, ILoadedImageSurfacepublic sealed class LoadedImageSurface : IDisposable, ICompositionSurface, ILoadedImageSurfacePublic NotInheritable Class LoadedImageSurface Implements IDisposable, ICompositionSurface, ILoadedImageSurface// This API is not available in Javascript.
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.

public : Size DecodedPhysicalSize { get; }public Size DecodedPhysicalSize { get; }Public ReadOnly Property DecodedPhysicalSize As Size// This API is not available in Javascript.
Value
Size Size Size Size

The size of the decoded image in physical pixels.

DecodedSize DecodedSize DecodedSize DecodedSize

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

public : Size DecodedSize { get; }public Size DecodedSize { get; }Public ReadOnly Property DecodedSize As Size// This API is not available in Javascript.
Value
Size Size Size Size

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.

public : Size NaturalSize { get; }public Size NaturalSize { get; }Public ReadOnly Property NaturalSize As Size// This API is not available in Javascript.
Value
Size Size Size Size

The natural size of the image in physical pixels.

Methods

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

Disposes of the LoadedImageSurface and associated resources.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// This API is not available in Javascript.

Examples

In this example, the CompositionSurfaceBrush will continue to exist even after the LoadedImageSurface has been closed.

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

LoadedImageSurface loadedSurface = LoadedImageSurface.StartLoadFromUri(new Uri("ms-appx:///Assets/myPic.jpg"));
loadedSurface.LoadCompleted += Load_Completed;
imageBrush.Surface = loadedSurface;

loadedSurface.Close();
// The imageBrush still exists

Remarks

Calling this method will dispose the LoadedImageSurface reference, however any brushes or surfaces created from the LoadedImageSurface that still have active references will continue to render unless you explicitly dispose of those as well.

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

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

This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()

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.

public : static LoadedImageSurface StartLoadFromStream(IRandomAccessStream stream)public static LoadedImageSurface StartLoadFromStream(IRandomAccessStream stream)Public Static Function StartLoadFromStream(stream As IRandomAccessStream) As LoadedImageSurface// This API is not available in Javascript.
Parameters
stream
IRandomAccessStream IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream from which the image is loaded.

Returns

An instance of LoadedImageSurface with the image loaded onto its surface.

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.

public : static LoadedImageSurface StartLoadFromStream(IRandomAccessStream stream, Size desiredMaxSize)public static LoadedImageSurface StartLoadFromStream(IRandomAccessStream stream, Size desiredMaxSize)Public Static Function StartLoadFromStream(stream As IRandomAccessStream, desiredMaxSize As Size) As LoadedImageSurface// This API is not available in Javascript.
Parameters
stream
IRandomAccessStream IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream from which the image is loaded.

desiredMaxSize
Size Size Size Size

The desired maximum size of the image surface in device independent pixels.

Returns

An instance of LoadedImageSurface with the image loaded onto its surface.

Remarks

By default, LoadedImageSurface will fill up as much of the desiredMaxSize as possible while preserving the aspect ratio and image content of the incoming source. This may result in a decodedsize that differs from the input desiredMaxSize

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.

public : static LoadedImageSurface StartLoadFromUri(Uri uri)public static LoadedImageSurface StartLoadFromUri(Uri uri)Public Static Function StartLoadFromUri(uri As Uri) As LoadedImageSurface// This API is not available in Javascript.
Parameters
uri
Uri Uri Uri Uri

The URI from which the image is loaded.

Returns

An instance of LoadedImageSurface with the image loaded onto its surface.

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.

public : static LoadedImageSurface StartLoadFromUri(Uri uri, Size desiredMaxSize)public static LoadedImageSurface StartLoadFromUri(Uri uri, Size desiredMaxSize)Public Static Function StartLoadFromUri(uri As Uri, desiredMaxSize As Size) As LoadedImageSurface// This API is not available in Javascript.
Parameters
uri
Uri Uri Uri Uri

The URI from which the image is loaded.

desiredMaxSize
Size Size Size Size

The desired maximum size of the image surface in device independent pixels.

Returns

An instance of LoadedImageSurface with the image loaded onto its surface.

Remarks

By default, LoadedImageSurface will fill up as much of the desiredMaxSize as possible while preserving the aspect ratio and image content of the incoming source. This may result in a decodedsize that differs from the input desiredMaxSize

Events

LoadCompleted LoadCompleted LoadCompleted LoadCompleted

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

public : event TypedEventHandler LoadCompleted<LoadedImageSurface,  LoadedImageSourceLoadCompletedEventArgs>public event TypedEventHandler LoadCompleted<LoadedImageSurface,  LoadedImageSourceLoadCompletedEventArgs>Public Event LoadCompleted<LoadedImageSurface,  LoadedImageSourceLoadCompletedEventArgs>// This API is not available in Javascript.
<LoadedImageSurface LoadCompleted="eventhandler"/>

Examples

In this example, we set the size of a SpriteVisual to exactly match the decoded size of a successfully loaded LoadedImageSurface.

private Load_Completed(LoadedImageSurface sender, LoadedImageSourceLoadCompletedEventArgs e)
{
    if(e.Status == LoadedImageSourceLoadStatus.Success){
        // imageVisual is a SpriteVisual than has been previously created and whose brush references the LoadedImageSurface
        Size decodedSize = sender.DecodedSize;
        imageVisual.Size = new Vector2((float)decodedSize.Width, (float)decodedSize.Height);

    } else {
        // Handle a load failure
    }
}

Remarks

The LoadedImageSurface instance will not have a loaded image or sizing information, until this event fires. The LoadCompleted event fires regardless of success or failure and the LoadedImageSourceLoadCompletedEventArgs can be used to determine the status.

The LoadCompleted event fires every time that the surface of an instance of LoadedImageSurface gets populated with an image. This includes:

  • The first time that a LoadedImageSurface is initialized
  • The device recovers from a lost state
  • A DPI change causes a different image source to load
  • The app recovers from a low memory state

Common uses of the LoadCompleted event are to put up a temporary image if the image source may take a long time to load or resize a visual exactly to the decoded size of the LoadedImageSurface.