/// <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); })); }