Difference between revisions of "Getting Started"

From OpenGL.org
Jump to: navigation, search
(Add a french tutorial from "le site du zero".)
(OpenGL 2.0+ and extensions: Major update.)
Line 66: Line 66:
 
For more information on developing OpenGL applications on Mac OS X, see [[Platform specifics: Mac OS X]].
 
For more information on developing OpenGL applications on Mac OS X, see [[Platform specifics: Mac OS X]].
  
== OpenGL 2.0+ and extensions ==
+
== Accessing OpenGL functions ==
  
 
The OpenGL ABI (application binary interface) is frozen to version GL 1.1 on Windows, and GL 1.2 on Linux. This means that you can not link directly to any new function provided by newer versions or by extensions.
 
The OpenGL ABI (application binary interface) is frozen to version GL 1.1 on Windows, and GL 1.2 on Linux. This means that you can not link directly to any new function provided by newer versions or by extensions.
  
So how do you use newer features ? The answer is to get a function pointer '''at runtime'''. The following text describes details for Windows, but it is very similar for Linux, using '''glXGetProcAddress''' instead of '''wglGetProcAddress'''.
+
So how do you use newer features? The answer is to get function pointers for those features (whether extensions or core functions) at runtime.
  
If you will be programming for Windows, typically compilers comes with a standard OpenGL 1.1 <code>.h</code> and <code>.lib</code>.
+
{{note|The following shows how to do this process manually. There are a number of automatic extension loading libraries, and you are encouraged to use them where appropriate. They will be able to do the same thing as the following, but with less code that you need to write.}}
  
'''Microsoft will never update gl.h and opengl32.lib''' that comes with their compiler. It hasn't been updated since 1995. Basically, the solution is to use glext.h and wglext.h (wglext.h is for Windows only) which define all the GL 1.2, 1.3, 1.4, 1.5, 2.0, 2.1 and above tokens and functions. Keep reading.
+
If you will be programming for Windows, typically compilers comes with a standard OpenGL 1.1 header (gl.h) and static library (opengl32.lib). To gain access to more recent versions or extension functions, you will need to use glext.h and either wglext.h (for windows) or glxext.h (for linux). These define function pointers for all extensions and versions of OpenGL 1.2 and above.
  
