Taking advantage of high-level C# features to make our 3D games API or platform independent

In the last few years, programming languages and development tools have evolved quite a bit. Visual Studio is a masterpiece nowadays, and things like Refactoring and Intellisense make our life much easier.
There are other cool features that can be now used in our code, and that are really appropriate to make our 3D engines API-Independent. I´m talking about Generics and Extension Methods.

What is API or platform multi-targeting?

Multi-targeting is writing a software (a game, for instance) that can run in different platforms or use different APIs. Of course, we should try to achieve this with the following constraints:

Avoid redundancy as much as possible (as we already saw that Duplicating is wrong).
If possible, introduce no performance overhead at all, or at least try to minimize it

When is multi-target necessary?

It is obviously necessary if your application is meant to be distributed for different platforms (XBox, PS3, PC, etc, for example). But making your software multi-target is also very recommendable in other situations, for example when you need to upgrade your technology to a newer version of an API.
For instance, imagine that DirectX11 just came out. You would like to take advantage of some new features of it, but cannot force all your clients to upgrade their graphics cards, so you still need to support DirectX10. The solution is to make your software support both DirectX10 and 11, with multi-targeting. In this article, we will use the case of targeting an application to two different render APIs: SlimDX and XNA.
If you already faced this problem before, you know it can be a serious one, especially if your software was not designed to support multi-targeting from the beginning, and you have API calls scattered all around your code. How do we make the change without needing to re-write the entire software from scratch?
Let’s explore the possibilities:

A macro-C++ approach

When using languages like C++, some people make multi-targeting using Macros:

Write all your game-logic code using your own MACRO-named types like: myMatrix4x4, myTexture, etc.
Write a header file for each platform, in which all that macros are declared:

#define myVector3 Microsoft::Xna::Framework::Vector3

#define myMatrix4x4 Microsoft::Xna::Framework::Matrix

But remember, MACROS ARE THE SOURCE OF ALL EVIL IN THE WORLD.
Macros easily grow in complexity. Specially if you start making multi-level macro calls. They make debugging and understanding the software a hell on Earth, and are extremely bug-prone, if you are not very careful. They have even been removed from modern languages like C#. So I totally discourage you to use this solution.

Pros:
Cons:

The conditional compilation approach

As we have already seen, some parts of your code must be different for each platform, so an obvious and easy way to make your software multi-target is using conditional compilation.
This approach is supported in almost every language, and works by defining compilation constants in your project like: PLATFORM_XNA, or PLATFORM_SLIMDX. Then, each time you find an API-dependent code part, you do something like:

#if(PLATFORM_XNA)

...

#else

...

#endif

Pros:
Cons:

The layered approach

This is one of the usual approaches. It is related to software engineering more than to an specific language, and involves all the stages of development, since conception and first designs, to the final coding.
What it suggests is dividing your application in “layers”, keeping internal layers for the game-logic related issues, which do not depend on the API or platform at all, and making an external layer that will give output to all that logic, through the API. This way, when you need to target a different platform, only the external layer has to be rewritten.
This external layer, usually deals with things like Rendering, that’s why it’s very typical to find games out there with DLLs like: RendererDX9.dll, RendererDX10.dll, etc.

Pros:
Cons:

You will end up with lines of code like:

RendererDX9.RenderModel(this);

Instead of the traditional:

this.Render();

Some people would say that rendering an object is not a task naturally belonging to that object. Well, as I said, this is a matter of personal preference, and I prefer the second approach. That’s why in next chapter we will try to make a multi-target system that follows it.

The inheritance approach

This approach is elegant as well (as the previous one). It also related to engineering and planning more to an specific language, and also involves many stages of the development.
Instead of dividing your software in layers, it relies mostly on Inheritance, through a very basic design for classes that are API-Dependant like the next example:

Model3DBase

It is quite obvious that we will put in the base class all the non API-dependent code, and the rest in the child classes. For example, the ToString() method has nothing to do with the platform the 3D model will be rendered in. So that code will be in the base class, avoiding rewriting it for each child.
Once we have all the classes divided for each version of the API, in the outer part of your software you just need to choose which kind of Scene to use. Something like: SceneSlimDX or SceneXNA.
This approach works, it’s elegant, easy to understand and trace, and keeps the consistency of classes, but it has a major drawback: for classes like this (a 3D Model), many many member variables and methods will be API-specific, so the amount of code in the base class will be much lower than in the child, dependent classes. This will force you to write a huge amount of duplicated code, and we already said that duplicating is wrong.

Pros:
Cons:

It requires some design effort
It’s sometimes not a feasible solution if the project is already written (the multi-target was not planned from the beginning), as it implies big structural changes.
Splitting your types for each API won´t help reducing redundancy in higher code levels too (what will happen when we are going to use the model? which version will be use? Again conditional compilation?)
The biggest problem is the redundancy of code mentioned (many code parts will be repeated in the child classes)

