Make your Windows 8 Video App use the PlayTo feature

If you are making a video app for Windows 8 Metro there are 6 lines of code you simply MUST add. The feature you get for such a little effort will make your jaw drop (well at least mine did). Here’s what the experience is like:

Imagine you are watching a video on your Windows 8 PC or Tablet:

image

But watching TV on the PC kinda sucks. So the first thing you do is to swipe from the right to bring out the Windows 8 Charms menu:

2

You hit the “Devices” charm, and voila, all your media clients show up under “Play To”. Now you just pick your PlayTo enabled TV/Device, or even any Windows Media Player running on Win7 or 8:

image

And the next thing you know this happens:

4

Voila! The Christmas cheer is now playing on the TV for everyone to enjoy. And I can continue to use the playback controls on my PC to play, pause, fast forward, rewind etc.

How to accomplish this is described in depth in the “Play To and Media Sharing for Metro Style Apps” white paper. But it’s so simple to set up, that I’ll quickly tell you how.

First thing you do is that to add a MediaElement to your Win8 Metro app page (if you made a video app you already did this):

    <MediaElement x:Name="videoplayer" Source="http://www.contoso.com/clip.mp4" AutoPlay="true" />
When you assign a video source to the media element, simply hook up an event listener to when the user picks a play to device:

// Step 1: Obtain PlayToManager object for app’s current view.
PlayToManager ptm = Windows.Media.PlayTo.PlayToManager.GetForCurrentView();
// Step 2: Register for the SourceRequested event (user selects Devices button).
ptm.SourceRequested += (PlayToManager sender, PlayToSourceRequestedEventArgs e) => {
    request = e.SourceRequest;
    // Step 3: Specify the media to be streamed.
    PlayToSourceDeferral deferral = request.GetDeferral();
    request.SetSource(videoplayer.PlayToSource);
    deferral.Complete();
}
And that’s ALL you need to do! No need to build any UI around this. No need to figure out how to stream various types of video streams (as far as I can tell both local files and remote video streams works with this). And yes this can even be extended to work with images and music as well.

So those 6 lines of code should ALWAYS be in your video player app, and you’ll make a lot of people very happy (Netflix and Hulu are you reading this?).

In the Windows 8 Developer Preview there is a limitation on what devices this works on for now though. From the white paper:

Only the below list of Play To receivers are supported in the Developer Preview. For scenario testing/validation from apps the easiest solution is to use Windows Media Player on another PC on the same Private Network. Other available devices are:
·    WD Live Hub (firmware version: 2.07.17)
·    Onkyo AV Receivers (Windows 7 Certified models)
·    Windows Media Player (on Windows 7 and the Windows Developer Preview)
·    Metro style apps with Play To Receiver functionality

Since Windows Media Player supports this, it’s pretty easy to test for yourself with a second Win7 or 8 PC. Here’s how to configure Windows Media Player as a Play To receiver:

·    Open Windows Media Player and navigate to the Stream menu
·    Select Allow remote control of my Player

image

If both PC’s are on the same private network and have sharing enabled, that’s really all you need to do. Windows 8 will automatically pick it up and add it to the list of Play To devices.

If you have problems making this work, I suggest you first read the white paper, since this also covers known issues and how to correctly configure your devices on your network.

Why Silverlight 5’s 3D is (almost) useless

So Silverlight 5 finally hit the web this week, and there’s a lot of cool new features – some of which I’m very excited about, but probably the biggest feature ever added - the 3D XNA API that allows you to render directly to the graphics card using the new DrawingSurface API - I’m not so excited about any more. Why? Because between the RC and RTM release this feature has been heavily crippled. Here’s an excerpt from the recent blogpost describing the change:

[…] you may experience security errors with Silverlight 5 RTM when you want to use the wonderful new 3D feature. In fact, some graphics drivers may allow malicious code to execute. That may lead to an unwanted hard reset or a blue screen.

Starting with the beta version, to protect users for this kind of trouble, we initiate a first scenario where all Windows XP Display Driver Model (XPDM) drivers on Windows XP, Windows Vista, and Windows 7 will be blocked by default. Permission will be granted automatically in elevated trust scenarios and Windows Display Driver Model (WDDM) drivers will not require user consent at run-time.

But as always, features, including security features, continue to be refined and added during post-beta development.

And for the RTM version, there were a number of approaches considered to further improve security and stability, but the solution to block 3D in partial trust by default was the best option for this release. Permission is still granted automatically in elevated trust scenarios.

So already during beta and RC, we had a security limitation that certain old type of display drivers would disable this mode, unless you ran in full trust. Considering the uptake on WDDM, I didn’t consider this limitation a big problem. After all technology moves forward, and old tech sometimes needs to be left behind. After all one of the reasons for moving to the WDDM model was to stabilize the system.

Post RC this limitation was increased to be across all systems and display drivers. I was lucky enough to get a heads up about this a little over two months ago, but I feel truly sorry for the people who had been betting on this feature and are ready to release their 3D apps now that RTM has hit. The communication of this limitation shouldn’t have stayed within a small group of people under NDA, but should have been communicated out to the community. It probably didn’t happen because it could probably have fueled the “Silverlight is dead” fire (and rightfully so). I would have like to have seen a more open discussion of this, similar to what the Windows 8 team has on their “Building Windows 8” blog. In June the Silverlight Team had promised that the DoS issue that beta and RC had, would be mitigated and developers were counting on this feature.

So I’m not saying that security shouldn’t take precedence, but I would have like to see a more focused effort to either improve the experience – either by dedicating a lot of resources to weed out the security issues, delay the release, or at the very least make it easier for users to opt in. – perhaps communicating that this is a temporary limitation and will be resolved in a GDR update. Considering the late change, I get that the Silverlight team didn’t have much time to turn around and improve this experience. However, there’s already a feature like this for when you want to use the webcam that works much better. When I in Silverlight want to use the webcam, I ask the user for permission, and I’m met with the following dialog:

