Package org.lwjgl.opengl

Class GL

java.lang.Object
org.lwjgl.opengl.GL
public final class GL extends Object
This class must be used before any OpenGL function is called. It has the following responsibilities:
  • Loads the OpenGL native library into the JVM process.
  • Creates instances of GLCapabilities classes. A GLCapabilities instance contains flags for functionality that is available in an OpenGL context. Internally, it also contains function pointers that are only valid in that specific OpenGL context.
  • Maintains thread-local state for GLCapabilities instances, corresponding to OpenGL contexts that are current in those threads.

Library lifecycle

The OpenGL library is loaded automatically when this class is initialized. Set the Configuration.OPENGL_EXPLICIT_INIT option to override this behavior. Manual loading/unloading can be achieved with the create() and destroy() functions. The name of the library loaded can be overridden with the Configuration.OPENGL_LIBRARY_NAME option. The maximum OpenGL version loaded can be set with the Configuration.OPENGL_MAXVERSION option. This can be useful to ensure that no functionality above a specific version is used during development.

GLCapabilities creation

Instances of GLCapabilities can be created with the createCapabilities() method. An OpenGL context must be current in the current thread before it is called. Calling this method is expensive, so the GLCapabilities instance should be associated with the OpenGL context and reused as necessary.

Thread-local state

Before a function for a given OpenGL context can be called, the corresponding GLCapabilities instance must be passed to the setCapabilities(org.lwjgl.opengl.GLCapabilities) method. The user is also responsible for clearing the current GLCapabilities instance when the context is destroyed or made current in another thread.

Note that the createCapabilities() method implicitly calls setCapabilities(org.lwjgl.opengl.GLCapabilities) with the newly created instance.

  • Method Details

    • create

      public static void create()
      Loads the OpenGL native library, using the default library name.

    • create

      public static void create(String libName)
      Loads the OpenGL native library, using the specified library name.
      Parameters:
      libName - the native library name

    • create

      public static void create(FunctionProvider functionProvider)
      Initializes OpenGL with the specified FunctionProvider. This method can be used to implement custom OpenGL library loading.
      Parameters:
      functionProvider - the provider of OpenGL function addresses

    • destroy

      public static void destroy()
      Unloads the OpenGL native library.

    • getFunctionProvider

      public static @Nullable FunctionProvider getFunctionProvider()
      Returns the FunctionProvider for the OpenGL native library.

    • setCapabilities

      public static void setCapabilities(@Nullable GLCapabilities caps)
      Sets the GLCapabilities of the OpenGL context that is current in the current thread.

      This GLCapabilities instance will be used by any OpenGL call in the current thread, until setCapabilities is called again with a different value.

    • getCapabilities

      public static GLCapabilities getCapabilities()
      Returns the GLCapabilities of the OpenGL context that is current in the current thread.
      Throws:
      IllegalStateException - if setCapabilities(org.lwjgl.opengl.GLCapabilities) has never been called in the current thread or was last called with a null value

    • getCapabilitiesWGL

      public static WGLCapabilities getCapabilitiesWGL()
      Returns the WGL capabilities.

      This method may only be used on Windows.

    • getCapabilitiesGLX

      public static GLXCapabilities getCapabilitiesGLX()
      Returns the GLX capabilities.

      This method may only be used on Linux.

    • createCapabilities

      public static GLCapabilities createCapabilities()
      Creates a new GLCapabilities instance for the OpenGL context that is current in the current thread.

      Depending on the current context, the instance returned may or may not contain the deprecated functionality removed since OpenGL version 3.1.

      This method calls setCapabilities(GLCapabilities) with the new instance before returning.

      Returns:
      the GLCapabilities instance

    • createCapabilities

      public static GLCapabilities createCapabilities(@Nullable IntFunction<PointerBuffer> bufferFactory)
      Creates a new GLCapabilities instance for the OpenGL context that is current in the current thread.

      Depending on the current context, the instance returned may or may not contain the deprecated functionality removed since OpenGL version 3.1.

      This method calls setCapabilities(GLCapabilities) with the new instance before returning.

      Parameters:
      bufferFactory - a function that allocates a PointerBuffer given a size. The buffer must be filled with zeroes. If null, LWJGL will allocate a GC-managed buffer internally.
      Returns:
      the GLCapabilities instance

    • createCapabilities

      public static GLCapabilities createCapabilities(boolean forwardCompatible)
      Creates a new GLCapabilities instance for the OpenGL context that is current in the current thread.

      Depending on the current context, the instance returned may or may not contain the deprecated functionality removed since OpenGL version 3.1. The forwardCompatible flag will force LWJGL to not load the deprecated functions, even if the current context exposes them.

      This method calls setCapabilities(GLCapabilities) with the new instance before returning.

      Parameters:
      forwardCompatible - if true, LWJGL will create forward compatible capabilities
      Returns:
      the GLCapabilities instance

    • createCapabilities

      public static GLCapabilities createCapabilities(boolean forwardCompatible, @Nullable IntFunction<PointerBuffer> bufferFactory)
      Creates a new GLCapabilities instance for the OpenGL context that is current in the current thread.

      Depending on the current context, the instance returned may or may not contain the deprecated functionality removed since OpenGL version 3.1. The forwardCompatible flag will force LWJGL to not load the deprecated functions, even if the current context exposes them.

      This method calls setCapabilities(GLCapabilities) with the new instance before returning.

      Parameters:
      forwardCompatible - if true, LWJGL will create forward compatible capabilities
      bufferFactory - a function that allocates a PointerBuffer given a size. If null, LWJGL will allocate a GC-managed buffer internally.
      Returns:
      the GLCapabilities instance

    • createCapabilitiesWGL

      public static WGLCapabilities createCapabilitiesWGL()
      Creates a WGLCapabilities instance for the context that is current in the current thread.

      This method may only be used on Windows.

    • createCapabilitiesGLX

      public static GLXCapabilities createCapabilitiesGLX(long display)
      Creates a GLXCapabilities instance for the default screen of the specified X connection.

      This method may only be used on Linux.

      Parameters:
      display - the X connection handle (DISPLAY)

    • createCapabilitiesGLX

      public static GLXCapabilities createCapabilitiesGLX(long display, int screen)
      Creates a GLXCapabilities instance for the specified screen of the specified X connection.

      This method may only be used on Linux.

      Parameters:
      display - the X connection handle (DISPLAY)
      screen - the screen index