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)
Windows 7.
Development Environment
Visual Studio 2010, Express or full edition.
Surface 2.0.
Software Developer Kit (SDK)
.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.
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
