Release Notes

Microsoft Surface 2.0 SDK Microsoft Surface 2.0 Runtime

Version: June, 2011

Copyright
This document is provided for informational purposes only, and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results from the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, financial and other data, and events depicted herein, are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, places, financial or other data, or events is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. 2010, 2011 Microsoft Corporation. All rights reserved. Microsoft, DirectX, Expression Blend, Microsoft Surface, Windows, Windows Vista, Visual C#, Visual Studio, and XNA are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.

Contents
Introduction....................................................................................................................................................................... 4 Surface Installers.............................................................................................................................................................. 4 Requirements.................................................................................................................................................................... 4 End-User Requirements....................................................................................................................................... 4 Developer Requirements .................................................................................................................................... 4 What's New ....................................................................................................................................................................... 5 Application Migration Tool ..................................................................................................................................... 5 Application Registration .......................................................................................................................................... 5 Attract Application ..................................................................................................................................................... 6 Configuration Editor .................................................................................................................................................. 6 ElementMenu Control............................................................................................................................................... 6 Gestures ......................................................................................................................................................................... 6 Hardware Capabilities ............................................................................................................................................... 6 Reach Profile / HiDef Profile ................................................................................................................................... 7 The Cloth SDK Sample ............................................................................ Error! Bookmark not defined. HID-based Input ......................................................................................................................................................... 7 Manipulations and Inertia ....................................................................................................................................... 8 Rich Input ...................................................................................................................................................................... 8 Samples .......................................................................................................................................................................... 8 Surface Controls .......................................................................................................................................................... 8 Surface System ............................................................................................................................................................ 8 Tags and Object Routing ......................................................................................................................................... 9 Tools ................................................................................................................................................................................ 9 Touch Support ............................................................................................................................................................. 9 User Controls................................................................................................................................................................ 9 Visual Studio Integration ......................................................................................................................................... 9

API Changes ................................................................................................................................................................... 10 Application Registration ................................................................................................................................... 10 Detecting Hardware Capabilities .................................................................................................................. 10 Manipulations and Inertia................................................................................................................................ 10 Tag APIs and Object Recognition ................................................................................................................. 10 Tap and Hold Gestures ..................................................................................................................................... 11 Surface Colors ...................................................................................................................................................... 11 Surface Stress ....................................................................................................................................................... 11 Version Numbers in Assemblies .................................................................................................................... 11 Known Issues ................................................................................................................................................................. 11 APIs and Controls .................................................................................................................................................... 11 Templating ElementMenu and the Library Controls ............................................................................. 11 ElementMenu Control ....................................................................................................................................... 11 LibraryContainer Control.................................................................................................................................. 11 Input Simulator Tool............................................................................................................................................... 12 Input Simulator Stops Working if Display Settings are Changed ..................................................... 12 Cursor freezes when a User Account Control dialog box appears or if you press Ctrl+Alt+Del while Input Simulator is running ................................................................................................................... 12 Promoted Mouse Events....................................................................................................................................... 12 MouseEventArgs.StylusDevice is null .......................................................................................................... 12 Related Documents and Resources ...................................................................................................................... 12

Introduction
This document describes the current features and known issues for the Microsoft Surface 2.0 SDK and the Surface 2.0 runtime.

Surface Installers
The following installers are available for the Surface 2.0 platform: Hardware Installer The hardware installer comes preinstalled on devices made for Surface 2.0. It contains the drivers necessary for rich multi-touch input, the Surface reference assemblies, and Windows integration components (Surface Mode and Windows Mode support). Surface Shell is installed by the hardware installer. To test your application integration with Surface Shell, you must run it on hardware made for Surface 2.0. SDK Installer The SDK installer includes all the components you need to develop a Surface application, including reference assemblies, Visual Studio integration components (design time components and templates), samples, and tools like the new Surface Input Simulator, Input Visualizer and Surface Stress. The SDK installer does not include Surface Shell. Runtime Installer The runtime installer contains Surface reference assemblies. The runtime installer provides redistributable rights. You redistribute the runtime if your application will be installed and run on devices not made for Surface.

