Manages GL contexts. Before any rendering is done by a LWJGL system, a call should be made to GLContext.useContext() with a context. This will ensure that GLContext has an accurate reflection of the current context's capabilities and function pointers.
This class is thread-safe in the sense that multiple threads can safely call all public methods. The class is also thread-aware in the sense that it tracks a per-thread current context (including capabilities and function pointers). That way, multiple threads can have multiple contexts current and render to them concurrently.
| Modifier and Type | Class and Description |
|---|---|
| private static class |
| Modifier and Type | Field and Description |
|---|---|
| private static final Map | capability_cache
The weak mapping from context Object instances to ContextCapabilities. |
| private static final ThreadLocal | current_capabilities
Maps threads to their current context's ContextCapabilities, if any |
| private static boolean | |
| private static GLContext. | fast_path_cache
The getCapabilities() method is a potential hot spot in any LWJGL application, since it is needed for context capability discovery (e.g. is OpenGL 2.0 supported?), and for the function pointers of gl functions. |
| private static int | gl_ref_count
Reference count of the native opengl implementation library |
| private static final ThreadLocal | thread_cache_entries
Simple lock-free cache of CapabilitesEntryCache to avoid allocating more than one cache entry per thread |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public static ContextCapabilities | |
| pack-priv static ContextCapabilities | Returns: the capabilities instancethe context object context)Returns the capabilities instance associated with the specified context object. |
| private static ContextCapabilities | |
| pack-priv static long | Returns: the function pointer addressthe function name aliases. aliases)Helper method to get a pointer to a named function with aliases in the OpenGL library. |
| pack-priv static long | getFunctionAddress(String name)
Helper method to get a pointer to a named function in the OpenGL library. |
| pack-priv static long | getPlatformSpecificFunctionAddress(String function_prefix, String[] os_prefixes, String[] os_function_prefixes, String function)
Helper method to get a pointer to a named function in the OpenGL library with a name dependent on the current platform |
| pack-priv static int | Returns: the context profile mask, will be 0 for any version < 3.2the Set to fill with the available extension names supported_extensions)Determine which extensions are available and returns the context profile mask. |
| private static ContextCapabilities | |
| pack-priv static void | initNativeStubs(final Class<?> extension_class, Set<E> supported_extensions, String ext_name)
Helper method to ContextCapabilities. |
| public static synchronized void | |
| private static native long | |
| private static native void | |
| private static native void | |
| pack-priv static native void | |
| pack-priv static void | Returns: The current capabilities instance.Set the current capabilities instance. |
| public static synchronized void | unloadOpenGLLibrary()
The OpenGL library reference count is decremented, and if it reaches 0, the library is unloaded. |
| public static synchronized void | useContext(Object
The context object, which uniquely identifies a GL context. If context is null, the native stubs are
unloaded. context)Makes a GL context the current LWJGL context by loading GL function pointers. |
| public static synchronized void | useContext(Object
The context object, which uniquely identifies a GL context. If context is null, the native stubs are
unloaded. context, boolean If the context is a forward compatible context (does not expose deprecated functionality, see XGL_ARB_create_context) forwardCompatible)Makes a GL context the current LWJGL context by loading GL function pointers. |
| capability_cache | back to summary |
|---|---|
| private static final Map<Object, ContextCapabilities> capability_cache The weak mapping from context Object instances to ContextCapabilities. Used to avoid recreating a ContextCapabilities every time a context is made current. | |
| current_capabilities | back to summary |
|---|---|
| private static final ThreadLocal<ContextCapabilities> current_capabilities Maps threads to their current context's ContextCapabilities, if any | |
| did_auto_load | back to summary |
|---|---|
| private static boolean did_auto_load | |
| fast_path_cache | back to summary |
|---|---|
| private static GLContext. The getCapabilities() method is a potential hot spot in any LWJGL application, since it is needed for context capability discovery (e.g. is OpenGL 2.0 supported?), and for the function pointers of gl functions. However, the 'current_capabilities' ThreadLocal is (relatively) expensive to look up, and since most OpenGL applications use are single threaded rendering, the following two is an optimization for this case. ThreadLocals can be thought of as a mapping between threads and values, so the idea is to use a lock-less cache of mappings between threads and the current ContextCapabilities. The cache could be any size, but in our case, we want a single sized cache for optimal performance in the single threaded case. 'fast_path_cache' is the most recent ContextCapabilities (potentially null) and its owner. By recent I mean the last thread setting the value in setCapabilities(). When getCapabilities() is called, a check to see if the current is the owner of the ContextCapabilities instance in fast_path_cache. If so, the instance is returned, if not, some thread has since taken ownership of the cache entry and the slower current_capabilities ThreadLocal is queried instead. No locks are needed in get/setCapabilities, because even though fast_path_cache can be accessed from multiple threads at once, we are guaranteed by the JVM spec that its value is always valid. Furthermore, if the ownership test in getCapabilities() succeeds, the cache entry can only contain the correct ContextCapabilites (that is, the one from getThreadLocalCapabilites()), since no other thread can set the owner to anyone else than itself. | |
| gl_ref_count | back to summary |
|---|---|
| private static int gl_ref_count Reference count of the native opengl implementation library | |
| thread_cache_entries | back to summary |
|---|---|
| private static final ThreadLocal<GLContext. Simple lock-free cache of CapabilitesEntryCache to avoid allocating more than one cache entry per thread | |
| GLContext | back to summary |
|---|---|
| public GLContext() | |
| getCapabilities | back to summary |
|---|---|
| public static ContextCapabilities getCapabilities() Get the current capabilities instance. It contains the flags used to test for support of a particular extension.
| |
| getCapabilities | back to summary |
|---|---|
| pack-priv static ContextCapabilities getCapabilities(Object context) Returns the capabilities instance associated with the specified context object.
| |
| getCapabilitiesImpl | back to summary |
|---|---|
| private static ContextCapabilities getCapabilitiesImpl() | |
| getFunctionAddress | back to summary |
|---|---|
| pack-priv static long getFunctionAddress(String[] aliases) Helper method to get a pointer to a named function with aliases in the OpenGL library.
| |
| getFunctionAddress | back to summary |
|---|---|
| pack-priv static long getFunctionAddress(String name) Helper method to get a pointer to a named function in the OpenGL library. | |
| getPlatformSpecificFunctionAddress | back to summary |
|---|---|
| pack-priv static long getPlatformSpecificFunctionAddress(String function_prefix, String[] os_prefixes, String[] os_function_prefixes, String function) Helper method to get a pointer to a named function in the OpenGL library with a name dependent on the current platform | |
| getSupportedExtensions | back to summary |
|---|---|
| pack-priv static int getSupportedExtensions(final Set<String> supported_extensions) Determine which extensions are available and returns the context profile mask. Helper method to ContextCapabilities. | |
| getThreadLocalCapabilities | back to summary |
|---|---|
| private static ContextCapabilities getThreadLocalCapabilities() | |
| initNativeStubs | back to summary |
|---|---|
| pack-priv static void initNativeStubs(final Class<?> extension_class, Set<E> supported_extensions, String ext_name) Helper method to ContextCapabilities. It will try to initialize the native stubs, and remove the given extension name from the extension set if the initialization fails. | |
| loadOpenGLLibrary | back to summary |
|---|---|
| public static synchronized void loadOpenGLLibrary() throws LWJGLException If the OpenGL reference count is 0, the library is loaded. The reference count is then incremented. | |
| ngetFunctionAddress | back to summary |
|---|---|
| private static native long ngetFunctionAddress(long name) | |
| nLoadOpenGLLibrary | back to summary |
|---|---|
| private static native void nLoadOpenGLLibrary() throws LWJGLException | |
| nUnloadOpenGLLibrary | back to summary |
|---|---|
| private static native void nUnloadOpenGLLibrary() | |
| resetNativeStubs | back to summary |
|---|---|
| pack-priv static native void resetNativeStubs(Class<T> clazz) Native method to clear native stub bindings | |
| setCapabilities | back to summary |
|---|---|
| pack-priv static void setCapabilities(ContextCapabilities capabilities) Set the current capabilities instance. It contains the flags used to test for support of a particular extension.
| |
| unloadOpenGLLibrary | back to summary |
|---|---|
| public static synchronized void unloadOpenGLLibrary() The OpenGL library reference count is decremented, and if it reaches 0, the library is unloaded. | |
| useContext | back to summary |
|---|---|
| public static synchronized void useContext(Object context) throws LWJGLException Makes a GL context the current LWJGL context by loading GL function pointers. The context must be current before a call to this method! Instead it simply ensures that the current context is reflected accurately by GLContext's extension caps and function pointers. Use useContext(null) when no context is active. If the context is the same as last time, then this is a no-op. If the context has not been encountered before it will be fully initialized from scratch. Otherwise a cached set of caps and function pointers will be used. The reference to the context is held in a weak reference; therefore if no strong reference exists to the GL context it will automatically be forgotten by the VM at an indeterminate point in the future, freeing up a little RAM.
| |
| useContext | back to summary |
|---|---|
| public static synchronized void useContext(Object context, boolean forwardCompatible) throws LWJGLException Makes a GL context the current LWJGL context by loading GL function pointers. The context must be current before a call to this method! Instead it simply ensures that the current context is reflected accurately by GLContext's extension caps and function pointers. Use useContext(null) when no context is active. If the context is the same as last time, then this is a no-op. If the context has not been encountered before it will be fully initialized from scratch. Otherwise a cached set of caps and function pointers will be used. The reference to the context is held in a weak reference; therefore if no strong reference exists to the GL context it will automatically be forgotten by the VM at an indeterminate point in the future, freeing up a little RAM. If forwardCompatible is true, function pointers of deprecated GL11-GL21 functionality will not be loaded. Calling a deprecated
function using the specified context will result in an
| |
| Modifier and Type | Field and Description |
|---|---|
| pack-priv ContextCapabilities | |
| pack-priv Thread |
| Access | Constructor and Description |
|---|---|
| private |
| capabilities | back to summary |
|---|---|
| pack-priv ContextCapabilities capabilities | |
| owner | back to summary |
|---|---|
| pack-priv Thread owner | |
| CapabilitiesCacheEntry | back to summary |
|---|---|
| private CapabilitiesCacheEntry() | |