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

[Contains prerelease APIs.]
Represents a single frame of video data.

public : sealed class VideoFrame : IClosable, IMediaFrame, IVideoFrame
struct winrt::Windows::Media::VideoFrame : IClosable, IMediaFrame, IVideoFrame
public sealed class VideoFrame : IDisposable, IMediaFrame, IVideoFrame
Public NotInheritable Class VideoFrame Implements IDisposable, IMediaFrame, IVideoFrame
var videoFrame = new videoFrame(format, width, height);
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Constructors

VideoFrame(BitmapPixelFormat, Int32, Int32) VideoFrame(BitmapPixelFormat, Int32, Int32) VideoFrame(BitmapPixelFormat, Int32, Int32) VideoFrame(BitmapPixelFormat, Int32, Int32) VideoFrame(BitmapPixelFormat, Int32, Int32)

Initializes a new instance of the VideoFrame class.

public : VideoFrame(BitmapPixelFormat format, int width, int height)
VideoFrame(BitmapPixelFormat format, int32_t width, int32_t height) const;
public VideoFrame(BitmapPixelFormat format, Int32 width, Int32 height)
Public Sub New(format As BitmapPixelFormat, width As Int32, height As Int32)
var videoFrame = new videoFrame(format, width, height);
Parameters
format
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format of the video frame.

width
Int32 Int32 Int32

The width of the video frame, in pixels.

height
Int32 Int32 Int32

The height of the video frame, in pixels.

See Also

VideoFrame(BitmapPixelFormat, Int32, Int32, BitmapAlphaMode) VideoFrame(BitmapPixelFormat, Int32, Int32, BitmapAlphaMode) VideoFrame(BitmapPixelFormat, Int32, Int32, BitmapAlphaMode) VideoFrame(BitmapPixelFormat, Int32, Int32, BitmapAlphaMode) VideoFrame(BitmapPixelFormat, Int32, Int32, BitmapAlphaMode)

Initializes a new instance of the VideoFrame class.

public : VideoFrame(BitmapPixelFormat format, int width, int height, BitmapAlphaMode alpha)
VideoFrame(BitmapPixelFormat format, int32_t width, int32_t height, BitmapAlphaMode alpha) const;
public VideoFrame(BitmapPixelFormat format, Int32 width, Int32 height, BitmapAlphaMode alpha)
Public Sub New(format As BitmapPixelFormat, width As Int32, height As Int32, alpha As BitmapAlphaMode)
var videoFrame = new videoFrame(format, width, height, alpha);
Parameters
format
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format of the video frame.

width
Int32 Int32 Int32

The width of the video frame, in pixels.

height
Int32 Int32 Int32

The height of the video frame, in pixels.

alpha
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The alpha mode of the video frame.

See Also

Properties

Direct3DSurface Direct3DSurface Direct3DSurface Direct3DSurface Direct3DSurface

Gets the IDirect3DSurface object containing the pixel data of the video frame, when one is present.

public : IDirect3DSurface Direct3DSurface { get; }
IDirect3DSurface Direct3DSurface();
public IDirect3DSurface Direct3DSurface { get; }
Public ReadOnly Property Direct3DSurface As IDirect3DSurface
var iDirect3DSurface = videoFrame.direct3dSurface;
Value
IDirect3DSurface IDirect3DSurface IDirect3DSurface

The IDirect3DSurface object containing the pixel data of the video frame.

Remarks

The pixel data of a VideoFrame can be stored either in a IDirect3DSurface or a SoftwareBitmap. This property will be null if the data for the frame is not stored in a IDirect3DSurface. If the data is stored in a software bitmap, you can access it using the SoftwareBitmap property of the VideoFrame.

Duration Duration Duration Duration Duration

Gets or sets the duration of the video frame.

public : IReference<TimeSpan> Duration { get; set; }
IReference<TimeSpan> Duration(); void Duration(IReference<TimeSpan> duration);
public Nullable<TimeSpan> Duration { get; set; }
Public ReadWrite Property Duration As Nullable<TimeSpan>
var nullable = videoFrame.duration;
videoFrame.duration = nullable;
Value
Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>

The duration of the video frame.

ExtendedProperties ExtendedProperties ExtendedProperties ExtendedProperties ExtendedProperties

Gets the extended property set which enables getting and setting properties on the media frame.

public : IPropertySet ExtendedProperties { get; }
IPropertySet ExtendedProperties();
public IPropertySet ExtendedProperties { get; }
Public ReadOnly Property ExtendedProperties As IPropertySet
var iPropertySet = videoFrame.extendedProperties;
Value
IPropertySet IPropertySet IPropertySet

The extended properties map.