image

It’s pretty easy and it’s clear to the user what he/she needs to do. I wish we had gotten a similar dialog for enabling 3D. Instead, now in Silverlight, all you can do is detect that the 3D capability is blocked and try and describe to the user what to do. These are the steps you would have to guide them through:

  • Right click on your Silverlight plugin.
  • Click the “Silverlight” option.
  • Go to the permissions tab.
  • Find the domain that hosts the .xap file (which might not be obvious since it could be different than where the website is located).
  • When you find the entry (and this list could be quite long), you have to click “Allow” – no indication here what that really means for the casual PC user (how do you use a blocked display driver?!??).

image

Was this really the best experience we could have gotten? It’s actually easier to ask the user to install the app in full trust (which is an even unsafer mode), than the above experience. I’m sure Average Joe would not like this experience, have trouble finding this out, and probably even be scared to death to do anything he’s not used to doing (I know my parents wouldn’t ever get through this). So all you are going to see on your website is a plugin container that just sits there unused, and not getting to show how awesome this thing could really have been.

It’s such a shame, because this API can vastly improve rendering performance in many scenarios, and opens up an entirely new group of 3D based web based apps. And it would have worked across a wide range of browsers (more so than WebGL at this point).

The 3D capabilities are still great for out-of-browser apps and internal line-of-business apps where it’s a lot easier to deploy an app in full trust (especially with SL5’s new in-browser full trust feature). But are that really the type of apps where you expect to be using the 3D feature a lot?

Building an Augmented Reality XAML control

Augmented Reality on Windows Phone and Windows 8 Metro style apps

I’ve lately been playing a lot with augmented reality on my Windows Phone and my Windows 8 Tablet. Both of them feature an accelerometer, compass and gyro as well as a back facing camera. This makes it possible to overlay various XAML elements on top of the camera feed, and have them move with the camera as you rotate and orient the device. As an example of this, you can try the AR view in my GuidePost app for Windows Phone (and while you’re at it, make sure you throw some good reviews in there ;-). The app uses the exact approach described here.

To do augmented reality in XAML, I built a custom panel control that automatically handles the placement of all it’s child elements based on the device’s orientation. I used an attached property to define what ‘direction’ an element is supposed to be placed in. You already know this from Grid and Canvas, where for instance Grid.Row=”1” places it in the second row of the grid, or Canvas.Top=”100” places the element 100 pixels from the top of the canvas. In my case I use ARPanel.Direction to define a Point where the first value is the azimuth (ie up/down) and second value is the compass heading.

Note: Since you probably know the Grid panel very well, to help explain how this custom panel works, you’ll sometimes see a “How Grid uses this” section, to explain how the grid control would do something similar.

Here’s what the four cardinal directions and up and down would look like in such a custom panel that we’ll be building:

<ar:ARPanel>
    <TextBlock Text="North" ar:ARPanel.Direction="0,0" />
    <TextBlock Text="East"  ar:ARPanel.Direction="0,90" />
    <TextBlock Text="South" ar:ARPanel.Direction="0,180" />
    <TextBlock Text="West"  ar:ARPanel.Direction="0,270" />
    <TextBlock Text="Up"    ar:ARPanel.Direction="90,0" />
    <TextBlock Text="Down"  ar:ARPanel.Direction="-90,0" />
</ar:ARPanel>

Neat huh? This makes it VERY simple to spit out a bunch of different AR-type of apps. So how did I build this?

The custom panel

When building a custom panel, there’s really just 3 things you need to do:

  1. Inherit from Panel
  2. Override MeasureOverride
  3. Override ArrangeOverride

Or to put that in code:

public class ARPanel : Panel
{
    protected override Size MeasureOverride(Size availableSize)
    {
        //TODO
    }
    protected override Size ArrangeOverride(Size finalSize)
    {
        //TODO
    }
}

The two methods here have the following purposes:

MeasureOverride is called first, and it should go through all the child elements and tell them “Hey I got this much space available - how much of that do you need?”.

How Grid uses this: If a grid is 150x100 and has two rows and two columns, it would look at the row/column of the element then say “I got this much 75x50 space in this row/column - how much do you want”. If all the row/column sizes are auto, it would send the entire size of the grid itself to the child.

ArrangeOverride is called second. This goes through all the child elements and tells them “I heard you want this much space (as indicated by child.DesiredSize), but I can only give you this much, and this is the area where you get to place yourself”.

How Grid uses this: After going through the measure step, Grid would now determine what the size of each row and column needs to be based on the child desired elements (unless the cell sizes are fixed), and then calculate the rectangle for each cell distributed based on the row/column definitions. These rectangles are then used to place the child elements in the row/column they are set to be placed in.

Now first let’s implement MeasureOverride, since this is very simple in this scenario. Each child element can render itself anywhere around you in a 360 degree space, so we don’t need to limit the child elements to any size other than the size of the panel itself. So we’ll ask each child “Given all of my space, how much would you want to use?”. This is simply done by going through each child element and calling Measure on them with the full size available (after each measure call, you will notice that child.DesiredSize will now be assigned). We end the call by returning the size that the panel needs to it’s parent - in this case we want to use the entire space available to us:

protected override Size MeasureOverride(Size availableSize)
{
    foreach (var child in Children)
        child.Measure(availableSize);
    return availableSize;
}

MeasureOverride is called whenever the panel’s size is changing or anything else that would affect the size of the child elements. You can trigger this yourself by calling panel.InvalidateMeasure(). In our specific case we don’t ever need to call this, and the measure will only get invalidated when the panel’s size changes - for instance when page orientation changes, and luckily this is all done for us. (Grid would call InvalidateMeasure if the row/column definitions change)

