Image sources

A source image may exist in various formats and containers. The developer has the choice to use either compressed data, such as JPEG small memory footprint), or to work with raw bitmaps, whichever suits her needs better. This topic describes the image source classes available in the Lumia Imaging SDK.

Bitmap Image Source

Use a BitmapImageSource when the source image is raw pixels in a Lumia.Imaging.Bitmap. Also, a WriteableBitmap can be used via the provided extension method AsBitmap:

using Lumia.InteropServices.WindowsRuntime;
WriteableBitmap wb = new WriteableBitmap(…);
// ...
BitmapImageSource source = new BitmapImageSource(wb.AsBitmap());

Bitmap Provider Image Source

Use a BitmapProviderImageSource when creation of the bitmap that the image source represents can be deferred to the actual time of use. An object of the class is instantiated with a IReadableBitmapProvider, an interface that can be implemented by the user to create the bitmap only when needed.

Buffer Image Source

Use a BufferImageSource when the source image is file data (JPEG/JFIF with EXIF metadata, PNG, and so on) in a WinRT IBuffer.

Buffer Provider Image Source

Use a BufferProviderImageSource when creation of the buffer containing the image that the image source represents can be deferred to the actual time of use. An object of the class is instantiated with a IBufferProvider, an interface that can be implemented by the user to create the buffer only when needed.

Camera Preview Image Source (Windows Phone 8.0)

Use a CameraPreviewImageSource when the source image is the preview buffer of an ICameraCaptureDevice. Every time RenderAsync is called on the processing pipeline, this image source will load the most recent preview image that is available. Other than reading preview dimensions and pixel data, it does not affect the ICameraCaptureDevice, so it can be used in a drop-in manner in most capturing scenarios.

Camera Preview Image Source (Windows and Windows Phone 8.1)

Use a CameraPreviewImageSource when the source image is the preview of the camera stream. Since ICameraCaptureDevice is not supported by Windows, the CameraPreviewImageSouce supports the preview functionality by implementing InitializeAsync, StartPreviewAsync, and StopPreviewAsync. The event PreviewFrameAvailable is raised every time a new preview frame is available. If async work is done in the event handler, wait on that work before calling StopPreviewAsync. When RenderAsync is called on the processing pipeline, this image source will load the most recent preview image that is available. To be able to capture an image using the MediaCapture class, the CameraPreviewImage has to be stopped.

Note: When app is suspended, the CameraPreviewImageSource must be stopped by calling StopPreviewAsync. When the app is resumed, the CameraPreviewImageSource must be restarted by calling InitializeAsync followed by StartPreviewAsync. It's only possible to have one instance of the CameraPreviewImageSouce running for each camera on the device. Webcam and microphone capabilities are needed.

Warning: It is extremely important that you properly shut down and dispose of the CameraPreviewImageSource object and related objects when your app is suspended. Failure to do so could interfere with other apps accessing the device's camera which will result in a negative user experience for your app.

Color Image Source

Use a ColorImageSource when the source image is a constant flat color. Using ColorImageSource makes it possible to avoid having an intermediate bitmap that consumes memory.

Delegating Image Source

Use a DelegatingImageSource when the source image is to be generated by a user-implemented class that implements the ICustomImageSource interface. The user class is attached to the DelegatingImageSource upon creation. In C#, this is more easily accomplished through the use of the CustomImageSourceBase base class. See Custom Sources and Effects.

Gradient Image Source

Use a GradientImageSource when the source image is a color gradient. Using GradientImageSource makes it possible to avoid having an intermediate bitmap that consumes memory.

The following example demonstrates how to create an image with a radial gradient that progresses from red to green:

var rad = new RadialGradient(new Windows.Foundation.Point(0.5, 0.5), new EllipseRadius(0.3, 0.3));

rad.Stops = new GradientStop[]  {
     new GradientStop() { Color = Windows.UI.Color.FromArgb(255, 255, 0, 0), Offset = 0 },
     new GradientStop() { Color = Windows.UI.Color.FromArgb(255, 0, 255, 0), Offset = 1 }
}; 
 
using (var grad = new GradientImageSource(new Windows.Foundation.Size(Width, Height), rad))  
{
  var buffer = await new JpegRenderer(grad).RenderAsync();  
}

Figure 1. Result of the GradientImageSource code example

RandomAccessStreamImageSource

Used when the source image is file data (JPEG/JFIF with EXIF metadata, PNG, and so on) in a WinRT IRandomAccessStream.

StorageFileImageSource

Used when the source image is file data (JPEG/JFIF with EXIF metadata, PNG, and so on) in a WinRT IStorageFile.

StreamImageSource

Used when the source image is file data (JPEG/JFIF with EXIF metadata, PNG, and so on) in a .NET System.IO.Stream.