From 5fa7c5d081eb53788b05082e163ed20525a315c4 Mon Sep 17 00:00:00 2001 From: Mike Hillberg <18429489+MikeHillberg@users.noreply.github.com> Date: Tue, 6 Aug 2024 10:22:22 -0700 Subject: [PATCH] Update to template format --- specs/CameraCaptureUI/CameraCaptureUI.md | 295 ++++++++++++++--------- 1 file changed, 185 insertions(+), 110 deletions(-) diff --git a/specs/CameraCaptureUI/CameraCaptureUI.md b/specs/CameraCaptureUI/CameraCaptureUI.md index 52d3c7ec35..9bb05ff27e 100644 --- a/specs/CameraCaptureUI/CameraCaptureUI.md +++ b/specs/CameraCaptureUI/CameraCaptureUI.md @@ -1,29 +1,141 @@ -# 1. CameraCaptureUI API +CameraCaptureUI API +=== This is the spec for proposal: [Issue #1034](https://github.com/microsoft/WindowsAppSDK/issues/1034) -This spec details the implementation of CameraCaptureUI, enabling WinUI 3 desktop applications to seamlessly integrate native camera capture functionality across diverse Windows platforms. +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. -# 2. Background -The current OS CameraCaptureUI implementation, 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, the 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. +# 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. -# 3. Description -Winappsdk version of 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) WinRT API, with a minor adjustment to the CameraCapture constructor to accept a windowID in the constructor for enhanced integration capabilities with 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). -The ***API*** includes the following key components: -## 3.1 CameraCaptureUI -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. + +# Conceptual pages + +*Todo - Replace Windows.UI.WindowId with Microsoft.UI.WindowId post testing.* +## Capture a photo (C++) + +A C++ example that tests whether a photo was successfully taken using the CaptureFileAsync method. + +```c++ + // Initialize CameraCaptureUI with a window handle (Foreground Window in this example) + auto parentWindow = ::GetForegroundWindow(); + winrt::Windows::UI::WindowId windowId{ reinterpret_cast(parentWindow) }; + 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 photoOperation = cameraUI.CaptureFileAsync(CameraCaptureUIMode::Photo); + auto photo = photoOperation.get(); // Get the result synchronously + + // 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 handle of the foreground window +IntPtr parentWindow = NativeMethods.GetForegroundWindow(); + +// Create a WindowId from the window handle +Windows.UI.WindowId windowId = new WindowId(parentWindow.ToInt64()); + +// Initialize CameraCaptureUI with a specific app window handle (12345 in this case) +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."); +} + +// NativeMethods class to access native Win32 functions +internal static class NativeMethods +{ + [System.Runtime.InteropServices.DllImport("user32.dll")] + internal static extern IntPtr GetForegroundWindow(); +} +``` + + + + + + + + + +# 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); @@ -38,39 +150,63 @@ Screenshot of the UI: ![Screenshot](CameraCaptureUI_Snapshot.png) -### 3.1.1 Constructor (The Change Introduced) +## 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(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. + +> Note: +You should not specify the webcam or microphone capabilities in your app manifest file if you are using CameraCaptureUI. +If you do so, your app will be displayed in the device's camera privacy settings, +but even if the user denies camera access to your app, +it will not prevent the CameraCaptureUI from capturing media. +This is because the Windows built-in camera app is a trusted first-party app that requires +the user to initiate photo, audio, and video capture with a button press. +Your app may fail Windows Application Certification Kit certification when submitted to +the Store if you specify the webcam or microphone capabilities when using CameraCaptureUI. + + + +## CameraCaptureUI Properties -### 3.1.2 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) | -### 3.1.3 Methods + + + +## CameraCaptureUI Methods | Name | Description | Parameters | Returns | |-|-|-|-| | CaptureFileAsync(CameraCaptureUIMode) | Launches the CameraCaptureUI user interface.| __mode__ CameraCaptureUIMode | __IAsyncOperation< StorageFile >__ | -### 3.1.4 Remarks -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. -`` Note: -You should not specify the webcam or microphone capabilities in your app manifest file if you are using CameraCaptureUI. If you do so, your app will be displayed in the device's camera privacy settings, but even if the user denies camera access to your app, it will not prevent the CameraCaptureUI from capturing media. This is because the Windows built-in camera app is a trusted first-party app that requires the user to initiate photo, audio, and video capture with a button press. Your app may fail Windows Application Certification Kit certification when submitted to the Store if you specify the webcam or microphone capabilities when using CameraCaptureUI. -`` -## 3.2 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 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). -### Properties +## CameraCaptureUIPhotoCaptureSettings Properties | Name | Description | Value | |-|-|-| @@ -80,10 +216,14 @@ Provides settings for capturing photos with CameraCaptureUI. The settings includ | 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 | -## 3.3 CameraCaptureUIVideoCaptureSettings Class -Provides settings for capturing videos. The settings include format, maximum resolution, maximum duration, and whether or not to allow trimming. -### Properties + + +## 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 | @@ -92,12 +232,10 @@ Provides settings for capturing videos. The settings include format, maximum res | MaxResolution | Determines the maximum resolution the user will be able to select.| CameraCaptureUIMaxVideoResolution | -## 3.4 Enums -All existing enumerated values from the CameraCapture class are brought over as-is to the Windows App SDK version as well. +## CameraCaptureUIMode enum -#### 3.4.1 CameraCaptureUIMode - -Determines whether the user interface for capturing from the attached camera allows capture of photos, videos, or both photos and videos. +Determines whether the user interface for capturing from the attached camera allows capture of photos, +videos, or both photos and videos. | Name | Value | Description | |-|-|-| @@ -105,7 +243,8 @@ Determines whether the user interface for capturing from the attached camera all | Photo | 1 | The user interface allows capture of photos only.| | Video | 2 | The user interface allows capture of videos only. | -#### 3.4.2 CameraCaptureUIPhotoFormat + +## CameraCaptureUIPhotoFormat enum Determines the format for photos captured with CameraCaptureUI. | Name | Value | Description | @@ -114,7 +253,8 @@ Determines the format for photos captured with CameraCaptureUI. | Png | 1 | PNG format. | | JpegXR | 2 | JPEG-XR format. | -#### 3.4.3 CameraCaptureUIVideoFormat + +## CameraCaptureUIVideoFormat enum Determines the format for saving captured videos. | Name | Value | Description | @@ -122,7 +262,7 @@ Determines the format for saving captured videos. | Mp4 | 0 |MP4/H.264/AAC format.| | Wmv | 1 | WMV format. | -#### 3.4.4 CameraCaptureUIMaxPhotoResolution +## CameraCaptureUIMaxPhotoResolution enum Determines the highest resolution the user can select for capturing photos. | Name | Value | Description | @@ -135,7 +275,7 @@ Determines the highest resolution the user can select for capturing photos. | VeryLarge5M | 5 | The user can select resolutions up to 5 MP.| -#### 3.4.5 CameraCaptureUIMaxVideoResolution +## CameraCaptureUIMaxVideoResolution enum Determines the highest resolution the user can select for capturing video. | Name | Value | Description | @@ -145,84 +285,19 @@ Determines the highest resolution the user can select for capturing video. | StandardDefinition | 2 | The user can select resolutions up to standard definition resolutions.| | HighDefinition | 3 | The user can select resolutions up to high definition resolutions. | -# 4. Examples -*Todo - Replace Windows.UI.WindowId with Microsoft.UI.WindowId post testing.* -## 4.1 Capture a photo (C++) -A C++ example that tests whether a photo was successfully taken using the CaptureFileAsync method. -```c++ - // Initialize CameraCaptureUI with a window handle (Foreground Window in this example) - auto parentWindow = ::GetForegroundWindow(); - winrt::Windows::UI::WindowId windowId{ reinterpret_cast(parentWindow) }; - 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 photoOperation = cameraUI.CaptureFileAsync(CameraCaptureUIMode::Photo); - auto photo = photoOperation.get(); // Get the result synchronously +# API Details - // 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."); - } - ``` - - ## 4.2 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 handle of the foreground window -IntPtr parentWindow = NativeMethods.GetForegroundWindow(); - -// Create a WindowId from the window handle -Windows.UI.WindowId windowId = new WindowId(parentWindow.ToInt64()); - -// Initialize CameraCaptureUI with a specific app window handle (12345 in this case) -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."); -} - -// NativeMethods class to access native Win32 functions -internal static class NativeMethods -{ - [System.Runtime.InteropServices.DllImport("user32.dll")] - internal static extern IntPtr GetForegroundWindow(); -} -``` - -# 5. Interface Definition +> 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 {