Requirements
End-User Requirements
To run Surface 2.0 applications in a consumer environment, we recommend that you use a device made for Surface to make full use of all Surface 2.0 environment features (Surface Shell, 50 simultaneous touch points, finger and blob recognition, tagged objects, detection of the orientation of touches, tilted display, rotated display, specialized controls, and so on). Surface 2.0 applications also run on Windows 7 Touch computers.

Developer Requirements
To develop Surface applications, a developer must have a computer that meets the following requirements:

Operating System (OS) Development Environment

Windows 7. Visual Studio 2010, Express or full edition. Surface 2.0. .NET Framework 4 (required for creating Presentation layer applications). XNA Game Studio 4.0 (optional, can be used with Core layer APIs). A computer that supports Windows 7 (with or without touch functionality), or a device made for Surface 2.0.

Software Developer Kit (SDK)

Hardware

A DirectX 10-capable graphics card (required to support most scenarios, and to enable the XNA HiDef profile). Recommended specifications: 4 GB RAM, 2.6 GHz dual core processor, 100 GB disk space.

Other recommended settings

Set your display resolution to 96 DPI if you will be using Input Simulator.

What's New
For a complete list of what's new, see the "What's New in Surface 2.0" topic in the Surface SDK documentation.

Application Migration Tool

You can use the Surface Migration PowerToy to help convert Surface 1.0 SP1 projects to Surface 2.0.

Application Registration
The schema of the application-registration XML file has changed due to the new generic tag format. Additionally, application previews are no longer supported. For more information, see the topic "Registering Standard Applications" in the Surface SDK documentation.

Attract Application
There is now only one Attract application, redesigned with new graphics and sound. The Attract application changes with the Surface color scheme. Surface administrators can configure the background image and other settings for the Attract application by using the Surface Configuration Editor.

Configuration Editor
Devices made for Surface now include a Surface Configuration Editor. You can use the Configuration Editor to quickly configure the Attract application, configure how applications appear in Launcher, enable single-application mode, change the globalization settings for Surface Shell, and configure the error and out-of-order screens. Some of these tasks were previously possible only by changing registry keys. The Surface Configuration Editor can be opened from the desktop shortcut on a device made for Surface.

ElementMenu Control
The visual and interaction design of the Microsoft.Surface.Presentation.Controls.ElementMenu control has been fine-tuned and uses new icons. The icons are provided as resources in the Controls Box sample. You can use any of the icons in other areas of your application.

Gestures
The syntax for responding to "tap" and "press-and-hold" gestures has changed. In Surface 1.0 SP1, the events were part of the base Microsoft.Surface.Presentation.Controls.SurfaceControl class. Now, you can use the attached events of the Microsoft.Surface.Presentation.Intput.TouchExtensions class.

Hardware Capabilities
You can use the Surface SDK to develop applications that will run on devices made for Surface and Windows Touch computers. Devices made for Surface are produced by third-party manufacturers. Individual devices and displays might differ in the following hardware capabilities: The display size and resolution. The maximum number of simultaneous touch points. The detection of the orientation of a touch point. The reporting of touch bounds or touch geometry. The detection of finger touch input (as well as blob touch input).

The detection of tagged objects. The detection of the tilt of the interactive device. The working area and the bounds of the interactive surface.

You can use the members of the Presentation layer and Core layer InteractiveSurfaceDevice classes to determine hardware capabilities.

Reach Profile / HiDef Profile

Applications created with the Surface Application (XNA Game Studio 4.0) project template in Visual Studio specify the Reach graphics profile by default. If you want to run your XNA-based application on hardware that supports the HiDef profile (to access the complete XNA Game Studio API), right-click your project in Visual Studio, click Properties, and then, on the XNA Game Studio tab, change the Game profile setting to Use HiDef to access the complete API (including features unavailable for windows Phone). The RawImage Visualizer sample in the Surface SDK requires the XNA high-definition graphics profile and therefore runs only on systems with DirectX 10-capable graphics cards.

