MediaFrameReference MediaFrameReference MediaFrameReference MediaFrameReference Class

Definition

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 : sealed class MediaFrameReference : IClosable, IMediaFrameReferencepublic sealed class MediaFrameReference : IDisposable, IMediaFrameReferencePublic NotInheritable Class MediaFrameReference Implements IDisposable, IMediaFrameReference// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

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 methods include:

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

Properties

BufferMediaFrame BufferMediaFrame BufferMediaFrame BufferMediaFrame

Gets the BufferMediaFrame wrapped by the MediaFrameReference, if that is the type of frame represented.

public : BufferMediaFrame BufferMediaFrame { get; }public BufferMediaFrame BufferMediaFrame { get; }Public ReadOnly Property BufferMediaFrame As BufferMediaFrame// You can use this property in JavaScript.

Remarks

If the frame reference wraps a different type of frame, such as a VideoMediaFrame, the object returned by this property is null.

CoordinateSystem CoordinateSystem CoordinateSystem CoordinateSystem

Gets the spatial coordinate system for the referenced media frame, if one is defined.

public : SpatialCoordinateSystem CoordinateSystem { get; }public SpatialCoordinateSystem CoordinateSystem { get; }Public ReadOnly Property CoordinateSystem As SpatialCoordinateSystem// You can use this property in JavaScript.
Value
SpatialCoordinateSystem SpatialCoordinateSystem SpatialCoordinateSystem SpatialCoordinateSystem

The spatial coordinate system for the referenced media frame.

Remarks

If no spatial coordinate system is defined for the referenced media frame, the returned SpatialCoordinateSystem object is null.

Duration Duration Duration Duration

Gets the duration of the referenced media frame.

public : TimeSpan Duration { get; }public TimeSpan Duration { get; }Public ReadOnly Property Duration As TimeSpan// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The duration of the referenced media frame.

Format Format Format Format

Gets the format of the reference media frame.

public : MediaFrameFormat Format { get; }public MediaFrameFormat Format { get; }Public ReadOnly Property Format As MediaFrameFormat// You can use this property in JavaScript.
Value
MediaFrameFormat MediaFrameFormat MediaFrameFormat MediaFrameFormat

The format of the reference media frame.

Properties Properties Properties Properties

Gets a map of properties for the referenced frame.

public : IMapView<Guid, object> Properties { get; }public IReadOnlyDictionary<Guid, object> Properties { get; }Public ReadOnly Property Properties As IReadOnlyDictionary<Guid, object>// You can use this property in JavaScript.
Value
IMapView<PlatForm::Guid, PlatForm::Object> IReadOnlyDictionary<Guid, object> IReadOnlyDictionary<Guid, object> IReadOnlyDictionary<Guid, object>

A map of properties for the referenced frame.

SourceKind SourceKind SourceKind SourceKind

Gets the type of MediaFrameSource from which the referenced frame originated, such as a color, infrared, or custom source.

public : MediaFrameSourceKind SourceKind { get; }public MediaFrameSourceKind SourceKind { get; }Public ReadOnly Property SourceKind As MediaFrameSourceKind// You can use this property in JavaScript.
Value
MediaFrameSourceKind MediaFrameSourceKind MediaFrameSourceKind MediaFrameSourceKind

The type of media frame source from which the referenced frame originated.

SystemRelativeTime SystemRelativeTime SystemRelativeTime SystemRelativeTime

Gets a timestamp that is relative to the system and is correlatable across multiple media sources on the same device.

public : IReference<TimeSpan> SystemRelativeTime { get; }public Nullable<TimeSpan> SystemRelativeTime { get; }Public ReadOnly Property SystemRelativeTime As Nullable<TimeSpan>// You can use this property in JavaScript.
Value
IReference<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>

A timestamp relative to the system. This value uses 100ns interval QPC time. For more information on QPC time, see Acquiring high-resolution time stamps.

VideoMediaFrame VideoMediaFrame VideoMediaFrame VideoMediaFrame

Gets the VideoMediaFrame wrapped by the MediaFrameReference, if that is the type of frame represented.

public : VideoMediaFrame VideoMediaFrame { get; }public VideoMediaFrame VideoMediaFrame { get; }Public ReadOnly Property VideoMediaFrame As VideoMediaFrame// You can use this property in JavaScript.

Remarks

If the frame reference wraps a different type of frame, or if the video frame data is in a format that is unsupported, such as RGB24, then this property is null. In this case, you can access the BufferMediaFrame property, which is always non-null.

Methods

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

Disposes of the object and associated resources.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.

Remarks

The Close method is used by Universal Windows app using JavaScript. For apps written using the .NET Framework 4.5 in C# and VB.NET, the Close method is exposed as the Dispose() method on the MediaFrameReference object. For apps written in C++, the Close method will be called when using the delete keyword on the object.

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()

See Also