Axiom

A Guide to Getting Started with Axiom

Michael Cummings — Mon, 09 Jan 2012 21:54:00 GMT

Axiom can be a little daunting when you first start working with it. This guide is designed to get you through the first initial hurdles and get you going on your first project using the library.

A Brief History

Axiom was started in 2003 by Chris McGurk ( leedgitar ) as a port from the popular OGRE project . Chris led the project until 2004, adding many features and providing a solid base from which to continue. I ( borrillis ) became the project lead in September of 2005 after a long pause in the projects progress. Today Axiom is very close to being feature compatible with OGRE. For a full feature list visit the project site. Over the last 5 years, there have been many people who have contributed to the project, providing many useful features and additions.

Packing List

Before you start creating a new project and using the Axiom SDK, lets make sure that all the required pieces are in place. You’ll need a proper build environment with all the dependencies installed for your project before you start writing code.

Operating System / CLI

The first step is to make sure you have a managed code environment installed. Currently Axiom supports Mono 2.10+ on Windows, Linux and MacOS and .Net 2.0+ on Windows.

Development Environment ( Editor )

Next, make sure you have a supported IDE. The following list is currently the active IDE’s that are supported by the Axiom team:

Visual Studio 2008, 2010
Visual Studio C# Express
MonoDevelop 2.0+
SharpDevelop 3.0+
Command Line ( MSBuild / XBuild )

Dependencies ( other libraries )

In order to work properly, Axiom uses several libraries to make it easier to access the underlying hardware. Some of these are included in the downloads, others can’t due to licensing restrictions or it may just be easier to have you install it yourself. Regardless, the libraries you’ll need to install will vary based on your OS, and which rendering API you’ll be using. Axiom has renderers for DirectX 9, OpenGL 2.0 and XNA 3.1 included in the download.

Operating System	Rendering API	Requirements
Windows	XNA	XNA Game Studio 3.1
Windows	DirectX	SlimDX ( June 2010 )
Windows	OpenGL	OpenTK
Linux / MacOS	OpenGL	OpenTK

In addition to the Rendering API, there are several plugins to Axiom that have additional dependencies. If you intend to use them you’ll have to install these addition dependencies as well, use the following table to identify what else you’ll need.

Plugin Type	Plugin	Requirements
Media Codec	Devil	DevIL Imaging Library ( libdevil1c2 )
	System.Media	.Net/ Mono Framework Support
	FreeImage	FreeImage Library
Miscellaneous	CgProgramManager	NVidia CG Toolkit ( nvidia-cg-toolkit )

To make this easier, most for the dependencies are included for Windows the exceptions being SlimDX and Xna. The method of how to installing these dependencies will vary based on your operating system. For the most part on Windows, an installer or setup is provided. For Linux and MacOS use your systems package installer ( apt-get, Synaptic, etc )

One last dependency is on FreeType. FreeType is used to render fonts on platforms where we can run native libraries, basically everything except XBox and Windows Phone.

The next post will dive into downloading the SDK and setting up your first project!

Axiom v0.8.0.0 Beta 2 Released

Michael Cummings — Tue, 02 Mar 2010 09:23:14 GMT

I am pleased to announce the next release of Axiom, v0.8.0.0 Beta 2. Get it here.

Axiom, XNA and RenderToTexture

Michael Cummings — Fri, 23 Oct 2009 17:24:00 GMT

So I learned something interesting about XNA. In Axiom, you can setup your entire scene before entering the renderloop. This way there isn’t any hiccups while rendering due to loading textures, models etc. In addition to Models and textures you can also setup additional render targets. These can be used for reflection planes, shadows, dynamic textures and what have you.

Well this all works really well in DirectX and OpenGL. I can setup a (DX) Surface and hold that until I’m ready to render to it. In XNA however, there is a distinction between a Texture and a RenderTarget. You can only set RenderTargets on the device, and once your done rendering, you can take it off the device and get the result using GetTexture().

This is how the original RenderToTexture (RTT) was implemented in XNA. However, GetTexture() is slow and calling it each frame caused a significant reduction in the number of frames per second. I threw in a quick optimization that only grabbed the Texture2D using GetTexture() once, to see if the reference was still valid between frames. My intuition was correct, the Texture2D that gets returned by GetTexture() isn’t recreated for each frame and I was able to get a 10% increase in my framerate.

To make the code even nicer, I decided that I should grab the Texture2D as early as possible, right after I new up the RenderTarget.

XFG.RenderTarget2D _renderTarget = new XFG.RenderTarget2D(_device, SrcWidth, SrcHeight, numMips, xnaPixelFormat);
XFG.Texture2D _normTexture = _renderTarget.GetTexture();

Bad Idea.

Now when calling GetTexture() I am getting a error that states I can’t call GetTexture() while the RenderTarget is still set on the device. ”But I haven’t set you on the device yet”, I screamed in frustration. After a little fiddling and discussion on the #xna IRC channel, which was more on why I needed what I needed than actually solving the problem, I found my solution.

XFG.RenderTarget2D _renderTarget = new XFG.RenderTarget2D(_device, SrcWidth, SrcHeight, numMips, xnaPixelFormat);

XFG.RenderTarget2D _oldTarget = _device.GetRenderTarget( 0 );
_device.SetRenderTarget( 0, _renderTarget );
_device.SetRenderTarget( 0, _oldTarget );
Texture2D _normTexture = _renderTarget.GetTexture();