So, which one is best?

Again, this is all a matter of personal preference.
Macros are discarded by themselves… too bug-prone, and not present in modern languages. In my opinion, best option is a combination of: a little bit of conditional compilation (in very few cases), and in some cases a bit of layered design too. But whatever we choose, all of them have the same problem: code redundancy.
If only we could reduce that code redundancy…

C# comes to save the day

.Net has been introducing improvements to software development since it’s conception. It saves you time. It saves you money. It saves you headaches. It saves you stress. In my opinion, that’s precisely the strong selling point of .Net.

Microsoft has succeeded in making programmers’ life easier, with no renounce to performance, efficiency or robustness

In the latest releases, .Net is going even further, introducing new ways of development that can, not only make your life easier, but also offer you the possibility to face old problems in new ways. This case is just an example.

Extension Methods

Many times, APIs are similar to each other. You will have textures, you will have 3D models, you will have vertices and faces. Even rendering methods will be probably similar. And it´s a pain having to add conditional compilation just for something like finding the number of vertices in a 3D model mesh:

#if(RENDER_XNA)

            int vertexCount = mMesh.NumVertices;

#elif(RENDER_SlimDX9)

            int vertexCount = mMesh.VertexCount;

#endif

Both XNA and SlimDX offer that information, but the name of the property changes. There are many many cases like this where code changes are just semantics, or just re-arranging stuff. And it´s a pity to add redundancy all around your code for such a simple thing.
We of course can put a “GetVertexCount” method or a “VertexCount” property in our Model3D class, but… What happens when we are working with simple Meshes (no access to our own Model3D type)? Conditional compilation again?
Not yet… Because Extension Methods can help here…

What are Extension Methods?

Extension Methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type.
So, we can take the type "SlimDX.Direct3D9.Mesh”, or “Microsoft.Xna.Framework.Graphics.ModelMeshPart”, and add a method to it. Just like if we could modify its code.
This way, we are allowed to unify or standardize the interfaces of API-dependent types, to drastically reduce the need for conditional compilation, and therefore code redundancy.

How do they work?

Following what´s explained here, we can easily code the “GetVertexCount” method like this:

public static int GetVertexCount(this Microsoft.Xna.Framework.Graphics.ModelMeshPart pMesh)

{

     return pMesh.NumVertices;

}

public static int GetVertexCount(this SlimDX.Direct3D9.Mesh pMesh)

{

     return pMesh.VertexCount;

}

Note: You just need to add that method to a static class in your DLL that holds Extension Methods.
Having this, both XNA´s ModelMeshPart and SlimDX´s Mesh will offer the GetVertexCount method. With the exact same interface. So, any part of our code that wants to have this information won´t need to add conditional compilation nor redundancy anymore.
We can do similar stuff with many many differences between APIs: properties renamed or relocated, methods with different or re-arranged parameters, or even creating methods that exist in one API and not in the other.

The objective is to unify the interfaces of both APIs as much as possible.

What about performance?

We are adding a call to a method where there wasn’t any. So, in theory, we are adding a performance overhead. But here is where the Visual Studio compiler comes to help.
As you already know, there is a thing called Inlining that will help here. When your code is compiled, the compiler will replace any call to the GetVertexCount method with it´s real inner code. So no performance overhead is really added.
However, you should take care with Inlining, as there are several conditions for this to happen:

Methods that are greater than 32 bytes of IL will not be inlined.
Virtual functions are not inlined.
Methods that have complex flow control will not be in-lined. Complex flow control is any flow control other than if/then/else; in this case, switch or while.
Methods that contain exception-handling blocks are not inlined, though methods that throw exceptions are still candidates for inlining.
If any of the method’s formal arguments are structs, the method will not be inlined.

More info on Inlining: here, and here and here.

C# comes to save the day (II)

Generics

Since 2.0, .Net introduced Generics, a way to work with variables without specifying what type they are. This is especially useful for cases where the type of those variables is irrelevant. One of the direct and most useful examples that soon appeared is Generic Collections. The logic behind a List or Dictionary of things is the same, no matter what that “things” are.

How can Generics help out here?

Generics introduce two clear advantages:

Generics are resolved at compilation, so no performance overhead is introduced at all. In fact, Generics can imply some performance advantages, in certain cases. Read this article (Generics implementation chapter) for more information.
Generics will again dramatically reduce the Duplication and redundancy of information and code in our projects.

Reducing duplication even more, with generics

