Source

Unofficial OpenGL SDK / docs / glsdk.doxy


/**
\mainpage Unofficial OpenGL Software Development Kit

The Unofficial OpenGL Software Development Kit is a collection of libraries and utilities that will help you get started working with OpenGL. It provides a unified, cross-platform build system to make compiling the disparate libraries easier.

Many of the components of the SDK are C++ libraries.

Each component of the SDK specifies the terms under which they are distributed. All licenses used by components are approximately like the MIT license in permissivity. The parts of the SDK responsible for maintaining the build, as well as all examples, are distributed under the <a href="http://www.opensource.org/licenses/MIT">MIT License</a>.

The library components are:
 
\li @ref module_glload "GL Load": Used to gain access to OpenGL's functions.
\li @ref module_glimg "GL Image": Used for loading image files into OpenGL textures.
\li @ref module_glutil "GL Utility": General-purpose utilities for OpenGL.
\li @ref module_glmesh "GL Mesh": Used for sending vertex data to OpenGL.
\li @ref module_glm "OpenGL Mathematics": Provides useful math classes and functions for OpenGL, using a GLSL-like syntax.
\li @ref module_glfw "GLFW": A tool for creating and managing an OpenGL window. It can be used to handle input.
\li @ref module_freeglut "FreeGLUT": A tool for creating and managing an OpenGL window. It can be used to handle input, as well as render a few basic shapes.

The SDK also comes with a number of examples, which are in the <tt>examples</tt> directory.

\section mainpage_install Installation and Use

Installation of the SDK is simple. <a href="https://sourceforge.net/projects/glsdk/files/">Download the most recent version of the distribution</a> and unzip the file to a directory of your choice. Then follow the @subpage pg_build "instructions for building the SDK components."

Once the SDK has been successfully built. To use it, follow the @subpage pg_use "instructions for using the SDK."

\section mainpage_support Support

The SDK is undergoing further development. The @subpage pg_changelist "list of changes and new features from prior versions" is available.

Bugs or feature requests should be filed in the <a href="https://bitbucket.org/alfonse/unofficial-opengl-sdk/issues?status=new&status=open">Bitbucket issue tracker</a> for the SDK. However, bugs can also be filed on the SourceForge issue tracker. Questions or other inquiries can be directed to the <a href="http://www.opengl.org/discussion_boards/">OpenGL forums</a>.

You can look on the \ref module_troubleshooting "troubleshooting page" for information about combating common problems.

\section mainpage_notation Request for Aid

The Unofficial GL SDK is still in Alpha at present. Currently, the SDK is missing the following libraries:

\li Font rendering: A library for rendering glyphs from fonts and doing the most basic of text layout.
\li Mesh rendering: A library for loading and rendering meshes.

The main issue is finding good, well-maintained libraries that can do these. Libraries that rely on compatibility profiles are not acceptable for the SDK, yet most of the available libraries that perform these tasks do.

They do not have to be C++, but they should have no additional dependencies outside of the <em>absolutely necessary</em>. For instance, FreeType2 would be essential for any font library, as there's no way anyone should be expected to reinvent that wheel. But outside of that, there should be no extra dependencies.

The MIT License is preferable, but similar BSD-style licenses are also accepted. Since the SDK uses static linking (for ease of use reasons), GPL and LGPL libraries are not acceptable.

**/