The error I was getting was a very good description of what was happening. XNA it seams does not create the Texture2D returned by GetTexture() until after it has been set on the device at least once. After that GetTexture() will return a valid Texture2D as long as it is no longer set on the device.

There are two things to remember from this, one, GetTexture() is slow, keep a reference to the Texture instead, and GetTexture() isn’t valid until the RenderTarget has been on the device at least once.

Creating .Net Configuration Sections

Michael Cummings — Thu, 24 Sep 2009 19:16:00 GMT

A while ago, I removed the configuration handling that was embedded in the Axiom core. I firmly believe that how the configuration information is stored should be the decision of the Application Developer not the library. I kept the format and just moved the relevant classes into the Demos. That particular implementation relied on a custom Typed DataSet and really didn’t fit with the whole .Net configuration patterns. So I decided it was time to look into creating a custom configuration section for the App.config as an example of a good practice for storing engine configuration.

It’s been a long time since I last had to create a custom configuration section for a .Net application. The last time I looked at it was pre .Net 2.0. At that time you would create a class that implemented IConfigurationSectionHandler. Since .Net 2.0 there has been a change to now use ConfigurationSection or ConfigurationSectionGroup to derive from to create your configuration sections.

After spending roughly 6 hours implementing a simple custom configuration section handler, I had a working class. All it did was specify the log file so I could configure the Root object in Axiom, but it was working. The next step was to figure out how to build a set of elements to store ResourceLocations, RenderSystem Options and Plugins. And this is where I found out that build custom Configuration Sections was hard.

While researching the net for something, I came across a StackOverflow post that was fairly relevant ( I’m finding more of these are showing up higher in Google’s page ranks ). One of the followups to the post, was someone asking ‘why would you bother trying to code custom configuration sections by hand anymore, check out the Configuration Section Designer’. I cocked my head a little to the left and clicked the link to see if it was worth it.

Read the home page – 2 minutes
Download and Install – 5 minutes
Use the Designer to create section – 30 minutes

Not having to code that by hand – Priceless

I am not going to go into any detail on how to create these sections using the CSD, it really was very easy and intuitive to use. I only had about 5 minutes worth of pain as I figured out which properties are required, for the various elements. So the next time you want to create a custom configuration section, head on over to http://csd.codeplex.com and download the Configuration Section Designer and save yourself countless hours of coding and debugging.

Axiom 0.7.5.0 Beta 1

Michael Cummings — Thu, 19 Feb 2009 22:22:47 GMT

Today I released the first Beta of the next version of Axiom. Axiom is a C# 3D rendering engine. This year marks the 6th year of it’s existence. I have been maintaining it for the past 3 years. I am particularly excited about this release because for the first time we are shipping some brand new features.

XNA Renderer

The largest feature that was added for 0.7.5.0 was the XNA Renderer. It has been in development for the past year. A large hurdle for the XNA renderer was the absence of any fixed function pipeline support. Only vertex and pixel shaders can be used. Since Axiom is old enough to still support the fixed function pipeline, it needed a way to provide that functionality using a shader. The result of this is the FixedFunctionEmulation layer. It will take the fixed function state of the engine aand generate a set of shaders on the fly. This will unfortunately only work with XNA on the windows platform as the XBox does not allow compilation of shaders at runtime. In this release the only Axiom functionality not supported is shadows. The plan is to have shader based shadows by the time this version is final.

The windows support of XNA in this release is much richer than the XBox. Axiom includes a custom pipeline component to load textures instead of using the native library DevIL. DevIL works wonderfully on the Windows platform, however native code cannot be used in XNA projects on the XBox. Rather than port the library over, I leveraged the XNA Content Pipeline to load the textures into the standard resource system. Additionally, the XNA Content Pipeline was used to precompile HLSL files into VertexShaders and PixelShaders for the XBox. Version 3 of XNA only supports FX files by default. Since Axiom has it’s own Material System, I don’t need FX files. I plan to add FX file support in a future release.

Once the final is released I am really hoping to see someone create a game using Axiom and publish it on the Community Games for XBox Live. That would be just awesome.

Project Files

Another big change for this release is in the build system. Previously I did not keep the project files in source control or ship them. Instead Prebuild was used to generate them specifically for your environment. This worked generally, and was necessary because SharpDevelop, Monodevelop and Visual Studio all supported different project file formats. As of MonoDevelop 1.0, SharpDevelop 2.2 and Visual Studio 2008, they now all support the 2008 version of the project file format. This means that now all project files are in the source control repository and shipped as part of the distribution. This should make it easier for newer users to get started with Axiom.

Additionally this will mean adoption of metabuild as the project build system, replacing the custom nAnt build scripts currently in use. The only roadblock for metabuild is Mono’s support for MSBuild scripts. Mono’s implementation of MSBuild, called xbuild, is still fairly immature, however I am testing it out with the Axiom projects to see how well it works.

The obligatory screenshots

Below you will find a few of my favorite demo screenshots. These are all running on windows using the XNA Renderer. Not bad for a managed engine.

What’s next?

After this version is complete and final, I already have another set of features hot on it’s tail. There is a post processing framework ( Blur, HDR ), better material handling, better window management, background loading of resources, an overhaul of the OpenGL Renderer and much much more.

call to action

Please, in order for Axiom to be the best it can be, I need some assistance in making sure the new features do what they are supposed to. More importantly, do what you need them to do. So go download Axiom today and kick it’s tires, file bug reports, and send me feedback.