Image Surface Class
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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
Object Platform::Object IInspectable LoadedImageSurface
Windows 10 Creators Update (introduced in 10.0.15063.0)
Windows.Foundation.UniversalApiContract (introduced in v4.0)
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;
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.
- StartLoadFromUri(Uri, Size)
- StartLoadFromStream(IRandomAccessStream, Size)
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.
Gets the size of the decoded image in physical pixels.
Gets the size of the decoded image in device independent pixels.
Gets the natural size of the image in physical pixels, which is defined in the original image source.
Disposes of the LoadedImageSurface and associated resources.
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
Loads an image into a LoadedImageSurface from the provided Uniform Resource Identifier (URI) at the natural size defined in the image source.
Loads an image into a LoadedImageSurface from the provided Uniform Resource Identifier (URI) with the desired maximum size.
Occurs when the image has been downloaded, decoded and loaded to the underlying ICompositionSurface.