HID-based Input
Human Interface Device (HID) is the protocol that most mice, keyboards, and digitizers use to send data to the Windows operating system. Surface software architecture uses HID-based input. Input on a touch-enabled Windows 7 PC is routed through the same path as input on hardware made for Surface 2.0. HID-based input provides the following advantages: A better out-of-box experience for the hardware administrator. A mouse and keyboard are no longer needed to set up hardware made for Surface 2.0 or perform administrative tasks. A simplified developer experience. You can write Surface 2.0 applications that will run on both hardware made for Surface 2.0 and touch-enabled Windows 7 PCs. A consistent UI experience between Surface controls and non-Surface controls. For example, controls that are hosted outside of a Surface window (such as the ActiveXbased WebBrowser control in WPF) also receive Surface input. You cannot use the Surface 2.0 SDK on Surface 1.0 hardware units because those units were not designed to provide HID input. You can, however, use the Surface Input Simulator to test your Surface 2.0 applications on a Windows 7 PC.

Manipulations and Inertia

There is no manipulation processor (Affine2DManipulationProcessor) in the Core layer or Presentation layer anymore. Manipulation functionality is included in WPF 4.0 and XNA 4.0. To use manipulations and inertia, use the classes of the System.Windows.Input.Manipulation namespace instead.

Rich Input
Surface software architecture now uses HID-based input. Input on a Windows Touch computer is routed through the same path as input on device made for Surface. The following new and redesigned input drivers provide touch and image data from OEM hardware to the Surface system: Surface VIP driver. Input Simulation driver. Image data channel.

Samples
New and updated WPF and XNA samples demonstrate key development concepts. A batch file is included to install and register the samples on a device made for Surface. On a Windows Touch computer, you can run the samples from Visual Studio.

Surface Controls
The Surface WPF controls now support local and inherited mouse, touch, and stylus events and methods. Additionally, the Surface WPF controls have been restyled to provide a more simplified design that emphasizes content and ease of use. There are four color schemes that can be chosen by the administrator. If you use the default templates of Surface WPF controls, or if you bind XAML properties to the Surface color resources, the appearance of your application will automatically change to match the color scheme chosen by the administrator.

Surface System
Improvements to the Microsoft.Surface APIs enable application integration with the Surface platform, providing access to system events, language settings, notifications, and keyboard events.

Applications can reference the Surface system assembly on either devices made for Surface or Windows Touch computers. Applications use equivalents in the Windows 7 environment when the Surface environment (in other words, Surface Shell running on a device made for Surface) is not present.

Tags and Object Routing

The concepts of "identity" and "byte" tags have been retired in Surface 2.0. Tag APIs have been redesigned to be generic. As a result, in the future, you may be able to use different tag types with the same APIs. The Application Registration XML schema has been updated to use the concept of a more generic tag. The physical attributes of object tags are now defined in an Object Set XML file instead of in a registry key.

Tools
The Input Simulator tool has been improved to simulate all types of touch input, including the orientation of touch points, and the tilt of the interactive device. Additionally, the Surface Stress tool now requires Administrator privileges.

Touch Support
WPF 4.0 controls now support touch input as well as stylus and mouse input. Because the Surface controls inherit from WPF controls, the WPF touch input functionality is now inherited. The touch-related APIs of the Core layer have been renamed to be more similar to the WPF touch APIs.

User Controls
The SurfaceUserControl class has been removed in Surface 2.0. The SurfaceUserControl class was required in Surface 1.0 SP1 to add touch support to user controls. However, touch support has been added to the UserControl class in .NET Framework 4.

Visual Studio Integration

You can use Microsoft Visual Studio 2010 (Express or full edition) to create Surface 2.0 applications. The Surface SDK installs a WPF project template for creating Presentation layer applications, and an XNA project template for creating Core layer applications that use XNA. Both templates use C#. The project templates generate the code necessary to interact with

Surface Shell on a device made for Surface. Additionally, Surface controls are available in the Visual Studio Toolbox when you are working in a Presentation layer project.

API Changes
For a complete list of API changes, see the topic "API Changes in Surface 2.0" in the Surface SDK documentation. For help converting a project from Surface 1.0 SP1 to Surface 2.0, use the Surface Migration PowerToy.

Application Registration
The application registration XML file has been updated to use the more generic tag APIs and to remove the need for a preview image.

Detecting Hardware Capabilities

