Multi​Source​Media​Frame​Reader Multi​Source​Media​Frame​Reader Multi​Source​Media​Frame​Reader Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

Prerelease. Provides access to time-correlated frames from multiple MediaFrameSource and provides notifications when new frames arrive. This is useful if you need to process frames from different sources, such as a depth camera and an rbg camera, and you need to make sure that the frames from each source were captured close to each other in time.

public : sealed class MultiSourceMediaFrameReader : IClosable, IMultiSourceMediaFrameReaderpublic sealed class MultiSourceMediaFrameReader : IDisposable, IMultiSourceMediaFrameReaderPublic NotInheritable Class MultiSourceMediaFrameReader Implements IDisposable, IMultiSourceMediaFrameReader
Attributes
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

Get an instance of this class by calling CreateMultiSourceFrameReaderAsync on a MediaCapture object that has been initialized to use the desired media frame source.

To read frames from one or more MediaFrameSource objects without time correlation between different sources, you can use MediaFrameReader.

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

Properties

AcquisitionMode AcquisitionMode AcquisitionMode

Prerelease. Specifies the way that the system should manage frames acquired from a MultiSourceMediaFrameReader when a new frame arrives before the app has finished processing the previous frame.

public : MediaFrameReaderAcquisitionMode AcquisitionMode { get; set; }public MediaFrameReaderAcquisitionMode AcquisitionMode { get; set; }Public ReadWrite Property AcquisitionMode As MediaFrameReaderAcquisitionMode
Value
MediaFrameReaderAcquisitionMode MediaFrameReaderAcquisitionMode MediaFrameReaderAcquisitionMode

A value that specifies the frame reader's acquisition mode.

Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16225.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

If this property is set to Realtime, frames that arrive while the app's FrameArrived event handler is executing are dropped. This mode works well for scenarios where processing the most current frame is prioritized, such as real-time computer vision applications.

If this property is set to [Buffered]((https://docs.microsoft.com/uwp/api/windows.media.capture.frames.mediaframereaderacquisitionmode), frames that arrive while the app's FrameArrived event handler is executing are buffered in memory by the system. The FrameArrived event is raised for each buffered frame when the event handler for the previous frame has completed. This mode is intended for apps for which the sequence of frames is critical and for which dropped frames will break the scenario. Note that once the system's memory limit for buffered frames has been reached, no more frames will be acquired until the app processes buffered frames, freeing memory for the acquisition of additional frames.

See Also

Methods

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
Attributes

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

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

StartAsync() StartAsync() StartAsync()

Asynchronously starts the reading of time-corellated frames from one or more MediaFrameSource objects.

public : IAsyncOperation<MultiSourceMediaFrameReaderStartStatus> StartAsync()public IAsyncOperation<MultiSourceMediaFrameReaderStartStatus> StartAsync()Public Function StartAsync() As IAsyncOperation( Of MultiSourceMediaFrameReaderStartStatus )
Returns
Attributes

StopAsync() StopAsync() StopAsync()

Asynchronously stops the reading of time-corellated frames from one or more MediaFrameSource objects.

public : IAsyncAction StopAsync()public IAsyncAction StopAsync()Public Function StopAsync() As IAsyncAction
Returns

An asynchronous action

Attributes

TryAcquireLatestFrame() TryAcquireLatestFrame() TryAcquireLatestFrame()

Attempts to obtain a MultiSourceMediaFrameReference object which provides access to the latest time-correlated frames from one or more MediaFrameSource objects.

public : MultiSourceMediaFrameReference TryAcquireLatestFrame()public MultiSourceMediaFrameReference TryAcquireLatestFrame()Public Function TryAcquireLatestFrame() As MultiSourceMediaFrameReference
Returns
Attributes

Remarks

After getting an instance of MultiSourceMediaFrameReference, get the time-correlated media frame from a particular media frame source by calling MultiSourceMediaFrameReference.TryGetFrameReferenceBySourceId and passing in the value of the MediaFrameSourceInfo.Id property for the desired media frame source.

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

Events

FrameArrived FrameArrived FrameArrived

Occurs when a new frame arrives from all of the media frame sources associated with the MultiSourceMediaFrameReader.

public : event TypedEventHandler FrameArrivedpublic event TypedEventHandler FrameArrivedPublic Event FrameArrived
Attributes

Remarks

In the handler for the FrameArrived event, call TryAcquireLatestFrame on the MultiSourceMediaFrameReference passed in as the sender parameter to the event handler to get a MultiSourceMediaFrameReference representing the latest set of correlated frames from the media frame sources for which the reader was created. Then, get the time-correlated media frame from a particular media frame source by calling TryGetFrameReferenceBySourceId and passing in the value of the MediaFrameSourceInfo.Id property for the desired media frame source.

Note that this event is only raised when a new frame is available from all of the media frame sources associated with the MultiSourceMediaFrameReader. For example, if one of the sources produces frames at twice the rate of another, half of the frames from the faster source will be dropped and this event will only be raised when the slower frame source has a new frame available. For this reason, it's a good idea to set up an event and signal it each time this event is raised. In a separate thread, you can check to see if the event has been signaled within a specified time window, 5 seconds for example. If the event has not been signaled with the time window, your app can deduce that one of the frame sources is no longer generating frames and that the reader should be stopped.

For how-to guidance on working with time-correlated media frames, see Process media frames with MediaFrameReader.

See Also