Chapter 1: Installation

To use OpenTK, you will need either the .Net 2.0 runtime (Windows) or the latest 1.2.x Mono release (Linux/Mac OS X/Windows). If you are using Mono, your are strongly advised to upgrade to the latest available version, as releases older than 1.2.6 contain bugs that affect OpenTK stability.

If you plan to build from source, you will need to obtain Nant (this dependency will be removed in the future).

Last, but not least, head to the Sourceforge project page and obtain OpenTK. OpenTK releases are simple zip/7z archives and installation consists of extracting the archive contents to a location on the disk - it is not possible to install OpenTK to the Global Assembly Cache at this point.

To use OpenTK, just have your project reference OpenTK.dll. You should also place OpenTK.dll.config in the same folder as your project's binaries, to achieve "compile once - run everywhere" compatibility.

Check the following pages for platform-specific instructions.

Linux

Installing Mono

If you are using a recent Linux distribution, all prerequisites for OpenTK projects should be readily available: the Mono runtime and the Mono compilers. Execute "mono --version" and "gmcs --version" and check if the output looks like this:

$ mono --version
Mono JIT compiler version 1.2.6 (tarball)
Copyright (C) 2002-2007 Novell, Inc and Contributors. www.mono-project.com
        TLS:           __thread
        GC:            Included Boehm (with typed GC)
        SIGSEGV:       altstack
        Notifications: epoll
        Architecture:  amd64
        Disabled:      none

$ gmcs --version
Mono C# compiler version 1.2.6.0

If one or both of these commands fail, you'll have to install Mono. Mono packages should be readily available through your distribution's package manager, so a line like the following should work:

# Ubuntu and other .deb-based distributions
sudo apt-get install mono mono-gmcs
# or
su -c "apt-get install mono mono-gmcs"

# Fedora Core and .rpm-based distributions
su -c "yum install mono mono-gmcs"
If no Mono packages are available, or they are outdated (mono --version returns something less than 1.2.6), you should build Mono from source. There is a message in the support forum describing the process of building mono from source here.

Alternatively, you can find binary packages at Mono Project's download page.

Using a binary release

Download the latest opentk-x.y.z-mono.tar.gz release from Sourceforge and untar it:

tar -xvf opentk-0.3.13-mono.tar.gz
A new opentk-x.y.z will be created with four subfolders: "Documentation", "Examples", "Libraries" and "QuickStart". Try running the examples contained in the second folder to make sure everything works alright:
cd opentk-0.3.13/Examples
mono Examples.exe
A new window will hopefully show up, listing all available examples. If not, check the troubleshooting section below.

The "Libraries" folder contains the main OpenTK assembly (OpenTK.dll) and the OpenTK.dll.config file - these are all you need to run OpenTK projects. If you are using MonoDevelop, check the "QuickStart" folder for a ready-to-use project. Last, don't forget to take a look at the release notes contained in the "Documentation" folder.

Troubleshooting

The following error has been reported on Fedora Core 8, when running Examples.exe:

Unhandled Exception: System.TypeInitializationException: An exception was thrown by the type initializer for System.Windows.Forms.Form ---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.TypeInitializationException: An exception was thrown by the type initializer for System.Drawing.GDIPlus ---> System.DllNotFoundException: gdiplus.dll
  at (wrapper managed-to-native) System.Drawing.GDIPlus:GdiplusStartup (ulong&,System.Drawing.GdiplusStartupInput&,System.Drawing.GdiplusStartupOutput&)
  at System.Drawing.GDIPlus..cctor () [0x00000] --- End of inner exception stack trace ---
This is caused by a missing entry in "/etc/mono/config". To correct this issue, open the aforementioned file (you must be root!), and add this line: <dllmap dll="gdiplus.dll" target="/usr/lib/libgdiplus.so.0" />. Now, Examples.exe should work.

Building OpenTK from source

OpenTK's build system currently uses NAnt, so you'll need to install that:
# Ubuntu
sudo apt-get install nant

# Debian
su -c "apt-get install nant"

# Fedora
su -c "yum install nant"
Once that is out of the way, untar the source release and cd to the Build folder:
unzip opentk-0.3.13.zip
cd opentk-0.3.13/Build
mono Build.exe mono
Wait a few seconds for the compilation to end, and check the "Binaries" folder that just appeared in the base OpenTK directory. To build the debug version, append "debug" so that the last command looks like:
mono Build.exe mono debug

[Add an appendix that describes how to build Mono from source, in case there is no package available]

Windows

OpenTK does not come with any installer or setup. Instead, you download the OpenTK binaries and add a reference to "OpenTK.dll" in your Visual Studio/SharpDevelop/MonoDevelop project. (Unzip the binaries first!)

It is a good idea to add "OpenTK.dll.config" to your project, and make sure the "Copy To Output Folder" (not "compile"!) is set to "Copy Always". The application will run without this on Windows, but not on Linux or Mac OS X, so please don't forget that!

Last, but not least, make sure the "Copy Local" property is set to true for the OpenTK reference, to simplify the distribution of your application.

It's as simple as that!

Troubleshooting

Most problems with running OpenTK-based Applications are related to the target platform missing the proper drivers.

OpenTK requires these components installed:

  • Either Mono or .Net (not both).
  • An OpenGL driver for your graphics card.
  • The OpenAL driver for your Operating System.

Below are links for your convenience. Note: Many of those sites require Javascript enabled to function.

Mono

Novell (Linux, Mac & Windows) http://www.go-mono.com/mono-downloads/download.html

.Net

Microsoft (Windows) http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=...

OpenAL

Note: It doesn't matter what brand your soundcard is, just chose the proper Operating System.

Creative Labs (Mac & Windows) http://www.openal.org/downloads.html
Strangesoft (Linux) http://kcat.strangesoft.net/openal.html

OpenGL

ATi (Linux, Mac & Windows) http://ati.amd.com/support/driver.html
NVIDIA (Linux & Windows) http://www.nvidia.com/Download/index.aspx?lang=en-us
Intel (Windows) http://downloadcenter.intel.com/
Intel (Linux) http://intellinuxgraphics.org/download.html
Mesa 3D (software rendering) http://sourceforge.net/project/showfiles.php?group_id=3

If you have a laptop with an Nvidia card, you can obtain updated drivers through: http://www.laptopvideo2go.com

Last edit of the links: March 2008

Tags for searches:
help problem error outdated trouble crash fail failure exception abort opengl openal driver ati intel nvidia