The Surface Duo SDK Preview is getting an update – Feb 20,2020
Hello Dual Screen developers!
We are proud to be part of this growing community and excited to share with you the latest on the #SurfaceDuo SDK front in these devblogs.
Don’t forget to read our previous editions for additional Dev goodies, and let us know (feedback links below) on what else you would like us to cover.
For today’s blog on 02/20/2020, we are going to focus on the Surface Duo Emulator Image refresh (Yes, almost a palindrome, if you’re into numbers).
Summary of changes in the 02202020 update
We have spent the past few weeks with fixing some bugs with some great results. We have updated how we report the display size, modified the DisplayMask API to improve app compatibility, and fixed several bugs that our users have reported.
You can download the refresh image for Mac, Windows and Ubuntu using this link
Change #1: Changes to how size is reported to an App:
We have been busy setting up an App Compat lab where we test against the top apps from the Google Play Store.
We found some inconsistencies in how activity, window, and display metrics were returned to apps and games. We have made the changes to how size is reported so that the app gets sizes appropriate to the displays it is on. In the case of:
- For apps on a single display, windows and display metrics will be related to a single display
- For apps across both displays, window and display metrics will be in relation to both displays, including the display mask
Our Java and Kotlin samples have been updated to reflect this change.
Try it out on your app and let us know if you’ve seen any issues.
Change #2: Updates to DisplayMask API
Display Metrics based on apps window and DisplayMask API change to return hinge mask relative to apps window:
Display Mask has been updated to return a bounding rectangle relative to the display metrics based on the app context. When running in single screen the DisplayMask will now return an empty list it will not intersect with the window. When running in dual screen the display mask bounding rectangle shall identify the area under the hardware hinge in relation to the app window
As consumer of this API apps run in one of the following scenarios:
- App running in single screen mode: DisplayMask will be an empty list
- App running in spanned mode: DisplayMask = hinge mask rectangle
Note: a service that created a view at any point will fall into one of the categories above
Change #3: Surface Duo Image Build Flavor is now a USER build and not USERDEBUG
This image refresh contains a USER build flavor which will result in less logging and faster image access within the emulator.
Note that the ADB commands will continue to work as usual without the need to enable Developer Options in settings.
Figure 1: The Surface Duo emulator image with Drag and Drop Sample
Behind the scenes on these changes:
If you’re interested in the behind the scenes on these changes, this section is for you.
Apps query their active window and active display information using a common class – android.view.Display.
The common behaviors and API’s within android.view.Display are:
- Getting current App Windows metrics (getSize / getMetrics) which returns the display size available to the app adjusted for specific system décor (cut-outs, nav bar, etc.) and compatibility.
- When called within an activity with an app window this returns the size available to the app with specific system décor subtracted.
- When called within an activity without an app window this returns the full display size
- Getting the current “real” display metrics (getRealSize / getRealMetrics) which returns the display size available to the active WindowManager adjusted by any rotation. “Real” in this context is at times Windows Manager may run in a smaller display than the actual full available display.
The Surface Duo Emulator Image supports these standard API’s that apps depend on, but the API’s will further define “real” display based on current posture and app context.
If you would like to read more “behind-the-scenes” content, please let us know on the Surface Duo feedback forum.
Microsoft Surface Duo Emulator definitions
The Surface Duo emulator image has two displays. The gap between both displays is 84 pixels. The entire virtual display is represented as 2784×1800.
Android abstracts pixel size and resolution into a display-independent pixel metric so apps can use a single metric across devices. This is calculated as:
dp = (width in pixels * 160) / screen density
|Native resolution||Resolution in dp|
|Single Display||1350 x 1800||540 x 720|
|Dual Display + Mask||2784 x 1800||1114 x 720|
Per the Material Guidelines, this would be classified as:
|Single Portrait Width||540dp||large handset|
|Single & Dual Landscape Width||720dp||large handset|
Because the default behavior for any activity creating a window is to be launched on a single screen, the display metric return value to all non-windowed activities will also be updated to be the size of a single screen to reduce discrepancies in an app default launch behavior.
To keep within the bounds of a large handset, future Surface Duo devices would need to keep a single display within the bounds of:
- Portrait Width of 400-599dp or 2.5” – 3.74” (Surface Duo Emulator is 3.375”)
- Landscape width of 720-959dp or 4.5” – 5.99” (Surface Duo Emulator is 4.5”)
The minimum aspect ratio recommended for Android based phones is 4:3/3:4 (which is what Surface Duo is).
We’d love your feedback
We would love to hear from you about your experiences using the SDK and emulator.
Please reach out using our feedback forum and let us know how we can help you be more productive, ask questions, make suggestions, or upvote other suggestions.
Our online Docs are at https://docs.microsoft.com/dual-screen/ and in case you missed it, the M365 Dual Screen Developer day recordings are now available.
And as always, you can message me on Twitter or GitHub.
Guy Merin, Development Manager, Surface Duo Developer Experience Team