# Unofficial OpenGL SDK / docs / glsdk.doxy

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295  /** \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 MIT License. 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 examples directory. \section mainpage_install Installation and Use Installation of the SDK is simple. Download the most recent version of the distribution 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 Bitbucket issue tracker or the SourceForge issue tracker. Questions or other inquiries can be directed to the SDK's discussion forum. 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 absolutely necessary. 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 download the distribution 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 Premake utility, 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 Makefile, which you would then use GNU Make on as normal. If you use Visual Studio, Premake generates .sln and .vcproj 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 Premake documentation 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:
1. Ensure that the Premake4 executable is in your path.
2. Open a command line and go to the directory where you have unpacked the SDK.
3. Run the command premake4 \a plat, where \a plat is the Premake4 command for your build system of choice.
4. Use the generated build files, using your preferred build environment, to build the libraries.
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:
1. Ensure that all of the libraries are compiled.
2. Open a command line and go to the directory where you have unpacked the SDK.
3. Go to the examples directory.
4. Run the command premake4 \a plat, where \a plat is the Premake4 command for your build system of choice.
5. Use the generated build files, using your preferred build environment.
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 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: \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 UseLibs 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 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 \#defines or other settings will also be provided. The names of the libraries used with UseLibs 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 StaticRuntime 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 "glload/include". The libraries are in the "glload/lib" directory. The debug and release libraries are called "glloadD" and "glload", respectively. \subsection page_use_native_glimage 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. \subsection page_use_native_glutil 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. \subsection page_use_native_glmesh 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. \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 "glm" 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 "glfw/include". The libraries are in the "glfw/library" directory. The debug and release libraries are called "glfwD" and "glfw", respectively. \subsection page_use_native_freeglut 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: \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 opengl32.lib: The basic Windows interface to OpenGL. If you are building a 64-bit application, it still links to opengl32.lib \li glu32.lib: An old utility library for OpenGL. Needed by FreeGLUT or older OpenGL applications. \li gdi32.lib: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT. \li winmm.lib: Needed by FreeGLUT. You do not have to link to this if you are not using FreeGLUT. \li 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: \li libGL: OpenGL's interface on Linux. \li libGLU: An old utility library for OpenGL. Needed by FreeGLUT and GLFW on Linux. \li Xrandr: 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. **/