/**
\page pg_build Building the SDK

In order to build the SDK, you must first have installed your development environment of choice. Please ensure that your development environment is functional and up to date.

Supported development environments are:

\li Visual Studio 2008 and 2010, including express editions
\li GNU Make, including Cygwin and MinGW
\li Code::Blocks
\li CodeLite

\note At present, the OpenGL SDK has not been tested under any form of Mac OS.

Outside of the Premake utility, the Unofficial OpenGL SDK is completely self-contained. It has no external dependencies. Simply <a href="https://sourceforge.net/projects/glsdk/files/">download the distribution</a> and unzip the package into a directory of your choice.

\section page_build_premake Premake

To simplify the build process for the SDK across platforms, the build system used for the SDK is the <a href="http://industriousone.com/premake">Premake utility</a>, version 4.3 or later.

Premake is a utility for generating build files; it does not do the building itself. The general idea is this: you run the Premake program on Premake scripts. This will generate the build files for your development environment of choice. Then you use those build files in that development environment to build your project.

For example, if you are using GCC and the standard GNU tools, Premake would generate a <tt>Makefile</tt>, which you would then use GNU Make on as normal. If you use Visual Studio, Premake generates <tt>.sln</tt> and <tt>.vcproj</tt> files for the VS version of your choice.

For each build tool, Premake has a command to generate the build files for that tool. For example, to execute Premake for Visual Studio 2008, the following command line would be used:

\code
premake4 vs2008
\endcode

To build a GNU Makefile, one would use

\code
premake4 gmake
\endcode

Each build tool that Premake supports has its own command; the <a href="http://industriousone.com/premake-quick-start">Premake documentation</a> explains how they work.

\section page_build_libs Building the Libraries

To compile the libraries that are part of the SDK, perform the following steps:

<ol>
<li>Ensure that the Premake4 executable is in your path.</li>
<li>Open a command line and go to the directory where you have unpacked the SDK.</li>
<li>Run the command <tt>premake4 \a plat</tt>, where \a plat is the Premake4 command for your build system of choice.</li>
<li>Use the generated build files, using your preferred build environment, to build the libraries.</li>
</ol>

This process will generate the static libraries for all of the libraries that need compiling (some libraries, like GLM, are pure header libraries).

\note Neither the GNU Makefiles nor the Premake scripts contain an "install" action. The SDK is intended to be used where it is; it is not intended to make any modifications to your system outside of the directory where you placed it.

\section page_build_examples Building the Examples

The SDK comes with a number of pieces of example code. These are useful as reference material when getting started with OpenGL.

To compile the examples, perform the following steps:

<ol>
<li>Ensure that all of the libraries are compiled.</li>
<li>Open a command line and go to the directory where you have unpacked the SDK.</li>
<li>Go to the <tt>examples</tt> directory.</li>
<li>Run the command <tt>premake4 \a plat</tt>, where \a plat is the Premake4 command for your build system of choice.</li>
<li>Use the generated build files, using your preferred build environment.</li>
</ol>

The examples are all intended to be executed in the directories where the executables are generated. Any paths they use are relative to that directory.
**/

/**
\page pg_use Using the SDK

Once you have @ref page_build_libs "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.

\section page_use_premake With Premake

This section assumes that you are familiar with Premake4. You should know how to set up a <tt>premake4.lua</tt> 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 <tt>premake4.lua</tt> in your directory. This file may call other files to generate the solutions and projects, or it may not.

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

<tt>dofile("path/to/GLSDK/links.lua")</tt>

The <tt>path/to/GLSDK</tt> is the path to the location where the SDK resides. It may be relative or absolute, as you see fit. The <tt>links.lua</tt> 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 <tt>require</tt> 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 <tt>project</tt> 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:

\code
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"};
\endcode

To link to the SDK libraries, you use the <tt>UseLibs</tt> function. This is done quite simply:

\code
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"};
\endcode

The line <tt>UseLibs {"glload", "freeglut"}</tt> 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 <tt>\#define</tt>s or other settings will also be provided.

The names of the libraries used with <tt>UseLibs</tt> are as follows:

\li \a glload: GL Load
\li \a glimage: GL Image
\li \a glutil: GL Util
\li \a glmesh: GL Mesh
\li \a glfw: GLFW
\li \a freeglut: FreeGLUT
\li \a glm: GLM

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 <tt>StaticRuntime</tt> flag in Premake4.

\section page_use_native 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.

\subsection page_use_native_glload GL Load Linking

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

\subsection page_use_native_glimage GL Image Linking

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

\subsection page_use_native_glutil GL Util Linking

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

\subsection page_use_native_glmesh GL Mesh Linking

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

\subsection page_use_native_glm GL Mathematics Linking

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

\subsection page_use_native_glfw GLFW Linking

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

\subsection page_use_native_freeglut FreeGLUT Linking

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

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

\li FREEGLUT_STATIC
\li _LIB
\li FREEGLUT_LIB_PRAGMAS=0

\section page_use_other 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):

\li <tt>opengl32.lib</tt>: The basic Windows interface to OpenGL. If you are building a 64-bit application, it still links to <tt>opengl32.lib</tt>
\li <tt>glu32.lib</tt>: An old utility library for OpenGL. Needed by FreeGLUT or older OpenGL applications.
\li <tt>gdi32.lib</tt>: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT.
\li <tt>winmm.lib</tt>: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT.
\li <tt>user32.lib</tt>: 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:

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

/**
\page pg_changelist Changelist

Changes from 0.4.4:
\li Modified how GL Load works, using a code generator from an external project.
\li @ref module_glutil_debug "GL Util's debug system" now has functions to get string names and descriptions for OpenGL errors and framebuffer status codes.
\li Added GL Load Gen to the distribution.

Changes from 0.4.3:
\li GL Load includes OpenGL 4.3 extensions and core functions.
\li Added a @ref module_glutil_font "basic font system" to GL Util.

Changes from 0.3.x:
\li Added a static mesh class to GL Mesh.
\li Added some simple geometry meshes to GL Mesh.

**/