Unofficial OpenGL Software Development Kit: Using the SDK

Unofficial OpenGL Software Development Kit 0.5.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Using the SDK

Once you have built the SDK's libraries, you may use them with your own projects. There are two ways to use the SDK's libraries. You can use them as part of a project that uses Premake, or you can use them in a project that directly uses native build systems.

The SDK is built around Premake, so you will find that it is much easier to make applications using the SDK if you generate your build files with a Premake script.

# With Premake

This section assumes that you are familiar with Premake4. You should know how to set up a `premake4.lua` build file. You should know how to link projects to static libraries and modify include directories. In short: you should use these instructions if you are reasonably proficient with Premake4.

Usually when using Premake 4, you will have a file called `premake4.lua` in your directory. This file may call other files to generate the solutions and projects, or it may not.

Regardless of whether the main `premake4.lua` file does all the work, the first thing you should do is execute this instruction:

`dofile("path/to/GLSDK/links.lua")`

The `path/to/GLSDK` is the path to the location where the SDK resides. It may be relative or absolute, as you see fit. The `links.lua` file is a file in the root of the SDK. You should only execute the file once (it is not a proper Lua module, so you should not use `require` on it), but executing it multiple times will not be harmful.

This file defines a number of global functions. These functions are to be used when defining a project with Premake's `project` command. They will alter the project so that it links with one or more libraries.

For example, in a Premake script, you might have a project defined like this:

project "MyProject"
kind "ConsoleApp"
language "c++"
files {"*.cpp", "*.h"}
configuration "windows"
defines "WIN32"
links {"glu32", "opengl32", "gdi32", "winmm", "user32"}
configuration "linux"
links {"GL"}
configuration "Debug"
targetsuffix "D"
defines "_DEBUG"
flags "Symbols"
configuration "Release"
defines "NDEBUG"
flags {"OptimizeSpeed", "NoFramePointer", "ExtraWarnings", "NoEditAndContinue"};

To link to the SDK libraries, you use the `UseLibs` function. This is done quite simply:

project "MyProject"
kind "ConsoleApp"
language "c++"
files {"*.cpp", "*.h"}
UseLibs {"glload", "freeglut"}
configuration "windows"
defines "WIN32"
links {"glu32", "opengl32", "gdi32", "winmm", "user32"}
configuration "linux"
links {"GL"}
configuration "Debug"
targetsuffix "D"
defines "_DEBUG"
flags "Symbols"
configuration "Release"
defines "NDEBUG"
flags {"OptimizeSpeed", "NoFramePointer", "ExtraWarnings", "NoEditAndContinue"};

The line `UseLibs {"glload", "freeglut"}` will bring in the GL Load and FreeGLUT libraries. The project will have the include paths added to the per-project include paths. The project will link to the debug and release libraries as appropriate. And any special `#define`s or other settings will also be provided.

The names of the libraries used with `UseLibs` are as follows:

- glload: GL Load
- glimage: GL Image
- glutil: GL Util
- glmesh: GL Mesh
- glfw: GLFW
- freeglut: FreeGLUT
- glm: GLM
- boost: Boost

Some of the SDK libraries have dependencies on other libraries. For example, GL Mesh can't work without GL Load. And so forth. In all cases, dependent libraries will be included. So if you call `UseLibs` with "glmesh", you will also get GL Load and boost (because it needs that too).

Only hard dependencies will be included. For example, GL Image needs GL Load, but only to upload image data to OpenGL textures. Because this is a soft dependency (and because you need to explicitly initialize GL Load before GL Image can use it), you must explicitly include "glload" if you want to use that part of GL Image.

Note that all of the libraries are built linking non-statically to the C++ runtime libraries (where available on the platform). Therefore, you should not use the `StaticRuntime` flag in Premake4.

# Native Build

If you wish to natively link to the SDK libraries, but do not use Premake to generate your build files, you will have to do a bit of extra work. Each library has its own include paths and so forth.

This section assumes that you are familiar with your build tools. You should know how to link to static library files, add directories to your include path, and add defines to your build on a per-project basis.

