git.sesse.net Git - casparcg/blob - GLee5_4/readme.txt

   1 GLee\r
   2 GL Easy Extension Library\r
   3 Version 5.4\r
   4 \r
   5 By Ben Woodhouse\r
   6 http://elf-stone.com\r
   7 \r
   8 \r
   9 LICENSE\r
  10 \r
  11 Copyright (c)2009  Ben Woodhouse  All rights reserved.\r
  12 \r
  13 Redistribution and use in source and binary forms, with or without\r
  14 modification, are permitted provided that the following conditions are \r
  15 met:\r
  16 1. Redistributions of source code must retain the above copyright\r
  17 notice, this list of conditions and the following disclaimer as\r
  18 the first lines of this file unmodified.\r
  19 2. Redistributions in binary form must reproduce the above copyright\r
  20 notice, this list of conditions and the following disclaimer in the\r
  21 documentation and/or other materials provided with the distribution.\r
  22 \r
  23 THIS SOFTWARE IS PROVIDED BY BEN WOODHOUSE ``AS IS'' AND ANY EXPRESS OR\r
  24 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES\r
  25 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\r
  26 IN NO EVENT SHALL BEN WOODHOUSE BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  27 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT\r
  28 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
  29 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
  30 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
  31 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF\r
  32 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  33 \r
  34 \r
  35 \r
  36 CONTACT\r
  37 \r
  38 Send any general questions, bug reports etc to me (Ben Woodhouse):\r
  39   bw [at] elf-stone.com\r
  40 \r
  41 Questions about the D port for GLee should go to Joel Anderson: \r
  42   anderson [at] badmama.com.au\r
  43   \r
  44 Questions about GLee on OS X should go to Tristam MacDonald\r
  45   swiftcoder [at] gmail.com\r
  46   \r
  47 \r
  48 \r
  49 INTRODUCTION\r
  50 \r
  51 GLee provides a simple interface for using extensions and core OpenGL \r
  52 functionality beyond OpenGL version 1.1, and automates the otherwise tedious \r
  53 process of linking function pointers. GLee works with both C and C++ \r
  54 compilers.\r
  55 \r
  56 Because the code is automatically generated, the latest extensions can \r
  57 be included rapidly in new versions. Currently there is support \r
  58 for OpenGL up to 3.0 and almost all registered extensions. For a complete \r
  59 list of extensions, please see the accompanying extensionList.txt file. \r
  60 \r
  61 For extension specifications, please visit: \r
  62 \r
  63    http://www.opengl.org/registry/\r
  64 \r
  65 \r
  66 CREDITS\r
  67 \r
  68 Tristam MacDonald for adding OS-X compatibility.\r
  69 \r
  70 Martin Büchler (LousyPhreak on the GameDev.net forums) for \r
  71 a huge amount of testing, tweaking, suggestions and advice to get GLee to \r
  72 work properly with Linux. \r
  73 \r
  74 Daniel Jo (Ostsol on the OpenGL.org forums) for helping to get  \r
  75 GLEE 2.1 working with the OGLSL extensions (ARB_shader_objects, \r
  76 ARB_vertex_shader and ARB_fragment_shader). \r
  77 \r
  78 Joel Anderson for his for his D port of GLee 3.0\r
  79 \r
  80 Jacques Beaurain for pointing out a potential access violation in \r
  81 __GLeeGetExtensions. \r
  82 \r
  83 \r
  84 WHAT'S NEW IN GLEE 5.0\r
  85 \r
  86 GLeeGen, the program that generates the code for the GLee library, has been\r
  87 rewritten to support parsing of extension specifications. As a result, GLee 5.0 and upwards support \r
  88 all extensions for which there is a specification, regardless of that \r
  89 extension's inclusion in glext.h, wglext.h or glxext.h. \r
  90 \r
  91 GLee 5.0 adds support for forced extension loading through the \r
  92 GLeeForceLink function. This makes it possible to force the linking of \r
  93 extension functions (or core functions) which are not reported by the video driver. \r
  94 \r
  95 GLee now supports lazy loading of extensions, meaning it is no longer \r
  96 necessary to call GLeeInit() at initialisation time. \r
  97 \r
  98 \r
  99 \r
 100 HOW TO INSTALL \r
 101 \r
 102 MSVC 2003 binary version\r
 103 \r
 104   1. Copy GLee.lib to your visual C++ lib directory \r
 105   (eg C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\Lib)\r
 106 \r
 107   2. Copy GLee.h to your visual C++ include\GL directory \r
 108   (eg C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\include\gl)\r
 109   \r
 110 \r
 111 Linux binary version (GLee-*-bin.tar.gz)\r
 112   (Installation has to be done as root)\r
 113 \r
 114   1. unpack GLee-*-bin.tar.gz\r
 115   (tar -xzf GLee-2.0-bin.tar.gz)\r
 116 \r
 117   2. Install with the inst script\r
 118   (cd glee && ./inst)\r
 119 \r
 120 Linux source version (GLee-*-src.tar.gz)\r
 121   1. unpack GLee-*-src.tar.gz\r
 122   (tar -xzf GLee-2.0-src.tar.gz)\r
 123 \r
 124   2. cd to "glee" and run the gnu build chain\r
 125   (cd glee && ./configure && make)\r
 126 \r
 127   3. Become root (password needed)\r
 128   (su)\r
 129 \r
 130   4. Install the lib\r
 131   (make install)\r
 132   \r
 133 \r
 134 \r
 135 HOW TO USE\r
 136 \r
 137 If you're using the binary version then you'll need to link to \r
 138 glee.lib and #include <gl\glee.h> in your project. Otherwise, \r
 139 just add glee.h and glee.c in your project and #include "glee.h".\r
 140 You can also build the library yourself using glee.c and glee.h. \r
 141 \r
 142 From this point onwards, you should have access to all OpenGL \r
 143 extensions and core functionality. \r
 144 \r
 145 You can query the availability of an extension like this:\r
 146 \r
 147 if (GLEE_ARB_point_parameters)\r
 148 {\r
 149    //GL_ARB_point_parameters is supported\r
 150    glPointParameterfARB(...);\r
 151 }\r
 152 \r
 153 WGL extensions have a GLEE_WGL_ prefix. For example, \r
 154 GLEE_WGL_ARB_pbuffer. GLX extensions work in a similar way. \r
 155 \r
 156 You can also query the OpenGL version:\r
 157 if (GLEE_VERSION_1_3)\r
 158 {\r
 159   //OpenGL 1.3 is supported \r
 160   glLoadTransposeMatrixf(...) ; \r
 161   ...\r
 162 }\r
 163 \r
 164 \r
 165 \r
 166 ERROR CHECKING\r
 167 \r
 168 Optionally, you can add a call to GLeeInit() after your OpenGL \r
 169 initialisation code, however this is no longer required as of \r
 170 GLee 5.0. GLeeInit returns a boolean value to indicate success\r
 171 or failure. \r
 172 \r
 173 If GLeeInit returns false you can get more detailed error \r
 174 information by calling GLeeGetErrorString(). This returns a pointer \r
 175 to a string which contains error description(s). \r
 176 \r
 177 At any time you can call GLeeGetExtStrGL() or GLeeGetExtStrWGL() \r
 178 (win32) or GLeeGetExtStrGLX() (linux) to retrieve a pointer to the \r
 179 corresponding extension list string.  \r
 180 \r
 181 \r
 182 \r
 183 FORCED EXTENSION SUPPORT\r
 184 \r
 185 By default, only those extensions reported by OpenGL's \r
 186 glGetString(GL_EXTENSIONS) are loaded by GLeeInit(). Likewise, \r
 187 only core functions whose version doesn't exceed the version number \r
 188 returned by glGetString(GL_VERSION) are loaded.\r
 189 \r
 190 However, GLee 5.0 and above can load additional extension and core \r
 191 functions using the GLeeForceLink function:\r
 192 \r
 193         GLint GLeeForceLink(const char * extensionName)\r
 194 \r
 195 For example, GLeeForceLink("GL_ARB_point_parameters") will attempt to \r
 196 load the ARB_point_parameters function. \r
 197 \r
 198 For core functions, you can use the GL version string for the version \r
 199 you wish to initialise. For example, GLeeForceLink( "GL_VERSION_2_0" ) \r
 200 will attempt to initialise OpenGL 2.0 core functions. \r
 201         \r
 202 Return Value:\r
 203   GLEE_LINK_COMPLETE is returned if all functions were \r
 204   successfully linked.\r
 205 \r
 206   GLEE_LINK_PARTIAL is returned if only some functions were \r
 207   linked successfully.\r
 208   \r
 209   GLEE_LINK_FAIL is returned if no functions could be linked\r
 210   successfully. \r
 211   \r
 212 Functions which could not be linked will be set to NULL. \r
 213 \r
 214 A successful link does not guarantee that a function will work \r
 215 correctly. If you want to be safe, only use extensions which are\r
 216 reported by the driver. \r
 217 \r
 218 \r
 219 \r
 220 LINUX NOTES - by LousyPhreak\r
 221 \r
 222 The binary version was compiled with gcc 3.3 and was also tested \r
 223 with gcc 3.2, but if you still have gcc 2.x you need the source \r
 224 version. If you don't know which version you have on your system just \r
 225 look at the output of 'gcc --version'.\r
 226 \r
 227 You should be using the NVIDIA headers if you have the NVIDIA drivers\r
 228 installed, and the MESA headers otherwise.\r
 229 \r
 230 One more note:\r
 231 The binary version might complain about missing glXGetProcAddressARB\r
 232 on the linker stage, but if you get this error, use the source \r
 233 version and email me (lousyphreak [at] gmx.at).\r
 234 \r
 235 Compiling on linux:\r
 236 You just need to replace the linking of libGL by libGLee:\r
 237 gcc main.cpp whatever.cpp -lGLee -o myproject\r
 238 \r
 239 Everything else should be the same as on windows.\r
 240 \r
 241 \r
 242 \r
 243 NOTES ON THE GLEE 3.0 D PORT FOR WIN32 - by Joel Anderson\r
 244 \r
 245 1) Put the GLee.lib in the lib folder (ie C:\dmd\lib)\r
 246 2) Put glee.d and glConstants.d in the include folder (ie create c:\glee \r
 247 and use the -IC:\glee on the compiler.) \r
 248 3) The D code is pretty much the same as the C code but you need to specify:\r
 249 \r
 250 import glee; //Instead of #include "glee.h"\r
 251 \r
 252 Notes\r
 253 - The GLee.lib was built using dmc.  I did try the one that comes with the \r
 254 C version, but that doesn't work with D. You can compile the lib yourself \r
 255 using cbuild\go.bat\r
 256 - I haven't tested everything.\r
 257 \r
 258 You can contact me (Joel Anderson) at anderson@badmama.com.au\r
 259 \r
 260 (21/01/2004) - AU\r
 261 \r
 262 \r
 263 CHANGES\r
 264 \r
 265 5.4   : Added 5 new extensions : \r
 266             GL_EXT_texture_swizzle\r
 267             GL_NV_explicit_multisample\r
 268             GL_NV_transform_feedback2\r
 269             WGL_NV_gpu_affinity\r
 270             GLX_ARB_create_context\r
 271             \r
 272         Removed some duplicate extensions:\r
 273             GL_NV_geometry_program4 (use GL_NV_gpu_program4)\r
 274             GL_NV_vertex_program4   (use GL_NV_gpu_program4)\r
 275             GL_NV_fragment_program4 (use GL_NV_gpu_program4)\r
 276             WGL_NV_video_out        (use WGL_NV_video_output)\r
 277             \r
 278         Fixed GL_NV_gpu_program4 by merging with GL_NV_geometry_program4, \r
 279         GL_NV_vertex_program4 and GL_NV_fragment_program4. \r
 280         \r
 281         Added support for multiple extensions including the same functions, so \r
 282         GL_EXT_geometry_shader4 and GL_NV_geometry_program4 can coexist without\r
 283         compile errors.  \r
 284           \r
 285         Fixed GL_EXT_geometry_shader4 so it no longer has missing functions and constants. \r
 286         These were excluded previously to avoid clashes with GL_NV_vertex_program4, which \r
 287         included a bunch of functions with the same names.\r
 288         \r
 289         Various GLeeGen/GLeeXMLGen fixes, mainly to fix issues with NVidia extensions, most\r
 290         notably:        \r
 291           Added support for overriding extension spec files so we can manually fix \r
 292           buggy specs which don't follow the standard (like GL_NV_gpu_program4).\r
 293             \r
 294 \r
 295 Reworked GLeeGen and GLeeXMLGen to allow overriding of \r
 296 \r
 297 5.33  : Fixed some GCC warnings \r
 298         Fixed some OS-X warnings\r
 299         Fixed an issue in __GLeeGetExtensions which could cause two\r
 300           extensions to go missing on some platforms\r
 301 \r
 302 5.32  : Fixed a potential access violation in __GLeeGetExtensions\r
 303 \r
 304 5.31  : Fixed GLX compile error\r
 305 \r
 306 5.3   : OpenGL 3.0 support\r
 307 \r
 308 5.21  : Nvidia geometry shader extensions \r
 309 \r
 310 5.2   : OS-X support\r
 311 \r
 312 5.1   : Fixed some ansi-C compatibility issues. \r
 313                 New GLeeGen version\r
 314                 Added 5 new GL extensions and 1 new WGL extension. \r
 315 \r
 316 5.04  : Added the latest extensions\r
 317 \r
 318 5.03  : Some minor compatibility fixes. \r
 319 \r
 320                 Malloc.h no longer used. \r
 321                 \r
 322                 GLee no longer fails if platform-specific (GLX or WGL) extensions \r
 323                 could not be loaded (a problem with some cards apparently).\r
 324 \r
 325 5.02  : Changed extension querying variable system. Removed GLEE_ENABLED() \r
 326         extension checking macro introduced in 5.00, since it is no longer \r
 327         needed\r
 328 \r
 329 5.01  : Fixed GLX_SGIX_HYPERPIPE bug\r
 330 \r
 331 5.00  : Rewrote GLeeGen to parse extension specs\r
 332         \r
 333         Added lazy loading for extensions\r
 334         \r
 335         Added experimental support\r
 336 \r
 337 4.00  : Updated using extensions from glext.h version 26, wglext.h version 6, \r
 338         and glxext.h version 10. OpenGL 2.0 is now supported. \r
 339 \r
 340 3.05  : Updated with glExt.h version 23 extensions. \r
 341 \r
 342 3.04  : Updated with glExt.h version 22 extensions. \r
 343 \r
 344 3.03  : Another linux compatibility bug fixed\r
 345 \r
 346 3.02  : GLX typedef bug fixed\r
 347 \r
 348 3.01  : Minor linux compatibility bugs fixed\r
 349 \r
 350 3.0   : Removed STL and other C++ specific features to make GLee \r
 351         compatible with C compilers \r
 352         \r
 353         Added a number of WGL extensions that had previously been\r
 354         excluded due to a bug with GLeeGen (now fixed)\r
 355 \r
 356 2.21  : Fixed VC6 compilation bug\r
 357 \r
 358 2.2   : Added full OpenGL 1.5 support\r
 359 \r
 360 2.1   : Added the OpenGL shading language extensions: \r
 361         ARB_shader_objects, ARB_vertex_shader and ARB_fragment_shader. \r
 362                 \r
 363 2.01  : Fixed missing description comment in header\r
 364         Fixed include guard\r
 365 \r
 366 2.0   : Removed dependency on glext.h and wglext.h\r
 367         Added cross-platform code for support with linux      \r
 368         Fixed potential stability problems \r
 369 \r
 370 1.2   : Made library compatible with VC7 and VC7.1\r
 371 \r
 372 1.12  : Cleaned up some commenting errors in GLeeGen\r
 373 \r
 374 1.11  : Added functions to get WGL and GL extension strings.\r
 375         Fixed minor formatting errors caused by a bug in GLeeGen (now fixed)\r
 376 \r
 377 1.1   : Added detailed error checking. \r
 378         Fixed possible buffer overrun issue \r
 379 \r
 380 1.01  : GLeeInit no longer requires a device context handle.