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
| 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:
- BufferMediaFrame.Buffer
- VideoMediaFrame.SoftwareBitmap
- VideoMediaFrame.GetVideoFrame
- VideoMediaFrame.CameraIntrinsics 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. 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.
The BufferMediaFrame wrapped by the MediaFrameReference.
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.
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.
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.
The VideoMediaFrame wrapped by the MediaFrameReference.
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.