IsDiscontinuous IsDiscontinuous IsDiscontinuous IsDiscontinuous IsDiscontinuous

Gets or sets a value that indicates whether an video frame is the first frame after a gap in the stream.

public : Platform::Boolean IsDiscontinuous { get; set; }
bool IsDiscontinuous(); void IsDiscontinuous(bool isdiscontinuous);
public bool IsDiscontinuous { get; set; }
Public ReadWrite Property IsDiscontinuous As bool
var bool = videoFrame.isDiscontinuous;
videoFrame.isDiscontinuous = bool;
Value
bool bool bool

True if the video frame is the first frame after a gap in the stream; otherwise, false.

IsReadOnly IsReadOnly IsReadOnly IsReadOnly IsReadOnly

Gets a value indicating whether the video frame is read-only.

public : Platform::Boolean IsReadOnly { get; }
bool IsReadOnly();
public bool IsReadOnly { get; }
Public ReadOnly Property IsReadOnly As bool
var bool = videoFrame.isReadOnly;
Value
bool bool bool

True if the video frame is read-only; otherwise, false.

Remarks

When this value is true, both the video data and the mutable properties of the video frame are read-only.

RelativeTime RelativeTime RelativeTime RelativeTime RelativeTime

Gets or sets the relative time of the frame within the video stream.

public : IReference<TimeSpan> RelativeTime { get; set; }
IReference<TimeSpan> RelativeTime(); void RelativeTime(IReference<TimeSpan> relativetime);
public Nullable<TimeSpan> RelativeTime { get; set; }
Public ReadWrite Property RelativeTime As Nullable<TimeSpan>
var nullable = videoFrame.relativeTime;
videoFrame.relativeTime = nullable;
Value
Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>

The relative time of the frame within the video stream.

Remarks

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

SoftwareBitmap SoftwareBitmap SoftwareBitmap SoftwareBitmap SoftwareBitmap

Gets the SoftwareBitmap object containing the pixel data of the video frame, when one is present.

public : SoftwareBitmap SoftwareBitmap { get; }
SoftwareBitmap SoftwareBitmap();
public SoftwareBitmap SoftwareBitmap { get; }
Public ReadOnly Property SoftwareBitmap As SoftwareBitmap
var softwareBitmap = videoFrame.softwareBitmap;
Value
SoftwareBitmap SoftwareBitmap SoftwareBitmap

The SoftwareBitmap object containing the pixel data of the video frame.

Remarks

The pixel data of a VideoFrame can be stored either in a Direct3DSurface or a SoftwareBitmap. This property will be null if the data for the frame is not stored in a SoftwareBitmap. If the data is stored in a software bitmap, you can access it using the Direct3DSurface property of the VideoFrame.

SystemRelativeTime SystemRelativeTime SystemRelativeTime SystemRelativeTime SystemRelativeTime

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

public : IReference<TimeSpan> SystemRelativeTime { get; set; }
IReference<TimeSpan> SystemRelativeTime(); void SystemRelativeTime(IReference<TimeSpan> systemrelativetime);
public Nullable<TimeSpan> SystemRelativeTime { get; set; }
Public ReadWrite Property SystemRelativeTime As Nullable<TimeSpan>
var nullable = videoFrame.systemRelativeTime;
videoFrame.systemRelativeTime = nullable;
Value
Nullable<TimeSpan> Nullable<TimeSpan> Nullable<TimeSpan>

A timestamp relative to the system.

Remarks

Use RelativeTime to get a timestamp that is relative to the video stream.

Type Type Type Type Type

Gets a string indicating the type of video data the video frame contains.

public : Platform::String Type { get; }
winrt::hstring Type();
public string Type { get; }
Public ReadOnly Property Type As string
var string = videoFrame.type;
Value
string string string

A string indicating the type of audio data the video frame contains.

Methods

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

Disposes of the object and associated resources.

public : void Close()
void Close() const;
// This member is not implemented in C#
' This member is not implemented in VB.Net
// This member is not implemented in JavaScript

CopyToAsync(VideoFrame) CopyToAsync(VideoFrame) CopyToAsync(VideoFrame) CopyToAsync(VideoFrame) CopyToAsync(VideoFrame)

Copies the current VideoFrame into a provided VideoFrame object.

public : IAsyncAction CopyToAsync(VideoFrame frame)
IAsyncAction CopyToAsync(VideoFrame frame) const;
public IAsyncAction CopyToAsync(VideoFrame frame)
Public Function CopyToAsync(frame As VideoFrame) As IAsyncAction
Windows.Media.VideoFrame.copyToAsync(frame).done( /* Your success and error handlers */ );
Parameters
frame
VideoFrame VideoFrame VideoFrame VideoFrame VideoFrame

