-
Notifications
You must be signed in to change notification settings - Fork 320
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Adding CameraCaptureUI Spec * Updating formatting * Updated IDL * Addressing review comments * Minor Updates * Update to template format * Updating to Microsoft::UI::WindowId, updated c# sample * Fixed typo * nit * Updated sample to maintain consistency * Resolving comments * Removing default namespace * Removed the note on capabilites * Sample update --------- Co-authored-by: Mike Hillberg <18429489+MikeHillberg@users.noreply.github.com>
- Loading branch information
1 parent
e47a762
commit dba0dd5
Showing
2 changed files
with
370 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,370 @@ | ||
| CameraCaptureUI API | ||
| === | ||
|
|
||
| This is the spec for proposal: [Issue #1034](https://github.com/microsoft/WindowsAppSDK/issues/1034) | ||
|
|
||
| This spec details the API of a new `CameraCaptureUI` in WinAppSDK, | ||
| enabling desktop applications such as WinUI3 to seamlessly integrate native camera capture | ||
| functionality across diverse Windows platforms. | ||
|
|
||
|
|
||
|
|
||
| # Background | ||
|
|
||
| The current OS | ||
| [CameraCaptureUI](https://docs.microsoft.com/uwp/api/Windows.Media.Capture.CameraCaptureUI), | ||
| primarily designed for UWP applications, | ||
| presents several challenges when used in desktop environments. | ||
| Key issues include the dependency on `CoreWindow`, | ||
| which are not compatible with desktop app frameworks and the lack of support for `IInitializeWithWindow`. | ||
| As a result, developers are forced to resort to workarounds involving interop interfaces and | ||
| additional code to integrate camera capture functionality into their WinUI 3 desktop applications. | ||
|
|
||
| In response to this feedback, this `CameraCaptureUI` API for WinAppSDK aims to provide | ||
| a streamlined solution that meets the expectations of our developer community. | ||
| The goal is to offer seamless integration of camera capture capabilities with | ||
| full feature parity across all Windows platforms supported by WinAppSDK. | ||
| This new API eliminates the need for cumbersome workarounds and | ||
| simplifies the process of incorporating camera functionality into desktop applications. | ||
|
|
||
|
|
||
| This new WinAppSDK version of the `CameraCaptureUI` is essentially the same as the existing public | ||
| [CameraCaptureUI](https://learn.microsoft.com/en-us/uwp/api/windows.media.capture.cameracaptureui?view=winrt-22621) | ||
| API, with a minor adjustment to the CameraCapture constructor to require a | ||
| [WindowId](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.WindowId). | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| # Conceptual pages | ||
|
|
||
| ## Capture a photo (C++) | ||
|
|
||
| A C++ example that tests whether a photo was successfully taken using the CaptureFileAsync method. | ||
|
|
||
| ```c++ | ||
| // Get the WindowId for the window | ||
| Microsoft::UI::WindowId windowId = this->AppWindow().Id(); | ||
|
|
||
| // Initialize CameraCaptureUI with a window handle | ||
| winrt::Microsoft::Windows::Media::Capture::CameraCaptureUI cameraUI(windowId); | ||
|
|
||
| // Configure Photo Settings | ||
| cameraUI.PhotoSettings().Format(CameraCaptureUIPhotoFormat::Jpeg); | ||
| cameraUI.PhotoSettings().AllowCropping(false); | ||
|
|
||
| // Capture a photo asynchronously | ||
| auto photo = co_await cameraUI.CaptureFileAsync(CameraCaptureUIMode::Photo); | ||
|
|
||
| // Assert the result | ||
| if (photo != nullptr) | ||
| { | ||
| // Log success if photo capture was successful | ||
| Log::Comment(L"Photo capture was successful."); | ||
| } | ||
| else | ||
| { | ||
| // Log error if photo capture failed or was canceled | ||
| Log::Error(L"Photo capture failed or was canceled."); | ||
| } | ||
| ``` | ||
| ## Capture a video (c#) | ||
| The code is from file | ||
| [CaptureVideo.xaml.cs](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/master/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/CameraCaptureUI%20Sample%20(Windows%208)/C%23) of the Camera capture UI C# sample with a small modification to include the window ID in the CameraCaptureUI constructor. | ||
| ```c# | ||
| // Get the WindowId for the window | ||
| Microsoft.UI.WindowId windowId = this.AppWindow.Id; | ||
| // Initialize CameraCaptureUI with a window handle | ||
| CameraCaptureUI dialog = new CameraCaptureUI(windowId); | ||
| // Configure Video Settings | ||
| dialog.VideoSettings.Format = CameraCaptureUIVideoFormat.Mp4; | ||
| // Capture a video asynchronously | ||
| StorageFile file = await dialog.CaptureFileAsync(CameraCaptureUIMode.Video); | ||
| if (file != null) | ||
| { | ||
| // Open the captured file for reading | ||
| using (IRandomAccessStream fileStream = await file.OpenAsync(FileAccessMode.Read)) | ||
| { | ||
| // Log success if video capture was successful | ||
| // Add any additional logic or UI updates here | ||
| } | ||
| } | ||
| else | ||
| { | ||
| // Log message if no video was captured | ||
| // Consider adding your own logging mechanism here | ||
| // For example: logger.Log("No video captured."); | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| # API Pages | ||
|
|
||
|
|
||
| ## CameraCaptureUI class | ||
|
|
||
| Provides a full window UI for capturing audio, video, and photos from a camera. | ||
| As well as controls for trimming video, time delayed capture, and camera settings. | ||
|
|
||
| This example shows how to use the CameraCaptureUI Class to take a picture. | ||
| The dialog with the user occurs when you call the asynchronous method CaptureFileAsync. | ||
|
|
||
| ```c# | ||
| // Using Microsoft.Windows.Media.Capture.CameraCaptureUI API to capture a photo | ||
| CameraCaptureUI dialog = new CameraCaptureUI(windowId); | ||
| Size aspectRatio = new Size(16, 9); | ||
| dialog.PhotoSettings.CroppedAspectRatio = aspectRatio; | ||
|
|
||
| StorageFile file = await dialog.CaptureFileAsync(CameraCaptureUIMode.Photo); | ||
| if(file != null) | ||
| { | ||
| // The user didn't cancel | ||
| this.ProcessFile(file); | ||
| } | ||
| ``` | ||
| Screenshot of the UI: | ||
|
|
||
|
|
||
|  | ||
|
|
||
|
|
||
| ## CameraCaptureUI constructor | ||
|
|
||
| | Name | Description | | ||
| |-|-| | ||
| | CameraCaptureUI(windowId) | Create a new CameraCaptureUI object.| | ||
|
|
||
|
|
||
| > Note: After you create a new CameraCaptureUI object, | ||
| you may want to set the PhotoSettings or VideoSettings property of the object before | ||
| calling CaptureFileAsync. | ||
|
|
||
| CameraCaptureUI provides a full window UI experience for capturing audio, video, and images. | ||
| It provides controls for setting a time delay on photo captures, trimming video, | ||
| and for adjusting the camera's settings such as video resolution, | ||
| the audio device, brightness, and contrast. | ||
|
|
||
| Call CaptureFileAsync to launch the UI. | ||
| The user has control over when to start the capture. | ||
| When the asynchronous CaptureFileAsync operation completes, a StorageFile object is returned. | ||
|
|
||
|
|
||
|
|
||
| ## CameraCaptureUI Properties | ||
|
|
||
| | Name | Description | Value | | ||
| |-|-|-| | ||
| |PhotoSettings| Provides settings for capturing photos. The settings include aspect ratio, image size, format, resolution, and whether or not cropping is allowed by the user interface (UI).|CameraCaptureUIPhotoCaptureSettings (An object containing settings for capturing photos) | | ||
| |VideoSettings| Provides settings for capturing videos. The settings include format, maximum resolution, maximum duration, and whether or not to allow trimming.| CameraCaptureUIVideoCaptureSettings (An object that provides settings for capturing videos) | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## CameraCaptureUI Methods | ||
|
|
||
| | Name | Description | Parameters | Returns | | ||
| |-|-|-|-| | ||
| | CaptureFileAsync(CameraCaptureUIMode) | Launches the CameraCaptureUI user interface.| __mode__ CameraCaptureUIMode | __IAsyncOperation< StorageFile >__ | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## CameraCaptureUIPhotoCaptureSettings Class | ||
| Provides settings for capturing photos with CameraCaptureUI. | ||
| The settings include aspect ratio, image size, format, resolution, | ||
| and whether or not cropping is allowed by the user interface (UI). | ||
|
|
||
| ## CameraCaptureUIPhotoCaptureSettings Properties | ||
|
|
||
| | Name | Description | Value | | ||
| |-|-|-| | ||
| | AllowCropping | Determines whether photo cropping will be enabled in the user interface for capture a photo.| Boolean | | ||
| | CroppedAspectRatio | The aspect ratio of the captured photo.| Windows.Foundation.Size | | ||
| | CroppedSizeInPixels |The exact size in pixels of the captured photo.| Windows.Foundation.Size | | ||
| | Format |Determines the format that captured photos will be stored in.| CameraCaptureUIPhotoFormat | | ||
| | MaxResolution | Determines the maximum resolution the user will be able to select. | CameraCaptureUIMaxPhotoResolution | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ## CameraCaptureUIVideoCaptureSettings Class | ||
| Provides settings for capturing videos. | ||
| The settings include format, maximum resolution, maximum duration, and whether or not to allow trimming. | ||
|
|
||
| ## CameraCaptureUIVideoCaptureSettings Properties | ||
| | Name | Description | Value | | ||
| |-|-|-| | ||
| | AllowTrimming | Determines whether the user can trim the captured video.| Boolean | | ||
| | Format | Determines the format that captured videos will be stored in.| CameraCaptureUIVideoFormat | | ||
| | MaxDurationInSeconds | The maximum duration of the video that the user can capture.| Single | | ||
| | MaxResolution | Determines the maximum resolution the user will be able to select.| CameraCaptureUIMaxVideoResolution | | ||
|
|
||
|
|
||
| ## CameraCaptureUIMode enum | ||
|
|
||
| Determines whether the user interface for capturing from the attached camera allows capture of photos, | ||
| videos, or both photos and videos. | ||
|
|
||
| | Name | Value | Description | | ||
| |-|-|-| | ||
| | PhotoOrVideo | 0 | The user interface allows capture of photos and videos. | | ||
| | Photo | 1 | The user interface allows capture of photos only.| | ||
| | Video | 2 | The user interface allows capture of videos only. | | ||
|
|
||
|
|
||
| ## CameraCaptureUIPhotoFormat enum | ||
| Determines the format for photos captured with CameraCaptureUI. | ||
|
|
||
| | Name | Value | Description | | ||
| |-|-|-| | ||
| | Jpeg | 0 |JPEG format. | | ||
| | Png | 1 | PNG format. | | ||
| | JpegXR | 2 | JPEG-XR format. | | ||
|
|
||
|
|
||
| ## CameraCaptureUIVideoFormat enum | ||
| Determines the format for saving captured videos. | ||
|
|
||
| | Name | Value | Description | | ||
| |-|-|-| | ||
| | Mp4 | 0 |MP4/H.264/AAC format.| | ||
| | Wmv | 1 | WMV format. | | ||
|
|
||
| ## CameraCaptureUIMaxPhotoResolution enum | ||
| Determines the highest resolution the user can select for capturing photos. | ||
|
|
||
| | Name | Value | Description | | ||
| |-|-|-| | ||
| | HighestAvailable | 0 | The user can select any resolution. | | ||
| | VerySmallQvga | 1 |The user can select resolutions up to 320 X 240, or a similar 16:9 resolution. | | ||
| | SmallVga | 2 | The user can select resolutions up to 320 X 240, or a similar 16:9 resolution.| | ||
| | MediumXga | 3 | The user can select resolutions up to 1024 X 768, or a similar 16:9 resolution. | | ||
| | Large3M | 4 | The user can select resolutions up to 1920 X 1080, or a similar 4:3 resolution. | | ||
| | VeryLarge5M | 5 | The user can select resolutions up to 5 MP.| | ||
|
|
||
|
|
||
| ## CameraCaptureUIMaxVideoResolution enum | ||
| Determines the highest resolution the user can select for capturing video. | ||
|
|
||
| | Name | Value | Description | | ||
| |-|-|-| | ||
| | HighestAvailable | 0 | The user can select any resolution. | | ||
| | LowDefinition | 1 | The user can select resolutions up to low definition resolutions.| | ||
| | StandardDefinition | 2 | The user can select resolutions up to standard definition resolutions.| | ||
| | HighDefinition | 3 | The user can select resolutions up to high definition resolutions. | | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| # API Details | ||
|
|
||
| > Note: all of this new WinAppSDK API is the same as the existing UWP | ||
| [CameraCaptureUI](https://docs.microsoft.com/uwp/api/Windows.Media.Capture.CameraCaptureUI) | ||
| API, only changing the constructor to take a | ||
| [WindowId](https://docs.microsoft.com/windows/windows-app-sdk/api/winrt/Microsoft.UI.WindowId). | ||
|
|
||
|
|
||
| ```c++ (but really MIDL3) | ||
| namespace Microsoft.Windows.Media.Capture | ||
| { | ||
| [contractversion(1)] | ||
| apicontract CameraCaptureUIContract {}; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| typedef enum CameraCaptureUIMode | ||
| { | ||
| PhotoOrVideo = 0, | ||
| Photo, | ||
| Video, | ||
| } CameraCaptureUIMode; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| typedef enum CameraCaptureUIPhotoFormat | ||
| { | ||
| Jpeg = 0, | ||
| Png, | ||
| JpegXR, | ||
| } CameraCaptureUIPhotoFormat; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| typedef enum CameraCaptureUIVideoFormat | ||
| { | ||
| Mp4 = 0, | ||
| Wmv, | ||
| } CameraCaptureUIVideoFormat; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| typedef enum CameraCaptureUIMaxVideoResolution | ||
| { | ||
| HighestAvailable = 0, | ||
| LowDefinition, | ||
| StandardDefinition, | ||
| HighDefinition, | ||
| } CameraCaptureUIMaxVideoResolution; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| typedef enum CameraCaptureUIMaxPhotoResolution | ||
| { | ||
| HighestAvailable = 0, | ||
| VerySmallQvga, | ||
| SmallVga, | ||
| MediumXga, | ||
| Large3M, | ||
| VeryLarge5M, | ||
| } CameraCaptureUIMaxPhotoResolution; | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| runtimeclass CameraCaptureUIPhotoCaptureSettings | ||
| { | ||
| CameraCaptureUIPhotoCaptureSettings(); | ||
|
|
||
| Boolean AllowCropping; | ||
| Windows.Foundation.Size CroppedAspectRatio; | ||
| Windows.Foundation.Size CroppedSizeInPixels; | ||
| Microsoft.Windows.Media.Capture.CameraCaptureUIPhotoFormat Format; | ||
| Microsoft.Windows.Media.Capture.CameraCaptureUIMaxPhotoResolution MaxResolution; | ||
| } | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| runtimeclass CameraCaptureUIVideoCaptureSettings | ||
| { | ||
| CameraCaptureUIVideoCaptureSettings(); | ||
|
|
||
| Boolean AllowTrimming; | ||
| Microsoft.Windows.Media.Capture.CameraCaptureUIVideoFormat Format; | ||
| Single MaxDurationInSeconds; | ||
| Microsoft.Windows.Media.Capture.CameraCaptureUIMaxVideoResolution MaxResolution; | ||
| } | ||
|
|
||
| [contract(CameraCaptureUIContract, 1)] | ||
| [threading(sta), | ||
| marshaling_behavior(none)] | ||
| runtimeclass CameraCaptureUI | ||
| { | ||
| CameraCaptureUI(Microsoft.UI.WindowId window); | ||
|
|
||
| CameraCaptureUIPhotoCaptureSettings PhotoSettings{ get; }; | ||
| CameraCaptureUIVideoCaptureSettings VideoSettings{ get; }; | ||
|
|
||
| Windows.Foundation.IAsyncOperation<Windows.Storage.StorageFile> CaptureFileAsync(Microsoft.Windows.Media.Capture.CameraCaptureUIMode mode); | ||
| } | ||
| } | ||
| ``` |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.