Also, for other compilers for Windows, the same applies : gl.h and opengl32.a is limited to GL 1.1.<br>
+
Download glext.h and wglext.h/glxext.h from [http://www.opengl.org/registry/ The Extensions Registry]. You can put these files directly under the compiler's "GL" folder, or you can put them in some other folder that will be in your project's include path. As long as you can find them. The example code will assume that they are in the "GL" folder.
For Linux and others, you might want to borrow the same idea (getting function pointers for the GL functions)
+
  
To access higher OpenGL functions, you would have to get the function pointers.<br>
+
<source lang="cpp">
For example, in C or C++, this is what you would do
+
include <GL/gl.h>
 +
include <GL/glext.h>
 +
include <GL/wglext.h>
  
'''PS : The info here applies also to GL 3.0'''
+
PFNGLACTIVETEXTUREPROC glActiveTexture;    //Declare an OpenGL function pointer in a .cpp file
 +
</source>
  
Download <code>glext.h</code> and <code>wglext.h</code> from [http://www.opengl.org/registry/ The Extensions Registry]
+
PFNGLACTIVETEXTUREPROC is a typedef defined in glext.h that represents a function pointer to this particular OpenGL function. Every OpenGL core function (in a version 1.2 or greater) and every OpenGL extension function has a typedef. They all begin with PFN, followed by the function name in ALL CAPS, followed by PROC.
  
Put it in your compiler's GL folder.
+
If you wish to expose this function pointer to other .cpp files, you will need to put the following in a header file that those .cpp files include:
  
<pre>
+
<source lang="cpp">
 +
//Some header file.
 
include <GL/gl.h>
 
include <GL/gl.h>
 
include <GL/glext.h>
 
include <GL/glext.h>
 
include <GL/wglext.h>
 
include <GL/wglext.h>
  
extern PFNGLACTIVETEXTUREPROC glActiveTexture; //Put this in a .h so that you can include the header in all your other .cpp
+
extern PFNGLACTIVETEXTUREPROC glActiveTexture;
PFNGLACTIVETEXTUREPROC glActiveTexture;    //Declare your function pointer in a .cpp file
+
</source>
</pre>
+
 
+
Once you create a GL context, you can use wglGetProcAddress to get a pointer to the function.
+
 
+
glActiveTexture = (PFNGLACTIVETEXTUREPROC) wglGetProcAddress("glActiveTexture");
+
 
+
This would be tedious if you had to do this for all the functions and it is even more work if you want to detect a certain OpenGL API version, then load all the core functions. Then, detect if a certain extension is present, then load all the functions.
+
 
+
There exists a few libraries out there that will get the function pointers for you. All you have to do is create an OpenGL rendering context and call the library's init function. The recent version of GLee doesn't require a call to its init function.
+
 
+
Examples are :
+
*[http://glew.sourceforge.net GLEW - The GL Extension Wrangler Library]
+
*[http://elf-stone.com/glee.php GLEE - GL Easy Extension library]
+
 
+
GLEW is used like this :<br>
+
Step 1. Just before including gl.h, include glew.h<br>
+
Step 2. Just after creating your GL context and making it current, call
+
 
+
  GLenum err=glewInit();
+
  if(err!=GLEW_OK)
+
  {
+
  //problem: glewInit failed, something is seriously wrong
+
  sprintf(ErrorMessage, "Error: %s\n", glewGetErrorString(err));
+
  return -1;
+
  }
+
  
NEW : For GL 3.0, a new header file has been released as mentioned here
+
After creating an OpenGL context, and ''only after creating an OpenGL context'', you may use wglGetProcAddress (or the glx equivalent) to get the function pointer.
http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=showflat&Number=256858#Post256858
+
  
http://www.opengl.org/registry/api/gl3.h
+
<source lang="cpp">
 +
glActiveTexture = (PFNGLACTIVETEXTUREPROC)wglGetProcAddress("glActiveTexture");
 +
</source>
  
It includes all the new tokens and functions and the old stuff has been removed.
+
This must be done for each function you intend to use that is not a core OpenGL 1.1 function. Or you can use an extension loading library and not have to worry about it.
  
 
== OpenGL 3.0 and Above ==
 
== OpenGL 3.0 and Above ==

Revision as of 04:49, 9 April 2011

So you want to take advantage of the power of the OpenGL API? If you are visiting this page because a game or software implements the OpenGL API, you need to install the appropriate graphic driver which enables usage of the functionality provided.

To program using the OpenGL API, you need the driver and the development package (depends on platform and programming language). More platform-specific details are described in the sections below.

FAQ

Besides the OpenGL Wiki FAQ linked above, there is an older FAQ

Windows

If you are running Windows 98/Me/NT/2000/XP/2003/Vista, the OpenGL library has already been installed on your system.

Remember that GL is a system component on Windows. DO NOT modify or copy OpenGL32.dll from one OS to another. The filename is OpenGL32.dll and is either in WINDOWS\SYSTEM, WINNT\SYSTEM32 or WINDOWS\SYSTEM32. This also means that you do not have to ship a copy of the library with your application since it will already be available on the system.

The standard Windows OpenGL32.dll library alone will not provide you with hardware acceleration for OpenGL. In order to get hardware acceleration, you will need to install the latest drivers for your graphics card. The second reason to install new drivers is to have the latest version of GL on your system (the max version supported by your GPU):

Some sites also distribute beta versions of graphics drivers, which may give you access to bug fixes or new functionality before an official driver release from the manufacturer:

Without drivers, you will default to a software version of OpenGL 1.1 (on Win98, ME, and 2000), a Direct3D wrapper that supports OpenGL 1.1 (WinXP), or a Direct3D wrapper that supports OpenGL 1.1 (Windows Vista and Windows 7). None of these options are particularly fast, so installing drivers is always a good idea.

Other libraries like GLUT, freeGLUT, QT, etc are not part of the OS. These should be downloaded from the net. GLUT and OpenGL Utility Libraries

64 bits Windows versions

If you are running a 64 bit version of Windows, you might be wondering if there is a OpenGL64.dll file. The answer is no, there isn't. On all versions of Windows, Windows\System32 contains all the 64 bit DLLs. It contains the OpenGL32.dll which is actually a 64 bit dll.

For 32 bit programs, Windows detects the exe as a 32 bit program and instead of using System32 files, it uses Windows\SysWOW64 which actually contains the 32 bit DLLs. WOW means Windows On Windows which is a backwards-compatibility layer.

To find your Windows' System32 directory, go to: Start, Run... and type in %WINDIR%\System32. The system will redirect you to the default System32 directory automatically; this is also true for the 32 bits versions of Windows.

Linux

Graphics on Linux is almost exclusively implemented using the X windows system. Supporting OpenGL on Linux involves using GLX extensions to the X Server. There is a standard Application Binary Interface defined for OpenGL on Linux that gives application compatability for OpenGL for a range of drivers. In addition the Direct Rendering Infrastucture (DRI) is a driver framework that allows drivers to be written and interoperate within a standard framework to easily support hardware acceleration, the DRI is included in of XFree86 4.0 but may need a card specific driver to be configured after installation. These days, XFree86 has been rejected in favor of XOrg due to the change in the license of XFree86, so many developers left Xfree86 and joined the XOrg group. Popular Linux distros come with XOrg now. Developers

Vendors have different approaches to drivers on Linux, some support Open Source efforts using the DRI, and others support closed source frameworks but all methods support the standard ABI that will allow correctly written OpenGL applications to run on Linux.

For more information on developing OpenGL applications on Linux, see Platform specifics: Linux

Linux comes with Mesa libraries, which implements the OpenGL API as a software rasterizer. Most Linux distros don't come with hardware acceleration. Some Linux distributions may include support for hardware acceleration. Also, some GPUs have Open Source drivers developed by the community even though a close source driver may be available from the manufacturer.

Mac OS X

All versions of Mac OS X ship with OpenGL runtime libraries pre-installed. Users who want to run OpenGL applications do not need to install or configure anything.

Unlike other platforms, where the Operating System and OpenGL implementations are often updated separately, OpenGL updates are included as part of Mac OS X system updates. To obtain the latest OpenGL on Mac OS X, users should upgrade to the latest OS release, which can be found at Apple.com.

For developers, a default installation of Mac OS X does not include any OpenGL headers, nor does it include other necessary development tools. These are installed by a separate developer tools package called Xcode. This installer includes the OpenGL headers, compilers (gcc), debuggers (gdb), Apple's Xcode IDE, and a number of performance tools useful for OpenGL application development.

For more information on developing OpenGL applications on Mac OS X, see Platform specifics: Mac OS X.

Accessing OpenGL functions

The OpenGL ABI (application binary interface) is frozen to version GL 1.1 on Windows, and GL 1.2 on Linux. This means that you can not link directly to any new function provided by newer versions or by extensions.

So how do you use newer features? The answer is to get function pointers for those features (whether extensions or core functions) at runtime.

Note: The following shows how to do this process manually. There are a number of automatic extension loading libraries, and you are encouraged to use them where appropriate. They will be able to do the same thing as the following, but with less code that you need to write.

If you will be programming for Windows, typically compilers comes with a standard OpenGL 1.1 header (gl.h) and static library (opengl32.lib). To gain access to more recent versions or extension functions, you will need to use glext.h and either wglext.h (for windows) or glxext.h (for linux). These define function pointers for all extensions and versions of OpenGL 1.2 and above.

Download glext.h and wglext.h/glxext.h from The Extensions Registry. You can put these files directly under the compiler's "GL" folder, or you can put them in some other folder that will be in your project's include path. As long as you can find them. The example code will assume that they are in the "GL" folder.

include <GL/gl.h>
include <GL/glext.h>
include <GL/wglext.h>
 
PFNGLACTIVETEXTUREPROC glActiveTexture;    //Declare an OpenGL function pointer in a .cpp file

PFNGLACTIVETEXTUREPROC is a typedef defined in glext.h that represents a function pointer to this particular OpenGL function. Every OpenGL core function (in a version 1.2 or greater) and every OpenGL extension function has a typedef. They all begin with PFN, followed by the function name in ALL CAPS, followed by PROC.

If you wish to expose this function pointer to other .cpp files, you will need to put the following in a header file that those .cpp files include:

//Some header file.
include <GL/gl.h>
include <GL/glext.h>
include <GL/wglext.h>
 
extern PFNGLACTIVETEXTUREPROC glActiveTexture;

After creating an OpenGL context, and only after creating an OpenGL context, you may use wglGetProcAddress (or the glx equivalent) to get the function pointer.

glActiveTexture = (PFNGLACTIVETEXTUREPROC)wglGetProcAddress("glActiveTexture");

This must be done for each function you intend to use that is not a core OpenGL 1.1 function. Or you can use an extension loading library and not have to worry about it.

OpenGL 3.0 and Above

OpenGL 3.0 adds many features to the core of OpenGL. It also brings with it a deprecation model that previous versions of OpenGL did not have. Before OpenGL 3.0, anything that became core had to remain in the specification permanently. The deprecation model allows OpenGL versions to announce that certain features may be removed from the core in later versions.

To support backwards compatibility, that is, to not break existing programs, a new context creation model was introduced. The old context creation model can only create OpenGL versions 2.1 or lower. Thus, the only way to use 3.0 contexts is to create them with the new API.

Part of this new API is a specification of exactly what version of OpenGL you want. So if you ask for a GL 3.1 context, you are telling the system that you expect that any entrypoints version 3.1 removed from earlier versions will not be available, and that any entrypoints 3.1 added to new versions will be available. The new API can fail if the implementation simply does not implement that version of OpenGL.

See also the page OpenGL 3.0 and beyond, creating a context for instructions.

OpenGL 3.2

API & GLSL specifications

How to make your first OpenGL Program

The first thing to do is chose a programming language. It could be C, C++, C#, Visual Basic, Pascal, Perl, Java, Ada, x86 assembly, etc. As long as a language has an OpenGL binding for your chosen language, you may use it.

The second thing is to chose a compiler. It could be MS Visual C++, Code::Blocks, Delphi, Masm, etc. Remember that OpenGL is an API, so as long as you have the language bindings for your compiler, you can do OpenGL programming.

Typically, a compiler comes with the binding files. For example, if you have a C++ compiler, it will come with gl.h and opengl32.lib. It may even come with glu.h and glu32.lib, glut.h and glut32.lib.

If you don't have your binding files, you will need to figure out where to download them from. Microsoft releases their Windows Platform SDK which contains these files and most likely you don't need it because your compiler came with the files.

You might want to use SDL, GLUT, freeGLUT, or some other wrapper that takes care of creating a GL window for you and destroying for you. It makes it easier for someone who just wants to learn the OpenGL API syntax.

Assuming you know how to program in your language of choice, now all you need is to learn OpenGL. There are many online tutorials. Just search for opengl+tutorial in your favorite search engine or visit some of the tutorials listed here.

OpenGL Viewers

These are programs that you install and run, and they give you information specific to the OpenGL API your system implements, like the version offered by your system, the vendor, the renderer, the extension list, supported viewport size, line size, point size, plus many other details. Some might include a benchmark. Some are standalone benchmarks.

Tutorials and How To Guides

User contributed tutorials and getting started guides

Deferred Shading Tutorials

Development Tools

  • gDEBugger - OpenGL, OpenGL ES and OpenCL Debugger, Profiler and Memory Analyzer For Windows, Linux, Mac OS X and iPhone

See Also

External Links