The target video frame into which the current frame will be copied.

Returns

An asynchronous action.

Remarks

The target frame must have the same pixel format, width, height, and alpha mode as the source frame.

CopyToAsync(VideoFrame, IReference, IReference) CopyToAsync(VideoFrame, IReference, IReference) CopyToAsync(VideoFrame, IReference, IReference) CopyToAsync(VideoFrame, IReference, IReference) CopyToAsync(VideoFrame, IReference, IReference)

Prerelease. Copies the specified rectangle in the current VideoFrame into the specified rectangle of a provided VideoFrame object.

public : IAsyncAction CopyToAsync(VideoFrame frame, IReference<BitmapBounds> sourceBounds, IReference<BitmapBounds> destinationBounds)
IAsyncAction CopyToAsync(VideoFrame frame, IReference<BitmapBounds> sourceBounds, IReference<BitmapBounds> destinationBounds) const;
public IAsyncAction CopyToAsync(VideoFrame frame, Nullable<BitmapBounds> sourceBounds, Nullable<BitmapBounds> destinationBounds)
Public Function CopyToAsync(frame As VideoFrame, sourceBounds As Nullable<BitmapBounds>, destinationBounds As Nullable<BitmapBounds>) As IAsyncAction
Windows.Media.VideoFrame.copyToAsync(frame, sourceBounds, destinationBounds).done( /* Your success and error handlers */ );
Parameters
frame
VideoFrame VideoFrame VideoFrame VideoFrame VideoFrame

The target video frame into which the current frame will be copied.

sourceBounds
Nullable<BitmapBounds> Nullable<BitmapBounds> Nullable<BitmapBounds>

A BitmapBounds reference specifying the rectangle within the source frame that should be copied.

destinationBounds
Nullable<BitmapBounds> Nullable<BitmapBounds> Nullable<BitmapBounds>

A BitmapBounds reference specifying the rectangle within the target frame into which the source content is copied.

Returns

An asynchronous action.

Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32)

Prerelease. Creates a new instance of the VideoFrame class for which the image data is stored in an IDXGISurface allocated by the default Direct3D device.

public : static VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, int width, int height)
VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, int32_t width, int32_t height) const;
public static VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, Int32 width, Int32 height)
Public Static Function CreateAsDirect3D11SurfaceBacked(format As DirectXPixelFormat, width As Int32, height As Int32) As VideoFrame
var videoFrame = Windows.Media.VideoFrame.createAsDirect3D11SurfaceBacked(format, width, height);
Parameters
format
DirectXPixelFormat DirectXPixelFormat DirectXPixelFormat

A value from the DirectXPixelFormat enumeration, specifying the pixel format of the created VideoFrame. Not all pixel formats are supported. See the Remarks section for more information.

width
Int32 Int32 Int32

The width, in pixels, of the created VideoFrame.

height
Int32 Int32 Int32

The height, in pixels, of the created VideoFrame.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Remarks

The following pixel formats, defined in the DirectXPixelFormat enumeration, are supported by VideoFrame.

  • DirectXPixelFormat_R16G16B16A16UIntNormalized
  • DirectXPixelFormat_R8G8B8A8UIntNormalized
  • DirectXPixelFormat_B8G8R8X8UIntNormalized
  • DirectXPixelFormat_B8G8R8A8UIntNormalized
  • DirectXPixelFormat_NV12
  • DirectXPixelFormat_P010
  • DirectXPixelFormat_Yuy2
  • DirectXPixelFormat_R16UIntNormalized
  • DirectXPixelFormat_R8UIntNormalized

All other formats are unsupported. Attempting to create a VideoFrame with an unsupported format will cause the method to fail with a COM exception.

The overload of this method, CreateAsDirect3D11SurfaceBacked, allows you to supply the IDirect3DDevice that is used to allocate the backing surface of the video frame.

CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32, IDirect3DDevice) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32, IDirect3DDevice) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32, IDirect3DDevice) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32, IDirect3DDevice) CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat, Int32, Int32, IDirect3DDevice)

Prerelease. Creates a new instance of the VideoFrame class for which the image data is stored in an IDXGISurface allocated by the supplied Direct3D device.

public : static VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, int width, int height, IDirect3DDevice device)
VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, int32_t width, int32_t height, IDirect3DDevice device) const;
public static VideoFrame CreateAsDirect3D11SurfaceBacked(DirectXPixelFormat format, Int32 width, Int32 height, IDirect3DDevice device)
Public Static Function CreateAsDirect3D11SurfaceBacked(format As DirectXPixelFormat, width As Int32, height As Int32, device As IDirect3DDevice) As VideoFrame
var videoFrame = Windows.Media.VideoFrame.createAsDirect3D11SurfaceBacked(format, width, height, device);
Parameters
format
DirectXPixelFormat DirectXPixelFormat DirectXPixelFormat

