
/**
\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:

<ul>
<li>@ref module_glload "GL Load": Used to gain access to OpenGL's functions.</li>
<li>@ref module_glimg "GL Image": Used for loading image files into memory and into OpenGL textures.</li>
<li>@ref module_glutil "GL Utility": Provides a variety of generally useful functionality. It a wide variety of features including:
<ul>
<li>@ref module_glutil_font "Very simple text drawing services"</li>
<li>@ref module_glutil_matrixstack "A matrix stack"</li>
<li>@ref module_glutil_poles "Mouse-based camera and object manipulation"</li>
</ul></li>
<li>@ref module_glmesh "GL Mesh": A mechanism for rendering mesh data. It provides an @ref module_glmesh_draw "immediate mode interface" that can replace glBegin/glEnd, as well as a @ref module_glmesh_mesh "mesh class". It also provides a number of @ref module_glmesh_mesh_generator "sample mesh objects", for doing simple tasks.</li>
<li>@ref module_glm "OpenGL Mathematics": Provides useful math classes and functions for OpenGL, using a GLSL-like syntax.</li>
<li>@ref module_glfw "GLFW": A tool for creating and managing an OpenGL window. It can be used to handle input.</li>
<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.</li>
<li>@ref module_boost "Boost": A C++ utility library distributed with and used by the SDK.</li>
<li>@ref module_glloadgen "OpenGL Loader Generator": A command-line script tool for generating OpenGL loader code.</li>
</ul>

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, follow the @subpage pg_use "instructions for using the SDK" to use it.

\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> or the <a href="https://sourceforge.net/p/glsdk/bugs/">SourceForge issue tracker</a>. Questions or other inquiries can be directed to the <a href="https://sourceforge.net/p/glsdk/discussion/">SDK's discussion forum</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 Mesh loading: A library for loading files into GL Mesh 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 beyond the most basic font library, as there's no way anyone should be expected to reinvent that wheel. But outside of something that essential, 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
\li \a 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 <tt>UseLibs</tt> with "glmesh", you will also get GL Load and boost (because it needs that too).

Only \em 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 <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

\subsection page_use_native_boost 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 <tt>"boost"</tt>.

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

\li BOOST_ALL_NO_LIB

\subsection page_use_native_deps 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:

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

\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:
<ul>
<li>Added Boost to the distribution, as well as support for user-provided Boost.</li>
<li>Added [GL Load Gen](@ref module_glloadgen) to the distribution.</li>
<li> From @ref module_glload "GL Load"
<ul>
<li>GL Load is now generated using glLoadGen's generation system. This should not impact your use of the system.</li>
<li>BREAKING CHANGE: GL Load's C++ API now doesn't need to prefix its enums with GL_.</li>
<li>BREAKING CHANGE: Several of GL Load's headers have changed.</li>
</ul>
</li>
<li> From @ref module_glmesh "GL Mesh"
<ul>
<li>splits the `glmesh::Draw::Attrib` functions into their own utility class, so that the interface can be used in the new glmesh::CpuDataWriter. This class is used for creating vertex arrays on the CPU, to be used in later uploads to the GPU.</li>
<li>glmesh::VertexFormat::Enable class now can use ARB_vertex_attrib_binding.</li>
<li>glmesh::VertexFormat has functions to bind attributes, either all of them or individually. This makes it easy to use it with a VAO; you bind the VAO, call glmesh::VertexFormat::BindAttributes, and you're done. There is also glmesh::VertexFormat::BindAttribFormats for ARB_vertex_attrib_binding usage</li>
<li>A number of \ref module_glmesh_mesh_generator "mesh generators"</li>
</ul>
</li>
<li> From @ref module_glutil "GL Util"
<ul>
<li>@ref module_glutil_debug "The Debug system" now has functions to get string names and descriptions for OpenGL errors and framebuffer status codes.</li>
<li>[The program compiling/linking helpers](@ref module_glutil_program) now include RAII-style objects for holding shaders and programs.
</ul>
</li>
</ul>

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.

**/