Next up is ArrangeOverride. Now that we measured all the elements, we need to determine where to place them on the screen, and how much space we need to give each of them. We’ll basically go through each element and call Arrange(rect) on them, where the ‘rect’ is the rectangle it gets to render itself in. Ie. the top-left corner is where the area starts, and the width/height is the size it gets. It’s then up to the child to make use of that area. In our ARPanel case, the top/left corner would constantly change as the orientation of the device changes, but we’ll keep the width/height to the desired size of the element. So the method will look something like this:

protected override Size ArrangeOverride(Size finalSize)
{
    foreach(var child in Children)
    {
        double centerX = TODO;
double centerY = TODO;
double left = centerX - child.DesiredSize.Width * .5; double top = centerY - child.DesiredSize.Height * .5; Rect rect = new Rect(new Point(left, top), child.DesiredSize); child.Arrange(rect); } }

I subtract half the width/height of the size to center the element on top of ‘centerX’ and ‘centerY’, which we will still have to determine;

So this is basically our panel implementation. The tricky part is figuring out the “TODO” part of the above code based on the motion sensor. So basically, given a device orientation, what is the screen location of a direction?

Warning: I spent quite a lot of time on getting this part right. It’s a lot of vector math, and some of it I came to using pure trial and error :-). Therefore I might not even completely get all of it myself, but it works, and it works great. I’m pretty sure the math is right, but if I don’t go too much into detail in some of the math, just think of it as magic that works and use the code as is :-) For those of you who are used to XNA 3D Game programming, I’m sure this will all make sense to you though, since this is very similar to how you control a camera in a 3D environment.

The motion sensor

The Motion Sensor is what will be driving the placement of the child elements. Motion is a combination of Compass, Accelerometer and optionally Gyro. The Gyro is not required, but it makes the result A LOT better - especially when you rotate the device fast. Future certified Windows 8 tablets will require all 3 sensors, but for Windows Phone, only some of the newer Mango phones has a gyro, and I believe the Dell Venue Pro compass sensor doesn’t work. Future cheaper Windows Phone devices might not come with any sensors available, so beware that your app might not work on all devices, and you should check for the capability and notify the user if it’s missing.

On Windows Phone you can check whether the motion sensor is supported using ‘Microsoft.Devices.Sensors.Motion.IsSupported’. I didn’t find an equivalent property in Windows Runtime though. The following code starts reading from the sensor for both WinPhone and Windows Runtime:

#if WINDOWS_PHONE
    if (Microsoft.Devices.Sensors.Motion.IsSupported)
    {
        motion = new Microsoft.Devices.Sensors.Motion();
        motion.CurrentValueChanged += motion_CurrentValueChanged;
        motion.Start();
#elif WINRT
    motion = Windows.Devices.Sensors.OrientationSensor.GetDefault();
    if (motion != null)
    {
        motion.ReadingChanged += motion_CurrentValueChanged;
#endif
    }
    else
    {
        throw new InvalidOperationException("Motion sensor not supported on this device");
    }
#endif

When we get a new reading, all we have to do is tell the panel, that the current child placements are invalid. We don’t want to do too much work here, because the motion sensor can be triggering much more frequent than the layout cycle, so all we do here is flag the panel for arrange and clear any parameters that could be affected by the orientation change (like the attitude which I will get back to):

    private Matrix? _attitude;

    private void motion_CurrentValueChanged(object sender, EventArgs e)
    {
        _attitude = null;
 #if WINDOWS_PHONE
        Dispatcher.BeginInvoke(() => InvalidateArrange());
#elif WINRT
        Dispatcher.Invoke(Windows.UI.Core.CoreDispatcherPriority.Normal, 
                          (a, b) => InvalidateArrange(), this, null);
#endif
    }

Handling sensor and screen coordinate systems

The Motion sensor gives us a Matrix that defines the rotation of the device relative to up and north directions. The screen has a different coordinate system that is relative to the upper left corner of the screen. When the screen changes between landscape and portrait mode, this coordinate system changes relative to the motion sensors coordinate system, and it’s important to take this into account. Lastly we need to define a field of view for the screen. If you are overlaying elements on top of the camera, the field of view must match the field of view of the camera. Think of it as how ‘narrow’ the view is. A lens that is zoom in far has a small field of view, and only few elements will be visible on the screen, whereas a wide angle lens will have more child elements on the same screen. I found that on my phones a FOV of roughly 35 degrees seems appropriate. So to sum up we need 3 things: The orientation of the sensor, the orientation of the view (screen), and the parameters for the camera (the projection).

First the view, which is slightly different between phone and runtime (probably because the ‘natural’ orientation on a phone is portrait mode, whereas on a PC it’s landscape mode, so the sensors are mounted different).

    Matrix view;
if (orientation == LandscapeLeft) { view = Microsoft.Xna.Framework.Matrix.CreateLookAt( new Microsoft.Xna.Framework.Vector3(0, 0, 1), Vector3.Zero, #if WINDOWS_PHONE Vector3.Right); #elif WINRT Vector3.Up); #endif } else if (orientation == LandscapeRight) { view = Microsoft.Xna.Framework.Matrix.CreateLookAt( new Vector3(0, 0, 1), Vector3.Zero, #if WINDOWS_PHONE Vector3.Left); #elif WINRT Vector3.Down); #endif } else //portrait mode { view = Microsoft.Xna.Framework.Matrix.CreateLookAt( new Vector3(0, 0, 1), Vector3.Zero, #if WINDOWS_PHONE Vector3.Up); #elif WINRT Vector3.Left); #endif

Next we define a viewport based on this view. Note that this depends on the size of the screen, so on size changed we need to remember to reset this value.

private Microsoft.Xna.Framework.Graphics.Viewport? _viewport;
private Microsoft.Xna.Framework.Graphics.Viewport Viewport
{
    get
    {
        if (!_viewport.HasValue)
        {
            _viewport = new Microsoft.Xna.Framework.Graphics.Viewport(0, 0, (int)ActualWidth, (int)ActualHeight);
            _cameraProjection = null; //camera projection depends on viewport - force a reset
        }
        return _viewport.Value;
    }
}

And from this we can now define the projection of the camera / field of view.

private Matrix CameraProjection
{
    get
    {
        if (!_cameraProjection.HasValue)
        {
           _cameraProjection = Matrix.CreatePerspectiveFieldOfView(
MathHelper.ToRadians((float)FieldOfView), Viewport.AspectRatio, 1f, 12f); } return _cameraProjection.Value; } }

Now we need the attitude of the device based on the current sensor reading (this was the value we reset in reading changed event). We rotate this value so it matches the rotation of the XNA coordinate system as well.

    private Matrix Attitude
    {
        get
        {
            if (!_attitude.HasValue)
            {
                if (motion != null 
#if WINDOWS_PHONE
                    && motion.IsDataValid
#endif
                    )
                {
                    _attitude = Matrix.CreateRotationX(MathHelper.PiOver2) * CurrentReading;
                }
                else
                    return Matrix.Identity;
            }
            return _attitude.Value;
        }
    }
#if WINDOWS_PHONE
    private Matrix CurrentReading
#elif WINRT
    private SensorRotationMatrix CurrentReading
#endif
    {
        get
        {
            return
#if WINDOWS_PHONE
                motion.CurrentValue.Attitude.RotationMatrix;
#elif WINRT
                motion.GetCurrentReading().RotationMatrix;
#endif
        }
    }

Ok that’s a lot of funky stuff, but now we are pretty set to project from vectors to screen coordinates using this simple method:

Matrix world = Matrix.CreateWorld(Vector3.Zero, new Vector3(0, 0, -1), new Vector3(0, 1, 0));
// Projects the point from 3D space into screen coordinates.
private Vector3 Project(Vector3 vector)
{
    return Viewport.Project(vector, CameraProjection, view, world * Attitude);
}

Only thing is we have a direction ray and not a vector. A little extra method for converting to a vector is needed too:

private static Vector3 PolarToVector(double px, double py, double radius)
{
    var O = (py - 90) * PI_OVER_180; // / 180d * Math.PI;
    var W = (90 - px) * PI_OVER_180; // / 180d * Math.PI;
    var x = (float)((Math.Cos(O) * Math.Sin(W)) * radius);
    var y = (float)((Math.Cos(W)) * radius);
    var z = (float)((Math.Sin(O) * Math.Sin(W)) * radius);
    return new Vector3(x, y, z);
}

We don’t have any radius, but I found always using a value of ‘10’ (which is 10 units down the ray) works pretty well. So… we are now pretty set to implement the ArrangeOverride method.

Arranging the child elements

When arranging the children, we need to first check if it’s inside the screen view, and next where on the screen that is. I’m using the BoundingFrustum to do this. Think of the bounding frustum as the space the camera can see, and is a cone the expands out from the camera We can set this up using:

    BoundingFrustum viewFrustum = new BoundingFrustum(Attitude * view * CameraProjection);

If we now build a BoundingSphere around each element, we can use the .Contains method to see if that element is within the frustum. So we first grab the Point object from the element, and build a bounding sphere. If it is inside, all we have to do is call the Project method above to get the screen location, and lastly call Arrange on the element.

So our entire ArrangeOverride method ends up looking like this:

    protected override Size ArrangeOverride(Size finalSize)
    {
        if (ActualWidth > 0 && ActualHeight > 0 && motion != null
#if WINDOWS_PHONE
            && motion.IsDataValid
#endif
            )
        {
            BoundingFrustum viewFrustum = new BoundingFrustum(Attitude * view * CameraProjection);
            foreach (var child in Children)
            {
                object posObj = child.GetValue(DirectionProperty);
                if (posObj is Point && !double.IsNaN(((Point)posObj).X))
                {
                    Point p = (Point)posObj;
                    Vector3 direction = PolarToVector(p.X, p.Y, 10);
                    var size = child.DesiredSize;
                    //Create a bounding sphere around the element for hittesting against the current frustum
                    //This size is not entirely right... size we have is screen size but we use the world size. 
                    //*.008 seems to roughly fit as conversion factor for now
                    var box = new BoundingSphere(direction, (float)Math.Max(size.Width, size.Height) * .008f);
                    if (viewFrustum.Contains(box) != ContainmentType.Disjoint) //partially or fully inside camera frustum
                    {
                        Vector3 projected = Project(direction);
                        if (!float.IsNaN(projected.X) && !float.IsNaN(projected.Y))
                        {
                            //Arrange element centered on projected coordinate
                            double x = projected.X - size.Width * .5;
                            double y = projected.Y - size.Height * .5;
                            child.Arrange(new Rect(x, y, size.Width, size.Height));
                            continue;
                        }
                    }
                }
                //if we fall through to here, it's because the element is outside the view,
                //or placement can't be calculated
                child.Arrange(new Rect(0, 0, 0, 0));
            }
            return finalSize;
        }
        else
            return base.ArrangeOverride(finalSize);
    }

Congrats on making it this far - because we are actually pretty much done! All there’s left to do is put it all together, reset the used orientation parameters when needed and define the attached property for use on the child elements. And I already did all that for you!

You can download the control library together with a sample app here. There’s both a Windows Phone and Windows 8 Metro version included. You can use the code as you like, but if you improve on it, I would LOVE to hear about it. I didn’t include a camera background in the samples, so I’ll let that bit be up to you to add (you can use a VideoBrush as the background for that).

Note that for Windows Runtime, I have only tested this on the Samsung Build Tablet. I have no idea how this behaves on a device without a motion sensor (probably crashes, but let me know in the comments below). Also the Build tablets have a buggy fusion sensor firmware, which means that readings are fired VERY infrequent, making it almost useless for anything but rough testing.

Also note that the compass sensor can get very confused when you are inside - especially if the building has a metal frame construction. If directions seem off, try going outside away from anything that confuses the magnetic field.

WinRT vs. Silverlight - Part 8 - What other people are blogging

See intro blogpost here.

Over the last few months several other people have been writing blog posts covering the transition from WPF/Silverlight/WP7 to WinRT. Below are some of the ones I’ve stumbled upon.

Colin Eberhardt - XAMLFinance - A Cross-platform WPF, Silverlight and WP7 Application
An app that reuses code across 3 different XAML platforms and compiles for all of them. A great example that this can be accomplished. Also make sure to check out Colin’s blog for more WinRT goodness.

Jeffrey Richter - Core .NET Type usable from a Metro Styl Application
A list of the “standard” .NET types that are available in WinRT as well.

Andy’s blog - Physics Games: Multi-targeting Windows 8 and Windows Phone 7
Andy goes through building a physics-based game for both Windows 8 and Windows Phone 7. Also check out his Physics Helper library for WinRT.

Tim Greenfield - “WinRT Genome Project”
Visual comparison of how much overlay Silverlight 5 and WinRT has.

Tim Greenfield - Silverlight 5 vs. WinRT comparison
A follow-up to the link above with a comparison of namespaces, members, types and differences between SL5 and WinRT. This is an amazing list if you want to get into the details when reusing code between the two frameworks.

Pontus Wittenmarks’s - 10 tips about porting Silverlight apps to WinRT/Metro style apps (Part 1)
A quick list of of tips when porting from Silverlight to WinRT.

Petzold Book Blog - Windows 8 Dependency Property Strangeness
Talks about some of the issues with Dependency Properties in Windows 8. I already briefly touched on this, but this goes a lot more in-depth.

If I find more, I’ll add them here, or feel free to mention any other good resources in the comments below.

Correctly displaying your current location

With GPS receivers integrated in phones, tablets and PCs, a lot of apps are being built that displays your current location. Usually the GPS API’s that these devices come with provides you with two values: Longitude and Latitude in decimal degrees, and often an estimated accuracy in meters. Most apps just display these values as is, without considering formatting or number of significant digits. This blog post attempts to show how this could be done. I’ll use C# for this, but it should apply to any device, language and API out there.

Formatting

Some people think of longitude as the “X” in an ordinary flat X,Y the coordinate system and latitude as Y/Up/North. It’s technically not correct because this is not a flat coordinate system, but a ‘polar’ coordinate system - I do however understand this simplification and I think of it the same way internally when working with code that deals with any type of coordinate system. However, how things work internally and how they are displayed are two very different things. An example of this are date objects: They are usually stored and handled as a ‘tick’ number, but we never display it like that. Geographical coordinates are the same way. They have one way they are stored in memory, and a completely different way to be displayed.

First of all lets get the order out of the way: If you still think of longitude as the ‘x’ you probably want to display this value first. However it’s commonly agreed upon that latitude is displayed before longitude.

Next are negative coordinates. Instead of showing a latitude/longitude as for instance -117,34 you would write 117°W 34°N. So we prefix the coordinate with N/S and E/W depending on weather the coordinate is positive or negative. So in C# this could look like this:

char ns = lat < 0 ? 'S' : 'N'; //Southern or Northern hemisphere?
char ew = lon < 0 ? 'W' : 'E'; //Eastern or Western hemisphere?
string formatted = string.Format("{0}°{1} , {2}°{3}", Math.Abs(lat), ns, Math.Abs(lon), ew);

Now this is still decimal degrees. A more ‘proper’ format would be to use the degrees, minutes, seconds (DMS) format . Some people do prefer decimal degrees though, so you might want to make this a configurable option. But if you expect people to be using this coordinate to plot a position on a map, you are better off using DMS, since this is the format maps uses along its edge - and it also looks prettier. Degrees are denoted with a °, minutes with a single quote ' and seconds with a double quote ". For example 117°W 23' 12.34”

To make this conversion you will first show the integer part of the degrees. Take the remainder multiply by 60, and you’ll get the minutes. Lastly take the remainder of that and do the same, and you got the seconds (and you can display the seconds with decimals, but see the part on ‘accuracy’ next).  Below is what that will look like in C#:

char ns = lat < 0 ? 'S' : 'N'; //Southern or Northern hemisphere?
char ew = lon < 0 ? 'W' : 'E'; //Eastern or Western hemisphere?
//Make positive
lon = Math.Abs(lon);
lat = Math.Abs(lat);
//Grab the part in front of the decimal
var majorLong = Math.Floor(lon);
var majorLat = Math.Floor(lat);
//the value after the decimal in minutes (*60)
var minorLong = (lon - majorLong) * 60;
var minorLat = (lat - majorLat) * 60;
//Minutes:
var minutesLong = Math.Floor(minorLong);
var minutesLat = Math.Floor(minorLat);
//Seconds:
var secondsLong = (minorLong - minutesLong) * 60;
var secondsLat = (minorLat - minutesLat) * 60;
string formatted = string.Format("{0}{1}°{2}'{3}\" {4}{5}°{6}'{7}\"", ns, majorLat, minutesLat, secondsLat, ew, majorLong, minutesLong, secondsLong);

Accuracy

Often I see a location displayed as for example -117.342817243 , 34.212381313. When I see this many digits I instantly think ‘oooooh that’s a very accurate location’. But this is very misleading. In college, several of our professors would fail our reports if the end result displayed more digits than the accuracy of the input data. The same thing applies here. If your GPS receivers accuracy is 1000m, how many digits should you display, and how many meters is one second?

First a little about the size and shape of earth: While earth is not a perfect sphere, it’s fairly close to an ellipsoid (this is still an approximation though). It’s widest at equator, and smallest (flattened) between the north and south pole. So in ellipsoid-speak the parameters are:

Semi-major axis: 6,378,137m
Semi-minor axis: 6,356,752.3142m
Mean radius (mR): 6,367,449m

So back to the question: How many meters is one second? This is pretty easy to determine for latitude, but unfortunately this is not a straightforward conversion for longitude, since this changes with the latitude. Let’s first start with the simpler latitude:
First we need the circumference of Earth along a meridian (a line that goes north/south) and Equator:

Circumference at Equator: 2 * Pi * 6,378,137 = 40,075,016 m
Circumference of a meridian : 2 * Pi *  6,356,752 = 39,940,652 m

For simplicity let's stick with a rough average of 40mio meters, since this is not going to really matter for the end result.
From that we get:

Horizontal length of one degree at Equator or along a meridian:
     40,000,000 / 360 = 111,111m
Horizontal length of one second at Equator or along a meridian:
    111111.111 / 60 minutes / 60 seconds = 31m

So from that we get that we should never display any decimals on seconds unless our accuracy is better than 31 meters. And we shouldn’t display more than one decimal unless the accuracy is 3m or better (which never happens with standard GPS equipment). Similarly if we are using decimal degrees instead of DMS for display, how much does the n'th digit matter at Equator or along a meridian?

5 digits: 0.000,01 * 40000000 = 400m 
6 digits: 0.000,001 * 40000000 = 40m
7 digits: 0.000,000,1 * 40000000 = 4m

So in this case we will only show 7 digits if accuracy is better than 40m, and probably never more than 7 digits.

Latitude always goes along a meridian, so the number of significant digits doesn't ever change with your location. But the length of one degree at a longitude changes with the latitude you're at.
The radius of a longitude at a given latitude is: cos(latitude)*mR*2*PI.
At 34 north or south that would be: 33,168,021m. So here the number is roughly 3m instead of 4m, meaning you are more likely to show more digits on the longitude portion for the coordinate, the further north you go. In general practice however, this is not going to matter too much, since it only gets better. so to keep it simple we’ll just stick with the same conversion at all latitudes.

Bringing it all together

So let’s bring all this together into a C# ValueConverter you can use for binding against a GeoCoordinate object returned by the GeoCoordinateWatcher in .NET and Windows Phone. A converter parameter is used for choosing whether you want DMS or decimal degrees as output.

using System;
using System.Device.Location;
using System.Globalization;
using System.Windows.Data;

namespace CoordinateDisplay
{
    /// <summary>
    /// Converts a GeoCoordinate to Degrees-Minutes-Seconds
    /// </summary>
    public class CoordinateConverter : IValueConverter
    {
        private const double MeanEarthRadius = 6367449; //meters
        private const double MeanEarthCircumference = 2 * Math.PI * MeanEarthRadius; //meters
        public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
        {
            if (value is GeoCoordinate)
            {
                var coord = value as GeoCoordinate;
                if(coord.IsUnknown) return "Unknown";

                double lat = coord.Latitude;
                double lon = coord.Longitude;
                if ((parameter is string) &&
                    string.Compare("decimal", parameter as string, StringComparison.OrdinalIgnoreCase) == 0)
                //show as decimal degrees
                {
                    var decimalsLat = 7;
                    var decimalsLon = 7;
                    int val = 4;
                    if (coord.HorizontalAccuracy > val * 100) decimalsLat = 5;
                    else if (coord.HorizontalAccuracy > val * 10) decimalsLat = 6;
                    val = (int)Math.Floor(Math.Cos(lat / 180 * Math.PI) * MeanEarthCircumference / 10000000d);
                    if (coord.HorizontalAccuracy > val * 100) decimalsLon = 5;
                    else if (coord.HorizontalAccuracy > val * 10) decimalsLon = 6;
                    return string.Format("{0}°,{1}°", Math.Round(lat, decimalsLat), Math.Round(lon, decimalsLon));
                }
                else //Show as degrees/minutes/seconds
                {
                    char ns = lat < 0 ? 'S' : 'N'; //Southern or Northern hemisphere?
                    char ew = lon < 0 ? 'W' : 'E'; //Eastern or Western hemisphere?
                    //Make positive
                    lon = Math.Abs(lon);
                    lat = Math.Abs(lat);
                    //Grab the part in front of the decimal
                    var majorLong = Math.Floor(lon);
                    var majorLat = Math.Floor(lat);
                    //the value after the decimal in minutes (*60)
                    var minorLong = (lon - majorLong) * 60;
                    var minorLat = (lat - majorLat) * 60;
                    //Seconds:
                    var minutesLong = Math.Floor(minorLong);
                    var minutesLat = Math.Floor(minorLat);

                    //one digit accuracy on one second equals ~3m or better
                    //this changes with the latitude, but this is good enough for now
                    int decimals = 1;
                    if (coord.HorizontalAccuracy > 30)
                        decimals = 0; //With this accuracy we don't need to show sub-second accuracy
                    //Seconds:
                    var secondsLong = Math.Round((minorLong - minutesLong) * 60, decimals);
                    var secondsLat = Math.Round((minorLat - minutesLat) * 60, decimals);
                    return string.Format("{0}{1}°{2}'{3}\" {4}{5}°{6}'{7}\"",
                        ns, majorLat, minutesLat, secondsLat,
                        ew, majorLong, minutesLong, secondsLong);
                }
            }
            return value;
        }

        public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
}

Here’s an example of using that in XAML where the datacontext is the GeoCoordinate:

<Grid>
    <Grid.Resources>
        <local:CoordinateConverter x:Name="dmsConverter" />
    </Grid.Resources>
    <StackPanel>
        <TextBlock Text="Degrees minutes seconds:" />
        <TextBlock Text="{Binding Converter={StaticResource dmsConverter}}" />
        <TextBlock Text="Decimal degrees:" />
        <TextBlock Text="{Binding Converter={StaticResource dmsConverter}, ConverterParameter=decimal}" />
        <TextBlock Text="{Binding Path=HorizontalAccuracy, StringFormat=Accuracy: \{0:0\}m}" />
    </StackPanel>
</Grid>

And what this can look like on a Windows Phone with different accuracies (notice the different number of digits):

imageimage

You can download this sample app here.

WinRT vs. Silverlight - Part 7 - Making WebRequests

See intro blogpost here.

In Silverlight and WPF you are probably used to using WebClient to perform downloads. This is a simple class for doing download/upload string or retrieving a response stream from the server. However, in Windows Runtime this client doesn’t exists. Instead we have new a simple “HttpClient” to do much of what WebClient can. However it works very differently by using the new Task framework, and the more you dive into porting code to WinRT, you will see this a lot, and it will make your life porting code cumbersome. On the upside, the Tasks framework is awesome and it’ll often simplify you code a great deal! I talked a bit about this in my previous post, so please read that first, before you continue here, since this will be building on top of that.

Let’s say we have a method in WPF and Silverlight that uses WebClient to downloada and create an image. Since this is working asynchronously, we would have to either use event handlers or action delegates to return the result and/or the error. The method could look something like this:

public void GetContent(Uri uri, Action<string> complete, Action<Exception> error)
{
    WebClient client = new WebClient();
    client.DownloadStringCompleted += (sender, e) =>
    {
        if (e.Error != null)
            error(e.Error);
        else {
            complete(e.Result);
        }
    };
    client.DownloadStringAsync(uri);
}

 

Here’s how a method like that could look in WinRT:

public async Task<string> GetContentI(Uri uri)
{
   System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
   var result = await client.GetAsync(uri);
   return result.Content.ReadAsString();
}

Simple right? Well it' gets even simpler when we have to start consuming that method.

From SL and WPF you would consume the method something like this:

GetContent(uri, (text) => {
          TextBlock tb = new TextBlock() { Source = text };
          LayoutRoot.Children.Add(tb);
      },
      (error) => { /*TODO: handle error*/ }
);

And the same using the Task framework:

try {
   TextBlock tb = new TextBlock() { Source = await GetContent(uri) };
   LayoutRoot.Children.Add(tb);
catch { /*TODO: handle error */ }

You tell me what’s more elegant and readable? Smile

My point here is that Tasks are awesome, so rather than trying to reuse your existing code in WinRT, consider rewriting your existing code to use Tasks and it will work much smoother.

There’s lets create a method for downloading a string over the network that works the same way across the board. (I’ll assume you are using the Async Task CTP for Silverlight or WPF for this).

public async Task<string> GetContent(Uri uri)
{
#if NETFX_CORE
    System.Net.Http.HttpClient client = new System.Net.Http.HttpClient();
    var reqResult = await client.GetAsync(uri);
    return reqResult.Content.ReadAsString();
#else
    WebClient client = new WebClient();
    TaskCompletionSource<string> tcs = new TaskCompletionSource<string>();
    client.DownloadStringCompleted += (sender, e) =>
    {
        if (e.Error != null)
            tcs.TrySetException(e.Error);
        else
            tcs.TrySetResult(e.Result);
    };
    client.DownloadStringAsync(uri);
    return await tcs.Task;
#endif
}

Note you could also use the new .NET method “WebClient.DownloadStringTaskAsync” which would simplify the above quite a lot. I used the event based approach to demonstrate how you would handle the cases where you don’t already have a task implementation available.

WinRT vs. Silverlight - Part 6 - Using Tasks

See intro blogpost here.

When you start working with WinRT, you start seeing classes missing or changed. A lot of methods are now only asynchronous, like making a web request, opening, reading and writing files etc. They all now on the Task framework, and they do this to ensure you application is always responsive. However without this framework, it would be a pain to code against an API that’s inherently asynchronous all the way through. But with it, it makes it really easy to write code against it.

As an example here’s how you normally write async operations in WPF and Silverlight:

var myObject = new MyClass();
myObject.Completed += (sender,e) => { 
   //Completed event handler 
if(e.Error == null) { statusText.Text = "My Operation has completed: " + e.Result;
} }; myObject.StartAsync(); //Starts process and fires "Completed" event when done

So we first hook up to the event handler, then call start. When you look at the code, the lines are not executed in the order they are written. The completed delegate executes after the operation completes after Start() has been run (even explaining it makes it sound confusing). Also you cannot throw exceptions from an asynchronous running process, because there will be no way to catch it, so you’ll have to parse an exception object back as part of your result and check it.

This pattern makes it hard to read and understand the code, since it’s not immediately obvious what code runs when. Especially when the code gets more complex and/or your eventhandlers are declared elsewhere. When we then nest events, it gets very convoluted quickly:

var myObject = new MyClass();
myObject.Completed += (sender,e) => { 
   if(e.Error == null) {
       //Perform next operation
       var myObject2 = new MyClass();
       myObject2.Completed += (sender2,e2) => { 
           if(e2.Error == null) {
              //Completed event handler
              statusText.Text = "My Operation has completed: " + e2.Result;
} }; myObject2.StartAsync(); } }; myObject.StartAsync();

With the Task framework this becomes very simple and straightforward to write and more importantly read:

var myObject = new MyClass();
try {
     string result = await myObject.StartAsync();
     var myObject2 = new MyClass();
     string result2 = await myObject2.StartAsync();
     statusText.Text = "My Operation has completed: " + result2;
} catch { }

Notice that we don’t bother with checking an error object. We simply use try/catch instead, and the task returns the result up front. If it wasn’t for the little “await” keyword, it looks like this is just good ol’ synchronous programming! This is pure awesomeness!

If you are planning on porting a large application from Silverlight or WPF and it uses a lot of event-based asynchronous programming, you are probably in for some work. Not to say that your application can’t use events, but a lot of the WinRT API’s don’t have eventhandlers any more, so if you insist on keeping it this way, you would have to wrap all the built in tasks into some event-based classes. I would probably rather focus on moving forward and getting this cleaned up. And since the Task framework is already available in .NET 4 and there’s a CTP for Silverlight (and included in upcoming v5!) and WinPhone, you could port your original code to start taking advantage of this, making your code reuse easier and cleaner moving forward.

So how would you go about wrapping an event-based class into a task based method? Well let’s continue using the MyClass example above, and wrap it in a task. Here’s how that would look:

public Task<string> StartAsync()
{
    var tcs = new TaskCompletionSource<string>();
    var obj = new MyClass();
    obj.Completed += (sender,e) => {
        if (e.Error != null)
              tcs.TrySetException(e.Error);
        else
              tcs.TrySetResult(e.Result);
    };
    obj.StartAsync();
    return tcs.Task;
}

Basically we return Task of string, instead of just a string. We use the TaskCompletionSource of string to handle error and result messaging back to the task.

So when should you make a method an asynchronous task? The rule of thumb is: If it takes more than 50ms to execute, it should be asynchronous! This helps a lot towards preventing the UI from becoming choppy and/or unresponsive.

WinRT vs. Silverlight - Part 5 - Defining default style template

See intro blogpost here.

Here's something that's actually NOT different in Silverlight (but it's different from WPF as it has always been).
You declare your style using DefaultStyleKey. This means the code looks like this for Silverlight, WPF and Windows Runtime:

public class MyControl : Control
{
    public MyControl()
    {
#if SILVERLIGHT || NETFX_CORE
        this.DefaultStyleKey = typeof(MyControl);
#endif
    }
    static MyControl() {
#if !SILVERLIGHT && !NETFX_CORE
        DefaultStyleKeyProperty.OverrideMetadata(
            typeof(HoverControl),
            new FrameworkPropertyMetadata(
            typeof(HoverControl))); 
#endif
    }
}

Here is what IS different though: You need to set the build action of \Themes\Generic.xaml to "Content". It won't work without it.
Also note that when you add Generic.xaml to your project, it will also get added to App.Xaml. I assume this is a bug in the current release, but you will have to go and delete this entry, or it won't work.

WinRT vs. Silverlight - Part 4 - Dispatcher

See intro blogpost here.

In Silverlight and WPF you will often use the Dispatcher to return from a background thread to jump to the UI Thread. This is required when you need to update your UI, because you’re not allowed to touch the UI from anything but the UI Thread. The Dispatcher method has changed slightly in WinRT. It’s also now of type “CoreDispatcher”, instead of just “Dispatcher”.

#if !NETFX_CORE
  Dispatcher.BeginInvoke(
#else
  Dispatcher.Invoke(CoreDispatcherPriority.Normal, 
#endif
           (s, a) => { ... }
#if NETFX_CORE
      , this, null);
#endif
   );

WinRT vs. Silverlight - Part 3 - Dependency Properties

See intro blogpost here.

UPDATE Feb. 29, 2012: As hinted at below that this would happen, this blogpost on dependency properties is now outdated. Since the Consumer Preview of Windows 8 released, dependency properties now work exactly like they do in Silverlight and WPF.

---

Declaration of dependency properties has changed in the WinRT. This is a temporary change and will go away when WinRT hits beta, but still good to know if you start prototyping on WinRT today. If you are a control developer this is probably one of the things you would have to change in the most places.

Here’s what the API looks like for Silverlight and WPF for registering a Dependency Property or an Attached Property:

public static DependencyProperty Register(
      string name, 
      Type propertyType, 
      Type ownerType,
      PropertyMetadata typeMetadata);
public static DependencyProperty RegisterAttached(
      string name, 
      Type propertyType,
      Type ownerType, 
      PropertyMetadata defaultMetadata);

And here’s what this currently looks like in WinRT CTP :

public static DependencyProperty Register(
      string name, 
      string propertyTypeName, 
      string ownerTypeName,
      PropertyMetadata typeMetadata);
public static DependencyProperty RegisterAttached(
      string name, 
      string propertyTypeName,
      string ownerTypeName, 
      PropertyMetadata defaultMetadata);

Notice how the PropertyType and PropertyOwnerType is now strings instead of types!

This means you would have to write your code like this to make it cross-compile:

        public double MyDoubleProperty
        {
            get { return (double)GetValue(MyDoublePropertyProperty); }
            set { SetValue(MyDoublePropertyProperty, value); }
        }

        public static readonly DependencyProperty MyDoublePropertyProperty =
            DependencyProperty.Register("MyDoubleProperty", 
#if NETFX_CORE
             "Double", "MyNamespace.MyControl", 
#else
                typeof(double), typeof(MyNamespace.MyControl), 
#endif
                 new PropertyMetadata(0d));

Also note that you don’t use the full type name for the system types. Ie. here you use “Double” and not “double” or “System.Double”.

You could create a few static methods to replace the Register/RegisterAttached methods that will make your code cross-platform, and switch it out just there when this changes. Here’s one example how this could be accomplished (the ‘ToRTString’ method isn’t fully tested though…):

    public static DependencyProperty RegisterAttached(string name, Type propertyType, Type ownerType, PropertyMetadata metadata)
    {
        return DependencyProperty.RegisterAttached(name, 
#if NETFX_CORE
            propertyType.ToRTString(), ownerType.ToRTString()
#else
            propertyType, ownerType
#endif
            , metadata);
    }
    public static DependencyProperty Register(string name, Type propertyType, Type ownerType, PropertyMetadata metadata)
    {
        return DependencyProperty.Register(name,
#if NETFX_CORE
            propertyType.ToRTString(), ownerType.ToRTString()
#else
            propertyType, ownerType
#endif
            , metadata);
    }
#if NETFX_CORE
    private static string ToRTString(this Type type)
    {
        string name = type.FullName;
        if(name.StartsWith("System."))
            return name.Substring(7);
        else
            return name;
    }
#endif