Some hardware capabilities on the extended input device (on the Microsoft.Surface.Presentation.TouchExtensions class) were moved to Microsoft.Surface.Presentation.InteractiveSurfaceDevice. This was done because the recognition of touch capabilities was dependent on the actual hardware support, not on the nature of the specific touch device. Microsoft.Surface.Core.InteractiveSurface.DefaultInteractiveSurface was renamed to Microsoft.Surface.Core.InteractiveSurface.PrimaryInteractiveSurfaceDevice, and its type was changed to Microsoft.Surface.Core.InteractiveSurfaceDevice. Some of the members of Microsoft.Surface.Core.InteractiveSurface were moved to Microsoft.Surface.Core.InteractiveSurfaceDevice to be consistent with the usage of the presentation layer InteractiveSurfaceDevice.

Manipulations and Inertia

Manipulation functionality has been added to .NET 4 to the System.Windows.Input namespace. Surface APIs now inherit most manipulation functionality from that namespace.

Tag APIs and Object Recognition

Byte tags and identity tags have been replaced by a more generic tag type, defined in Core layer and Presentation layer TagData structures. You must manually update your code and the tag definitions in your application registration XML file, and register tag objects using the new XML file format instead of registering tags in the registry.

Tap and Hold Gestures

Tap and hold events have been moved to routed events in the Microsoft.Surface.Presentation.Input.TouchExtensions class. WPF Gesture events now use TouchEventArgs instead of InputEventArgs. This increases the consistency with other WPF touch-related APIs.

Surface Colors
New APIs (including Microsoft.Surface.Presentation.SurfaceColors) support the four color schemes that are available to Presentation layer applications.

Surface Stress
The Surface Stress tool requires Administrator privileges to run.

Version Numbers in Assemblies

The version number in the assemblies has been updated to v2.0. For example, in a Presentation layer application, the reference to the resource dictionary must be updated to <ResourceDictionary Source="/Microsoft.Surface.Presentation.Generic;v2.0.0.0; .../>

Known Issues
APIs and Controls
Templating ElementMenu and the Library Controls
These controls do not support templating.

ElementMenu Control
Do not add more than 8 items to an ElementMenu control, nor more than 7 items to an ElementMenuItem control.

LibraryContainer Control
If you override the MinWidth and MinHeight properties of a Microsoft.Surface.Presentation.Controls.LibraryContainer control in stack view mode and set them to a value smaller than the default minimum width and height, group labels will not appear in stack view mode.

Input Simulator Tool

Input Simulator Stops Working if Display Settings are Changed
The Input Simulator tool does not simulate input correctly if the resolution or layout of the screen is changed while it is running. If you want to change the resolution of your system, close Input Simulator, change the resolution, and then reopen Input Simulator.

Cursor freezes when a User Account Control dialog box appears or if you press Ctrl+Alt+Del while Input Simulator is running
If you choose to open an application as an administrator while the Input Simulator is running, the cursor might freeze when the User Account Control (UAC) dialog box appears. To work around this, press Alt+Tab until the UAC dialog box receives focus, use the arrow keys or the Tab key to make your selection, and then press Enter or Spacebar to close the UAC dialog box. If your mouse freezes when you press Ctrl+Alt+Del, press Esc to exit to return to the desktop.

Promoted Mouse Events

MouseEventArgs.StylusDevice is null
Testing whether a mouse event was generated by a touch device will not work if you use code like the following because the StylusDevice property of the MouseEventArgs structure is set to null. internal static bool IsTouchPromotedMouseEvent(MouseEventArgs e) { return IsTouchPromotedStylusDevice(e.StylusDevice); } private static bool IsTouchPromotedStylusDevice(StylusDevice stylusDevice) { return (stylusDevice != null && stylusDevice.TabletDevice != null && stylusDevice.TabletDevice.Type == TabletDeviceType.Touch); }

Related Documents and Resources

All Surface documentation is available on the Surface Community Web site, including information about administering devices made for Surface. The Surface documentation is

regularly reviewed and updated, so please check the Microsoft Surface Community Web site periodically for new information. The following additional resources might also be useful: What Is Surface Surface Application Showcase Surface Administration Guide download Surface Administration Guide on TechNet Surface Community website Surface Administrator Forums Support Links Surface Team Blog Surface Developer Forums Surface Training Modules Surface Application Design Guidelines Technical Resources on the Surface Website