Using UrhoSharp in Xamarin.Forms

UrhoSharp can be used to add 3D graphics to an application for advanced visualization

PDF for offline use:
Related Samples:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-03

What is UrhoSharp?

UrhoSharp is a powerful 3D engine for Xamarin and .NET developers. The introduction explains more about the UrhoSharp library, and these notes describe how to program scenes and actions.

UrhoSharp can be used to render graphics in Xamarin.Forms applications. This sample demonstrates how UrhoSharp could be used to construct an interactive 3D chart:

Adding the UrhoSharp Nuget packages

Before using UrhoSharp, developers need to add the UrhoSharp Nuget package to their solution. This guide assumes a Xamarin.Forms project with an iOS, Android, and PCL project. All of the code will be written in the PCL project; but the UrhoSharp Nuget must be added to the iOS and Android projects too.

The UrhoSharp.Forms Nuget package contains all of the objects needed to create UrhoSharp objects. The UrhoSharp.Forms nuget package includes the UrhoSurface class, which is used to host UrhoSharp in Xamarin.Forms. To begin, right-click on the PCL’s Packages folder and select Add Packages.... Enter the search term UrhoSharp.Forms, select UrhoSharp for Xamarin.Forms, then click Add Package.

The UrhoSharp.Forms NuGet package will be added to the project:

Repeat the above steps for platform-specific projects (such as iOS and Android).

Walkthrough: Adding UrhoSharp to a Xamarin.Forms app

These steps describe the code in the Xamarin.Forms UrhoSharp sample:

  1. Creat a Xamarin Forms Page
  2. Add the UrhoSurface
  3. Build an Urho Application
  4. Add the Charts class to the UrhoSurface
  5. Interacting with UrhoSharp

Note that the sample uses C# 6 features, and may not compile on older versions of Visual Studio.

1. Create a Xamarin Forms Page

The code below shows a Xamarin.Forms page UrhoPage before any Urho-related code has been added:

public class UrhoPage : ContentPage
{
  Slider selectedBarSlider, rotationSlider;

  public UrhoPage()
  {
    // we'll add Urho later

    rotationSlider = new Slider(0, 500, 250);

    selectedBarSlider = new Slider(0, 5, 2.5);

    Title = " UrhoSharp + Xamarin.Forms";
    Content = new StackLayout {
      Padding = new Thickness (12, 12, 12, 40),
      VerticalOptions = LayoutOptions.FillAndExpand,
      Children = {
        rotationSlider,
        new Label { Text = "SELECTED VALUE:" },
        selectedBarSlider,
      }
    };
  }

2. Add the UrhoSurface

UrhoSharp can be hosted in a ContentPage like other Xamarin.Forms controls. The code snippet below shows a UrhoSurface added to the Xamarin.Forms page:

using Urho;
using Urho.Forms;
...
public class UrhoPage : ContentPage
{
  UrhoSurface urhoSurface;

  public UrhoPage()
  {
    urhoSurface = new UrhoSurface();
    urhoSurface.VerticalOptions = LayoutOptions.FillAndExpand;
...
    Content = new StackLayout {
    Padding = new Thickness (12, 12, 12, 40),
    VerticalOptions = LayoutOptions.FillAndExpand,
    Children = {
      urhoSurface,  // added
      new Label { Text = "ROTATION:" },
      rotationSlider,
      new Label { Text = "SELECTED VALUE:" },
      selectedBarSlider,
    }
  };

3. Build a Urho Application

Refer to the Charts class for the implementation of the Urho 3D graphics used in this sample. The basic code outline is shown below - note that the class implements Urho.Application which is different to the Xamarin.Forms.Application class that is implemented in App.cs.

using Urho;
using Urho.Actions;
using Urho.Gui;
using Urho.Shapes;

namespace FormsSample
{
    public class Charts : Urho.Application
    {
    public Charts (ApplicationOptions options = null) : base(options) { }
    protected override void Start ()
    {
      ...
    }
    protected override void OnUpdate(float timeStep)
    {
      ...
    }

The UrhoSharp documentation contains more information on how to build 3D scenes and actions.

4. Add the Charts class to the UrhoSurface

Use the UrhoSurface.Show<T> generic method to add the Urho application to the Xamarin.Forms page. The code snippet below shows the additional code required to create the Charts class:

public class UrhoPage : ContentPage
{
  Charts urhoApp;
  ...
  protected override async void OnAppearing ()
  {
    urhoApp = await urhoSurface.Show<Charts> (new ApplicationOptions(assetsFolder: null)
      { Orientation = ApplicationOptions.OrientationType.Portrait });
  }

Note: the Show<T> method is asynchronous and should be called with the await keyword.

5. Interacting with UrhoSharp

The example allows the chart bars to be selected and modified. The Charts class exposes the Bars and SelectedBar to enable this interaction.

Each "bar" has a selection event handler added after the Charts class has been rendered, by iterating over the exposed Bars collection:

protected override async void OnAppearing ()
{
  urhoApp = await urhoSurface.Show<Charts>(new ApplicationOptions(assetsFolder: null) { Orientation = ApplicationOptions.OrientationType.Portrait });
  foreach (var bar in urhoApp.Bars)
  {
    bar.Selected += OnBarSelection;
  }
}

The event handler uses the value of the Xamarin.Forms Slider control to adjust the height of the given bar:

private void OnBarSelection(Bar bar)
{
  //reset value
  selectedBarSlider.ValueChanged -= OnValuesSliderValueChanged;
  selectedBarSlider.Value = bar.Value;
  selectedBarSlider.ValueChanged += OnValuesSliderValueChanged;
}

void OnValuesSliderValueChanged(object sender, ValueChangedEventArgs e)
{  // C# 6
  if (urhoApp?.SelectedBar != null)
  {
    urhoApp.SelectedBar.Value = (float)e.NewValue;
  }
}

Finally, wire up the two Slider controls so that when their value changes the UrhoSharp canvas is affected. The first slider rotates the 3D chart image and the second slider adjusts the height of the selected bar.

rotationSlider = new Slider(0, 500, 250);
rotationSlider.ValueChanged += (s, e) => urhoApp?.Rotate((float)(e.NewValue - e.OldValue));

selectedBarSlider = new Slider(0, 5, 2.5);
selectedBarSlider.ValueChanged += OnValuesSliderValueChanged;

The animations at the top of the page show the sample running.

Summary

This page shows how UrhoSharp can be used to add 3D data visualization to Xamarin.Forms. Read the UrhoSharp documentation for more information on how to build Urho scenes that can be included in Xamarin.Forms apps using the method shown above.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.