Apart from using Extension Methods, as we have seen in the previous chapter, we can reduce Conditional Compilation and code redundancy even more, with the use of Generics.
Many times, some parts of our code need to add conditional compilation just because types used are different on each API, but the operations performed on them don´t need to know what type they actually are. For instance, if we create a Material class, it will probably hold a list of textures, and the Texture type is API-dependent. Will we need to add conditional compilation every time we want handle that list of textures? Probably not.
Making the Material class to be generic, will allow us to work with Textures, without knowing if they actually are SlimDX or XNA textures:

public class Material<T_Texture>

{

     protected List<T_Texture> mTextures;

}

That reduces redundancy in the Material class, as any management of the List of textures can be done without knowing the type: adding or removing textures, accessing to them, etc.

What if we still need to perform an API-dependent operation in a generic class?

Sometimes, your classes won´t be purely generic, and still will need to perform some operations that are API-specific. In those cases, you can always check what the type of the generic T_Texture actually is.
Just like in the following example, where the generic type is checked to return one type of value or another:

 public static T GetRenderState<T>(this Microsoft.DirectX.Direct3D.Device pSrc, RenderState pState)            

        {

            if (typeof(T) == typeof(int))

                return (T)Convert.ChangeType(pSrc.GetRenderStateInt32((RenderStates)pState), typeof(T));

            else if (typeof(T) == typeof(float))

                return (T)Convert.ChangeType(pSrc.GetRenderStateSingle((RenderStates)pState), typeof(T));

            else if (typeof(T) == typeof(bool))

                return (T)Convert.ChangeType(pSrc.GetRenderStateBoolean((RenderStates)pState), typeof(T));

            else throw new System.ApplicationException("Generic Type invalid");

        }

Using the generic (Material) class

When the Material class is finished, we will probably want to use it in a Model3D class. We just need to do something like:

public class Model3D

{

    #if(RENDER_XNA)

         protected Material<Microsoft.Xna.Framework.Graphics.Texture2D> mMaterial;

    #elif(RENDER_SlimDX9)

         protected Material<SlimDX.Direct3D9.Texture> mMaterial;

    #endif

}

This way, we remove any conditional compilation or code redundancy from the Material class, and add it just a couple of times when declaring and instantiating the mMaterial variable.

Going even further with conditional #using statements

This is pretty obvious, but anyway it might help someone.
Many times, types have the same names in several APIs. For instance, the type VertexBuffer exists in: XNA, in SlimDX and in Managed DirectX.
For such cases, we can reduce conditional compilation and code redundancy even more, with #using statements at the beginning of each code file. Imagine we have a class XXX like the following:

public class XXX

{

    #if(RENDER_XNA)

        protected Microsoft.Xna.Framework.Graphics.VertexBuffer mVertexBuffer;

    #elif(RENDER_SlimDX9)

        protected SlimDX.Direct3D9.VertexBuffer mVertexBuffer;

    #endif

}

In that case, we are adding the conditional compilation just because the namespace of a type changes. It´s much better to add the conditional compilation just once in the #using statements, avoiding to spare them all through your code:

#if(RENDER_XNA)

    #using Microsoft.Xna.Framework.Graphics;

#elif(RENDER_SlimDX9)

    #using SlimDX.Direct3D9;

#endif

public class XXX

{

    protected VertexBuffer mVertexBuffer;

}

Using Generic’s constraints to reduce even more redundancies

We still didn’t mention other possibilities Generics have, like Constraints. Constraints are a way to tell the environment that, even when a type is Generic (like T_Texture), it meets certain constraints, like to have a constructor, or to inherit from a class or interface. Just an example:

public class Model3DBase<T_Material, T_Texture>

    where T_Material : MaterialBase<T_Texture>

{

        protected List<T_Material> mMaterials;

}

This makes an huge difference reducing duplication as now, even specifying no type for T_Material, we will be able to access all the properties and methods specified in MaterialBase.
Other examples:

Constraint	Description
where T: struct	The type argument must be a value type. Any value type except Nullable can be specified. See Using Nullable Types (C# Programming Guide) for more information.
where T : class	The type argument must be a reference type, including any class, interface, delegate, or array type. (See note below.)
where T : new()	The type argument must have a public parameterless constructor. When used in conjunction with other constraints, the new() constraint must be specified last.
where T : <base class name>	The type argument must be or derive from the specified base class.
where T : <interface name>	The type argument must be or implement the specified interface. Multiple interface constraints can be specified. The constraining interface can also be generic.
where T : U	The type argument supplied for T must be or derive from the argument supplied for U. This is called a naked type constraint.

Want to know more on Generics?

This magnificent article on generics will explain you more about this issue.

Conclusion

C# and .Net are offering new ways of facing old problems. This article tried to show how to take advantage of some new features like Generics and Extension Methods in a very old problem: API-independent 3D engines.
So, we took those new functionalities and combined them with old approaches of facing this issue, to come with a new, improved implementation, that has a basic objective: reduce code redundancy.
Hope you liked it.
Cheers!