/// <summary>
/// Create a video track source using a local video capture device (webcam).
///
/// The video track source produces raw video frames by capturing them from a capture device accessible
/// from the local host machine, generally a USB webcam or built-in device camera. The video source
/// initially starts in the capturing state, and will remain live for as long as the source is alive.
/// Once the source is not live anymore (ended), it cannot be restarted. A new source must be created to
/// use the same video capture device again.
///
/// The source can be used to create one or more local video tracks (<see cref="LocalVideoTrack"/>), which
/// once added to a video transceiver allow the video frames to be sent to a remote peer. The source itself
/// is not associated with any peer connection, and can be used to create local video tracks from multiple
/// peer connections at once, thereby being shared amongst those peer connections.
///
/// The source is owned by the user, who must ensure it stays alive while being in use by at least one local
/// video track. Once it is not used anymore, the user is in charge of disposing of the source. Disposing of
/// a source still in use by a local video track is undefined behavior.
/// </summary>
/// <param name="initConfig">Optional configuration to initialize the video capture on the device.</param>
/// <returns>The newly create video track source.</returns>
/// <remarks>
/// On UWP this requires the "webcam" capability.
/// See <see href="https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations"/>
/// for more details.
///
/// The video capture device may be accessed several times during the initializing process,
/// generally once for listing and validating the capture format, and once for actually starting
/// the video capture. This is a limitation of the OS and/or hardware.
///
/// Note that the capture device must support a capture format with the given constraints of profile
/// ID or kind, capture resolution, and framerate, otherwise the call will fail. That is, there is no
/// fallback mechanism selecting a closest match. Developers should use
/// <see cref="PeerConnection.GetVideoCaptureFormatsAsync(string)"/> to list the supported formats ahead
/// of calling <see cref="CreateAsync(LocalVideoDeviceInitConfig)"/>, and can build their own
/// fallback mechanism on top of this call if needed.
/// </remarks>
/// <example>
/// Create a video track source with Mixed Reality Capture (MRC) enabled.
/// This assumes that the platform supports MRC. Note that if MRC is not available
/// the call will still succeed, but will return a track without MRC enabled.
/// <code>
/// var initConfig = new LocalVideoDeviceInitConfig
/// {
/// enableMrc = true
/// };
/// var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);
/// </code>
/// Create a video track source from a local webcam, asking for a capture format suited for video conferencing,
/// and a target framerate of 30 frames per second (FPS). The implementation will select an appropriate
/// capture resolution. This assumes that the device supports video profiles, and has at least one capture
/// format supporting exactly 30 FPS capture associated with the VideoConferencing profile. Otherwise the call
/// will fail.
/// <code>
/// var initConfig = new LocalVideoDeviceInitConfig
/// {
/// videoProfileKind = VideoProfileKind.VideoConferencing,
/// framerate = 30.0
/// };
/// var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);
/// </code>
/// </example>
/// <seealso cref="LocalVideoTrack.CreateFromSource(VideoTrackSource, LocalVideoTrackInitConfig)"/>
public static Task <VideoTrackSource> CreateAsync(LocalVideoDeviceInitConfig initConfig = null)
{
return(Task.Run(() =>
{
// On UWP this cannot be called from the main UI thread, so always call it from
// a background worker thread.
var config = new DeviceVideoTrackSourceInterop.LocalVideoDeviceMarshalInitConfig(initConfig);
uint ret = DeviceVideoTrackSourceInterop.DeviceVideoTrackSource_Create(in config, out DeviceVideoTrackSourceHandle handle);
Utils.ThrowOnErrorCode(ret);
return (VideoTrackSource) new DeviceVideoTrackSource(handle);
}));
}
/// <summary>
/// Create a video track source using a local video capture device (webcam).
///
/// The video track source produces raw video frames by capturing them from a capture device accessible
/// from the local host machine, generally a USB webcam or built-in device camera. The video source
/// initially starts in the capturing state, and will remain live for as long as the source is alive.
/// Once the source is not live anymore (ended), it cannot be restarted. A new source must be created to
/// use the same video capture device again.
///
/// The source can be used to create one or more local video tracks (<see cref="LocalVideoTrack"/>), which
/// once added to a video transceiver allow the video frames to be sent to a remote peer. The source itself
/// is not associated with any peer connection, and can be used to create local video tracks from multiple
/// peer connections at once, thereby being shared amongst those peer connections.
///
/// The source is owned by the user, who must ensure it stays alive while being in use by at least one local
/// video track. Once it is not used anymore, the user is in charge of disposing of the source. Disposing of
/// a source still in use by a local video track is undefined behavior.
/// </summary>
/// <param name="initConfig">Optional configuration to initialize the video capture on the device.</param>
/// <returns>The newly create video track source.</returns>
/// <remarks>
/// On UWP this requires the "webcam" capability.
/// See <see href="https://docs.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations"/>
/// for more details.
///
/// The video capture device may be accessed several times during the initializing process,
/// generally once for listing and validating the capture format, and once for actually starting
/// the video capture. This is a limitation of the OS and/or hardware.
///
/// Note that the capture device must support a capture format with the given constraints of profile
/// ID or kind, capture resolution, and framerate, otherwise the call will fail. That is, there is no
/// fallback mechanism selecting a closest match. Developers should use <see cref="GetCaptureFormatsAsync(string)"/>
/// to list the supported formats ahead of calling <see cref="CreateAsync(LocalVideoDeviceInitConfig)"/>, and can
/// build their own fallback mechanism on top of this call if needed.
/// </remarks>
/// <example>
/// Create a video track source with Mixed Reality Capture (MRC) enabled.
/// This assumes that the platform supports MRC. Note that if MRC is not available
/// the call will still succeed, but will return a track without MRC enabled.
/// <code>
/// var initConfig = new LocalVideoDeviceInitConfig
/// {
/// enableMrc = true
/// };
/// var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);
/// </code>
/// Create a video track source from a local webcam, asking for a capture format suited for video conferencing,
/// and a target framerate of 30 frames per second (FPS). The implementation will select an appropriate
/// capture resolution. This assumes that the device supports video profiles, and has at least one capture
/// format supporting exactly 30 FPS capture associated with the VideoConferencing profile. Otherwise the call
/// will fail.
/// <code>
/// var initConfig = new LocalVideoDeviceInitConfig
/// {
/// videoProfileKind = VideoProfileKind.VideoConferencing,
/// framerate = 30.0
/// };
/// var videoSource = await VideoTrackSource.CreateFromDeviceAsync(initConfig);
/// </code>
/// </example>
/// <seealso cref="LocalVideoTrack.CreateFromSource(VideoTrackSource, LocalVideoTrackInitConfig)"/>
public static Task <DeviceVideoTrackSource> CreateAsync(LocalVideoDeviceInitConfig initConfig = null)
{
// Ensure the logging system is ready before using PInvoke.
MainEventSource.Log.Initialize();
return(Task.Run(() =>
{
// On UWP this cannot be called from the main UI thread, so always call it from
// a background worker thread.
var config = new DeviceVideoTrackSourceInterop.LocalVideoDeviceMarshalInitConfig(initConfig);
uint ret = DeviceVideoTrackSourceInterop.DeviceVideoTrackSource_Create(in config, out DeviceVideoTrackSourceHandle handle);
Utils.ThrowOnErrorCode(ret);
return new DeviceVideoTrackSource(handle);
}));
}
