Microsoft Surface 2.0 SDK Microsoft Surface 2.0 Runtime

Release Notes

Microsoft Surface 2.0 SDK
Microsoft Surface 2.0 Runtime

Version: June, 2011

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.

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

Surface Installers

Requirements

End-User Requirements

Developer Requirements

What's New

Application Migration Tool

Application Registration

Attract Application

Configuration Editor

ElementMenu Control

Gestures

Hardware Capabilities

Reach Profile / HiDef Profile

The Cloth SDK Sample

HID-based Input

Manipulations and Inertia

Rich Input

Samples

Surface Controls

Surface System

Tags and Object Routing

Tools

Touch Support

User Controls

Visual Studio Integration

API Changes

Application Registration

Detecting Hardware Capabilities

Manipulations and Inertia

Tag APIs and Object Recognition

Tap and Hold Gestures

Surface Colors

Surface Stress

Version Numbers in Assemblies

Known Issues

APIs and Controls

Templating ElementMenu and the Library Controls

ElementMenu Control

LibraryContainer Control

Input Simulator Tool

Input Simulator Stops Working if Display Settings are Changed

Cursor freezes when a User Account Control dialog box appears or if you press Ctrl+Alt+Del while Input Simulator is running

Promoted Mouse Events

MouseEventArgs.StylusDevice is null

Introduction

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

Surface Installers

The following installers are available for the Surface 2.0 platform:

Hardware InstallerThe 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 InstallerThe 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 InstallerThe 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) / Windows 7.
Development Environment / Visual Studio 2010, Express or full edition.
Software Developer Kit (SDK) / 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).
Hardware / A computer that supports Windows 7 (with or without touch functionality), or a device made for Surface 2.0.
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 Surface1.0SP1, 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 ActiveX-based WebBrowser control in WPF) also receive Surface input.

You cannot use the Surface 2.0 SDK on Surface 1.0 hardware unitsbecause 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.DefaultInteractiveSurfacewas 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.InteractiveSurfacewere 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

TemplatingElementMenu 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 areChanged

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