Humans live in a three-dimensional world, which we navigate from the time we’re infants. We might, therefore, assume that 3D graphics programming would be an intuitively natural fit to our lifetime of experience; after all, we simply need to translate familiar concepts (left and right, up and down, forward and back) into an X-Y-Z coordinate system.

For most people, however, 3D graphics is quite daunting. It’s hard to get a mental feel for 3D objects and how they move through space, and the mathematics involved can be truly hairy. It’s very common for beginning 3D graphics developers to programmatically define a camera, light source, and a 3D object, and then see nothing at all on the screen.

Imagine if you could then fiddle with the code a bit, perhaps change that positive Z coordinate to a negative, for instance, and immediately see the new result.

This is what the combination of UrhoSharp and Xamarin Workbooks now offers. 3D graphics programming has become more accessible to developers, as well as more enticing, by becoming more interactive.

UrhoSharp is Xamarin’s C# wrapper for the open-source Urho3D cross-platform game engine. This is a powerful, industrial-strength 3D graphics API whose major deficiency is that it has so many features it can seem overwhelming to a 3D newcomer (and to developers who already have some 3D coding experience!).

Xamarin Workbooks are documents that combine text and code. Workbooks allow you to edit and execute code in tiny pieces and get immediate feedback. To get started, download the Workbooks application from the Xamarin Workbooks page, and then begin exploring the almost 100 Workbooks that already exist for a variety of platforms.

Getting Started

If you know some UrhoSharp, it might not seem like the optimal platform for Workbooks. Normally, you create a UrhoSharp application by deriving a class from Application, overriding several methods, and then calling a method named Run. This Run method is blocking; it doesn’t return until the application has completed. Within a Workbook, this application architecture is not conducive to an interactive experience.

For that reason, a new UrhoSharp class has been created specifically for Workbooks. This class is called SimpleApplication. You can simply call the static method SimpleApplication.Show with an optional ApplicationOptions argument within the Workbook, and you’re ready to go.

There are currently eight UrhoSharp Workbooks, with more in the works. Four of these eight are demonstrations of UrhoSharp features, while four others take a more tutorial approach suitable for aspiring 3D graphics programmers. You can run these Workbooks on a PC or Mac directly from the Workbooks page, or you can download the whole Workbooks GitHub repository. The UrhoSharp Workbooks are in the graphics/urhosharp directory.

One of the crucial aspects of 3D graphics programming is defining solid objects in 3D space. UrhoSharp provides several ways to do this. The most professional approach is to use specialized modeling software. UrhoSharp supports numerous model formats. The Animated Model Workbook is the shortest of the Urho Workbooks because it does little more than load in a model of a 3D mutant and animate it:

It’s also possible to create 3D shapes algorithmically by defining or deriving all the 3D vertices right in the Workbook. This approach is demonstrated in two Workbooks: Working with Urho Custom Geometries and Building Polyhedra with UrhoSharp.

The simplest approach, however, can be found in the Urho.Shapes namespace, which contains seven classes that let you make common geometric objects: Box, Cone, Cylinder, Plane, Pyramid, Sphere, and Torus. This is certainly the fastest way to get up and running with an UrhoSharp Workbook.

Creating The Workbook

To begin creating your own UrhoSharp Workbooks, you’ll want to download the Workbooks GitHub repository. In the directories for the existing UrhoSharp Workbooks, you’ll see three library files: one for the PC (mono-urho.dll), another for the Mac (libmono-urho.dylib), and the third that’s common to both platforms (Urho.dll). You’ll need these files in the same directory as your new Workbook file.

Note: Since we’re copying the library files specifically created for Workbooks, there’s no requirement to add the UrhoSharp library from NuGet.

Using the Workbooks application, create a new Console Workbook. In a code cell, add a reference for the UrhoSharp library and include two using directives:

#r "Urho.dll"
using Urho;
using Urho.Shapes;

Now create an instance of SimpleApplication:

SimpleApplication app = SimpleApplication.Show();

When that method executes, a window will pop up on your screen to host the UrhoSharp graphics. SimpleApplication creates a default camera, a point light source, and a root node. A 3D scene in UrhoSharp is a tree of nodes. This hierarchical node architecture turns out to be quite convenient when you want to reference a whole subset of 3D components with a single object.

Creating Objects

The following code creates a new node and associates it with the Box shape:

Node boxNode = app.RootNode.CreateChild("boxNode");
Box box = boxNode.CreateComponent();

When that code executes, you’ll see a box on the UrhoSharp window:

These simple shapes become much more versatile when you realize that you can apply transforms to them. You can move them around the scene, of course, but you can also apply scaling and rotation that’s different in the three dimensions:

boxNode.Scale = new Vector3(3, 0.25f, 0.25f);
boxNode.Rotation = Quaternion.FromAxisAngle(Vector3.UnitZ, 45);

Now the box has become a thin bar that’s no longer constrained to the axes of the 3D coordinate system:

And, of course, you can set a different color or use a bitmap for texturing. These shapes become a fast and easy approach to creating 3D graphics for visualization purpose, as demonstrated by the Charts Workbook, which uses the Box class to create a little bar chart:

You can also combine these basic shapes to create more complex objects. The Creating Compound Shapes Workbook exploits this technique to the max: it starts with a torus, two cylinders that are scaled to a skinny size, and two circles that are squashed to shapes that look like propeller wings:

Now the node hierarchy implemented by UrhoSharp comes in very handy, for nodes can be cloned and can have transforms applied that also impact all child nodes. This technique allows one arm to be cloned into four arms:

The Workbook goes on to describe the animations to make the wings rotate, and then lets you fly the quadcopter around the screen.

The latest Urho Workbook is called Building Polyhedra with UrhoSharp. This one might have a special appeal to anybody who spent at least part of their childhood making 3D figures out of folded cardboard.

The workbook begins with constructing a plain old dodecahedron:

The dodecahedron has 12 faces (as its name suggests), each of which is a pentagon. As a convex regular polyhedron, it’s one of five possible Platonic solids.

But then the Workbook builds upon this figure to make another figure that is certainly related but looks quite different. Each of the pentagon faces in the dodecahedron becomes the center pentagon of a five-pointed star:

This is a process known as stellating the polyhedron, and this particular result is called the small stellated dodecahedron. It’s still considered a regular polyhedron because all of the faces are the same five-pointed star, but it’s definitely not convex any more.

The Workbook then takes another step by replacing the five-pointed stars with pentagons whose vertices are the same as the points of the stars:

This is known as the great dodecahedron, and yes, another step can replace those pentagons with larger five-pointed stars to create the great stellated dodecahedron… but to see that, you’ll have to run the Workbook!

(It’s definitely more fun that way.)

Summary

Workbooks is an incredibly valuable learning tool, and the Workbooks demonstrate the power and versatility of UrhoSharp and the ability to create professional 3D objects and animations. Workbooks allows you to quickly and easily try new ideas, as well as create samples and tutorials for others.

Don’t forget to check out our guides on both Workbooks and UrhoSharp, as well as the Xamarin Workbooks page containing all our sample Workbooks.