MediaFrameReference Class

Definition

Namespace:

Windows.Media.Capture.Frames

A wrapper class that represents a frame obtained from a MediaFrameSource. Use the properties of this class to access the specific frame type provided by the source, such as a VideoMediaFrame or BufferMediaFrame.

public ref class MediaFrameReference sealed : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 196608)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class MediaFrameReference final : IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 196608)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class MediaFrameReference : System.IDisposable

Public NotInheritable Class MediaFrameReference
Implements IDisposable

Inheritance

Object Platform::Object IInspectable MediaFrameReference

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

IClosable IDisposable

Windows requirements

Device family	Windows 10 Anniversary Edition (introduced in 10.0.14393.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v3.0)

Remarks

To get an instance of MediaFrameReference from a media frame source, create a MediaFrameReader by calling CreateFrameReaderAsync on a MediaCapture object that has been initialized to use the desired media frame source. After the frame reader has been started by calling StartAsync, call TryAcquireLatestFrame to get a MediaFrameReference representing the latest frame from the media frame source.

Each MediaFrameReader maintains a circular buffer of MediaFrameReference objects obtained from TryAcquireLatestFrame. After all of the MediaFrameReference objects in the buffer have been used, subsequent calls to TryAcquireLatestFrame will cause the system to call Close (or Dispose in C#) on the oldest buffer object in order to reuse it. Once the object has been disposed, you can no longer use it to access the frame data. For this reason, you should not store the MediaFrameReference object longer than you actually need to process the frame. If your app scenario requires you to keep a reference to the data for longer, you should use one of the APIs provided to get the underlying data. These include:

• VideoMediaFrame.SoftwareBitmap
• VideoMediaFrame.Direct3DSurface

It is the responsibility of the app to call Close (or Dispose) on the objects returned by these APIs when they are no longer being used.

Important

If you access the SoftwareBitmap or Direct3DSurface objects provided by the VideoMediaFrame property of a MediaFrameReference, the system creates a strong reference to these objects, which means that they will not be disposed when you call Dispose on the containing MediaFrameReference. This also applies to the SoftwareBitmap or Direct3DSurface objects provided by the VideoFrame object that you obtain from the MediaFrameReference.VideoMediaFrame property. You must explicitly call the Dispose method of the SoftwareBitmap or Direct3DSurface directly for the objects to be immediately disposed. Otherwise, the garbage collector will eventually free the memory for these objects, but you can't know when this will occur, and if the number of allocated bitmaps or surfaces exceeds the maximum amount allowed by the system, the flow of new frames will stop.

For how-to guidance on using MediaFrameSource to capture frames, see Process media frames with MediaFrameReader.

Version history

Windows version	SDK version	Value added
1803	17134	AudioMediaFrame

Properties

AudioMediaFrame	Gets the AudioMediaFrame wrapped by the MediaFrameReference, if that is the type of frame represented.
BufferMediaFrame	Gets the BufferMediaFrame wrapped by the MediaFrameReference, if that is the type of frame represented.
CoordinateSystem	Gets the spatial coordinate system for the referenced media frame, if one is defined.
Duration	Gets the duration of the referenced media frame.
Format	Gets the format of the reference media frame.
Properties	Gets a map of properties for the referenced frame.
SourceKind	Gets the type of MediaFrameSource from which the referenced frame originated, such as a color, infrared, or custom source.
SystemRelativeTime	Gets a timestamp that is relative to the system and is correlatable across multiple media sources on the same device.
VideoMediaFrame	Gets the VideoMediaFrame wrapped by the MediaFrameReference, if that is the type of frame represented.

Methods

Close()	Disposes of the object and associated resources.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

See also

• IClosable
• Process media frames with MediaFrameReader