All of the libraries are built linking non-statically to the C++ runtime libraries (where available on the platform). Therefore, any code using these libraries must do the same.

The libraries use the same basic names for GCC-based builds as Visual Studio builds, but they have different extensions and prefixes. The VS libraries end in ".lib", while the GCC libraries end in ".a". The VS libraries have no prefix, while the GCC versions all begin with "lib".

So, if there was a library named "thingD", the GCC version would be "libthingD.a", while the VS version would be "thingD.lib".

All directories listed are relative to the root directory of the distribution.

## GL Load Linking

The include path you need to add to your build system for this library is `"glload/include"`. The libraries are in the `"glload/lib"` directory. The debug and release libraries are called `"glloadD"` and `"glload"`, respectively.

## GL Image Linking

The include path you need to add to your build system for this library is `"glimg/include"`. The libraries are in the `"glimg/lib"` directory. The debug and release libraries are called `"glimgD"` and `"glimg"`, respectively.

## GL Util Linking

The include path you need to add to your build system for this library is `"glutil/include"`. The libraries are in the `"glutil/lib"` directory. The debug and release libraries are called `"glutilD"` and `"glutil"`, respectively.

## GL Mesh Linking

The include path you need to add to your build system for this library is `"glmesh/include"`. The libraries are in the `"glmesh/lib"` directory. The debug and release libraries are called `"glmeshD"` and `"glmesh"`, respectively.

## GL Mathematics Linking

GLM does not have a compiled library; it is header only. To include the GLM headers, just add the `"glm"` directory to your include path.

## GLFW Linking

The include path you need to add to your build system for this library is `"glfw/include"`. The libraries are in the `"glfw/library"` directory. The debug and release libraries are called `"glfwD"` and `"glfw"`, respectively.

## FreeGLUT Linking

The include path you need to add to your build system for this library is `"freeglut/include"`. The libraries are in the `"freeglut/lib"` directory. The debug and release libraries are called `"freeglutD"` and `"freeglut"`, respectively.

You will also need to add some #defines to your command line. These are:

- FREEGLUT_STATIC
- _LIB
- FREEGLUT_LIB_PRAGMAS=0

## Boost Linking

The only sections of Boost that are included are the header-only parts. So there are no libraries. But you do need to have your include path use `"boost"`.

You will also need to add some #defines to your command line. These are:

- BOOST_ALL_NO_LIB

## SDK Dependencies

One more thing. Some of the SDK libraries are dependent on other SDK libraries. You could just include them all and be done with it. But if you only want to include the bare minimum you need, here is the lsit of dependencies. Any library not mentioned has no dependencies:

- GL Util: Boost, GL Load (for some functions)
- GL Mesh: Boost, GL Util, GL Load, GLM
- GL Image: Boost, GL Load (for the texture upload functions)

# Other Includes

While the Unofficial OpenGL SDK is intended to be self-contained, there is one external dependency that is unavoidable, by the very nature of its purpose: OpenGL itself.

Each platform has its own ways of dealing with OpenGL. In most cases, you will only need to download and install recent graphics drivers. Exactly what you must link to and what include paths you need is system-dependent.

For Windows, you will need to link to some of the following libraries. All of them come with your build tools (or you need to download the Windows Platform SDK):

- `opengl32.lib`: The basic Windows interface to OpenGL. If you are building a 64-bit application, it still links to `opengl32.lib`
- `glu32.lib`: An old utility library for OpenGL. Needed by FreeGLUT or older OpenGL applications.
- `gdi32.lib`: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT.
- `winmm.lib`: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT.
- `user32.lib`: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT.

For Linux, you will need to link to some of the following libraries. All of them come with your build tools or are otherwise a part of your system:

- `libGL`: OpenGL's interface on Linux.
- `libGLU`: An old utility library for OpenGL. Needed by FreeGLUT and GLFW on Linux.
- `Xrandr`: An X-Windows extension that allows accessing low-level screen behavior. Needed by GLFW for full-screening applications.