A value from the DirectXPixelFormat enumeration, specifying the pixel format of the created VideoFrame. Not all pixel formats are supported. See the Remarks section for more information.

width
Int32 Int32 Int32

The width, in pixels, of the created VideoFrame.

height
Int32 Int32 Int32

The height, in pixels, of the created VideoFrame.

device
IDirect3DDevice IDirect3DDevice IDirect3DDevice

An IDirect3DDevice that is used to allocate the backing surface of the video frame.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Remarks

The following pixel formats, defined in the DirectXPixelFormat enumeration, are supported by VideoFrame.

  • DirectXPixelFormat_R16G16B16A16UIntNormalized
  • DirectXPixelFormat_R8G8B8A8UIntNormalized
  • DirectXPixelFormat_B8G8R8X8UIntNormalized
  • DirectXPixelFormat_B8G8R8A8UIntNormalized
  • DirectXPixelFormat_NV12
  • DirectXPixelFormat_P010
  • DirectXPixelFormat_Yuy2
  • DirectXPixelFormat_R16UIntNormalized
  • DirectXPixelFormat_R8UIntNormalized

All other formats are unsupported. Attempting to create a VideoFrame with an unsupported format will cause the method to fail with a COM exception.

If the device parameter is null, the IDXGISurface is allocated using the default Direct3D device.

CreateWithDirect3D11Surface(IDirect3DSurface) CreateWithDirect3D11Surface(IDirect3DSurface) CreateWithDirect3D11Surface(IDirect3DSurface) CreateWithDirect3D11Surface(IDirect3DSurface) CreateWithDirect3D11Surface(IDirect3DSurface)

Prerelease. Creates a new instance of the VideoFrame class for which the image data is stored in the provided IDXGISurface.

public : static VideoFrame CreateWithDirect3D11Surface(IDirect3DSurface surface)
VideoFrame CreateWithDirect3D11Surface(IDirect3DSurface surface) const;
public static VideoFrame CreateWithDirect3D11Surface(IDirect3DSurface surface)
Public Static Function CreateWithDirect3D11Surface(surface As IDirect3DSurface) As VideoFrame
var videoFrame = Windows.Media.VideoFrame.createWithDirect3D11Surface(surface);
Parameters
surface
IDirect3DSurface IDirect3DSurface IDirect3DSurface

The IDXGISurface in which the image data is stored.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Remarks

If the surface parameter is null, an argument exception will occur. The supplied IDXGISurface must use one of the supported pixel formats. VideoFrame supports the formats corresponding to the following DirectXPixelFormat values:

  • DirectXPixelFormat_R16G16B16A16UIntNormalized
  • DirectXPixelFormat_R8G8B8A8UIntNormalized
  • DirectXPixelFormat_B8G8R8X8UIntNormalized
  • DirectXPixelFormat_B8G8R8A8UIntNormalized
  • DirectXPixelFormat_NV12
  • DirectXPixelFormat_P010
  • DirectXPixelFormat_Yuy2
  • DirectXPixelFormat_R16UIntNormalized
  • DirectXPixelFormat_R8UIntNormalized

All other formats are unsupported. If a surface with an unsupported format is specified, a COM exception will be thrown.

CreateWithSoftwareBitmap(SoftwareBitmap) CreateWithSoftwareBitmap(SoftwareBitmap) CreateWithSoftwareBitmap(SoftwareBitmap) CreateWithSoftwareBitmap(SoftwareBitmap) CreateWithSoftwareBitmap(SoftwareBitmap)

Prerelease. Creates a new instance of the VideoFrame class from the provided SoftwareBitmap.

public : static VideoFrame CreateWithSoftwareBitmap(SoftwareBitmap bitmap)
VideoFrame CreateWithSoftwareBitmap(SoftwareBitmap bitmap) const;
public static VideoFrame CreateWithSoftwareBitmap(SoftwareBitmap bitmap)
Public Static Function CreateWithSoftwareBitmap(bitmap As SoftwareBitmap) As VideoFrame
var videoFrame = Windows.Media.VideoFrame.createWithSoftwareBitmap(bitmap);
Parameters
bitmap
SoftwareBitmap SoftwareBitmap SoftwareBitmap

The SoftwareBitmap from which the VideoFrame is created.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Remarks

If the bitmap parameter is null, an argument exception will be thrown.

Dispose() Dispose() Dispose()

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

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