Class GLDrawableFactory
- java.lang.Object
-
- com.jogamp.opengl.GLDrawableFactory
-
public abstract class GLDrawableFactory extends Object
Provides a virtual machine- and operating system-independent mechanism for creating
GLDrawables.The
GLCapabilitiesobjects passed in to the various factory methods are used as a hint for the properties of the returned drawable. The default capabilities selection algorithm (equivalent to passing in a nullGLCapabilitiesChooser) is described inDefaultGLCapabilitiesChooser. Sophisticated applications needing to change the selection algorithm may pass in their ownGLCapabilitiesChooserwhich can select from the available pixel formats. The GLCapabilitiesChooser mechanism may not be supported by all implementations or on all platforms, in which case any passed GLCapabilitiesChooser will be ignored.Because of the multithreaded nature of the Java platform's Abstract Window Toolkit, it is typically not possible to immediately reject a given
GLCapabilitiesas being unsupportable by either returningnullfrom the creation routines or raising aGLException. The semantics of the rejection process are (unfortunately) left unspecified for now. The current implementation will cause aGLExceptionto be raised during the first repaint of theGLCanvasorGLJPanelif the capabilities can not be met.
GLOffscreenAutoDrawableare created lazily, seecreateOffscreenAutoDrawable(..).The concrete GLDrawableFactory subclass instantiated by
getFactorycan be changed by setting the system propertyopengl.factory.class.nameto the fully-qualified name of the desired class.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract booleancanCreateExternalGLDrawable(AbstractGraphicsDevice device)Returns true if it is possible to create an external GLDrawable object viacreateExternalGLDrawable().abstract booleancanCreateFBO(AbstractGraphicsDevice device, GLProfile glp)Returns true if it is possible to create an framebuffer object (FBO).abstract booleancanCreateGLPbuffer(AbstractGraphicsDevice device, GLProfile glp)Returns true if it is possible to create an pbuffer surface.abstract GLAutoDrawablecreateDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)Creates arealizeddummyGLAutoDrawableincl it's dummy, invisibleNativeSurfaceas created withcreateDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser).abstract GLDrawablecreateDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)Creates anunrealizeddummyGLDrawable.abstract GLContextcreateExternalGLContext()Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library.abstract GLDrawablecreateExternalGLDrawable()Creates aGLDrawableobject representing an existing OpenGL drawable in an external (third-party) OpenGL-based library.abstract GLDrawablecreateGLDrawable(NativeSurface target)Returns anunrealizedGLDrawable according to it's chosenGLCapabilitiesImmutable,
which determines pixel format, on- and offscreen incl.abstract GLOffscreenAutoDrawablecreateOffscreenAutoDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height)Creates arealizedGLOffscreenAutoDrawableincl it's offscreenNativeSurfacewith the given capabilities and dimensions.abstract GLDrawablecreateOffscreenDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height)Creates anunrealizedoffscreenGLDrawableincl it's offscreenNativeSurfacewith the given capabilities and dimensions.abstract ProxySurfacecreateProxySurface(AbstractGraphicsDevice device, int screenIdx, long windowHandle, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, UpstreamSurfaceHook upstream)Creates a proxyNativeSurfacew/ defined surface handle, i.e.List<GLCapabilitiesImmutable>getAvailableCapabilities(AbstractGraphicsDevice device)Returns an array of available GLCapabilities for the device.
The list is sorted by the native ID, ascending.
The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.abstract AbstractGraphicsDevicegetDefaultDevice()static GLDrawableFactorygetDesktopFactory()Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or nullstatic GLDrawableFactorygetEGLFactory()Returns the soleGLDrawableFactoryinstance for EGL if exist or null.static GLDrawableFactorygetFactory(boolean useNativeGLES)Returns the soleGLDrawableFactoryinstance, either for mobile ifusesNativeGLESis true, or for desktop otherwise.static GLDrawableFactorygetFactory(AbstractGraphicsDevice device)Returns the soleGLDrawableFactorymatching the givenAbstractGraphicsDeviceinstance, which will be suitable either for native mobile or native desktop.static GLDrawableFactorygetFactory(GLProfile glProfile)Returns the soleGLDrawableFactoryinstance.abstract booleangetIsDeviceCompatible(AbstractGraphicsDevice device)abstract GLRendererQuirksgetRendererQuirks(AbstractGraphicsDevice device, GLProfile glp)Returns the shared resource's contextGLRendererQuirks.abstract booleanhasOpenGLDesktopSupport()Method returnstrueif underlying implementation may support native desktop OpenGL, otherwisefalse.abstract booleanhasOpenGLESSupport()Method returnstrueif underlying implementation may support native embedded OpenGL ES, otherwisefalse.booleanhasRendererQuirk(AbstractGraphicsDevice device, GLProfile glp, int quirk)Returns true if thequirkexist in the shared resource's contextGLRendererQuirks.static voidinitSingleton()Instantiate singleton factories if available, EGLES1, EGLES2 and the OS native ones.abstract voidresetAllDisplayGamma()Resets the gamma, brightness and contrast values of all modified displays to their original values beforesetDisplayGammawas called the first time.abstract voidresetDisplayGamma(NativeSurface surface)Resets the gamma, brightness and contrast values of the display associated with the givensurfaceto its original values beforesetDisplayGammawas called the first time.abstract booleansetDisplayGamma(NativeSurface surface, float gamma, float brightness, float contrast)Sets the gamma, brightness, and contrast of the display associated with the givensurface.
-
-
-
Method Detail
-
initSingleton
public static final void initSingleton()
Instantiate singleton factories if available, EGLES1, EGLES2 and the OS native ones.
-
setDisplayGamma
public abstract boolean setDisplayGamma(NativeSurface surface, float gamma, float brightness, float contrast) throws IllegalArgumentException
Sets the gamma, brightness, and contrast of the display associated with the givensurface.This functionality is not available on all platforms and graphics hardware. Returns true if the settings were successfully changed, false if not. This method may return false for some values of the incoming arguments even on hardware which does support the underlying functionality.
If this method returns true, the display settings will automatically be reset to their original values upon JVM exit (assuming the JVM does not crash); if the user wishes to change the display settings back to normal ahead of time, use
resetDisplayGamma(NativeSurface)orresetAllDisplayGamma().It is recommended to call
resetDisplayGamma(NativeSurface)orresetAllDisplayGamma()before calling e.g.System.exit()from the application rather than rely on the shutdown hook functionality due to inevitable race conditions and unspecified behavior during JVM teardown.This method may be called multiple times during the application's execution, but calling
resetDisplayGamma(NativeSurface)will only reset the settings to the values before the first call to this method.- Parameters:
surface- denominates the display devicegamma- The gamma value, typically > 1.0 (default values vary, but typically roughly 1.0)brightness- The brightness value between -1.0 and 1.0, inclusive (default values vary, but typically 0)contrast- The contrast, greater than 0.0 (default values vary, but typically 1)- Returns:
- true if gamma settings were successfully changed, false if not
- Throws:
IllegalArgumentException- if any of the parameters were out-of-bounds- See Also:
resetDisplayGamma(NativeSurface),resetAllDisplayGamma()
-
resetDisplayGamma
public abstract void resetDisplayGamma(NativeSurface surface)
Resets the gamma, brightness and contrast values of the display associated with the givensurfaceto its original values beforesetDisplayGammawas called the first time.While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.
-
resetAllDisplayGamma
public abstract void resetAllDisplayGamma()
Resets the gamma, brightness and contrast values of all modified displays to their original values beforesetDisplayGammawas called the first time.While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.
-
getDefaultDevice
public abstract AbstractGraphicsDevice getDefaultDevice()
Retrieve the defaultdeviceconnection,unit IDandunique ID name. for this factory
The implementation must return a nonnulldefault device, which must not be opened, ie. it's native handle isnull.This method shall return the default device if available even if the GLDrawableFactory is not functional and hence not compatible. The latter situation may happen because no native OpenGL implementation is available for the specific implementation.
- Returns:
- the default shared device for this factory, eg. :0.0 on X11 desktop.
- See Also:
getIsDeviceCompatible(AbstractGraphicsDevice)
-
getIsDeviceCompatible
public abstract boolean getIsDeviceCompatible(AbstractGraphicsDevice device)
- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.- Returns:
- true if the device is compatible with this factory, ie. if it can be used for GLDrawable creation. Otherwise false. This implies validation whether the implementation is functional.
- See Also:
getDefaultDevice()
-
hasRendererQuirk
public final boolean hasRendererQuirk(AbstractGraphicsDevice device, GLProfile glp, int quirk)
Returns true if thequirkexist in the shared resource's contextGLRendererQuirks.Convenience method for:
final GLRendererQuirks glrq = factory.getRendererQuirks(device); return null != glrq ? glrq.exist(quirk) : false;- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.glp-GLProfileto identify the device'sGLRendererQuirks, maybenullquirk- the quirk to be tested, e.g.GLRendererQuirks.NoDoubleBufferedPBuffer.- Throws:
IllegalArgumentException- if the quirk is out of range- See Also:
getRendererQuirks(AbstractGraphicsDevice, GLProfile),GLRendererQuirks
-
getRendererQuirks
public abstract GLRendererQuirks getRendererQuirks(AbstractGraphicsDevice device, GLProfile glp)
Returns the shared resource's contextGLRendererQuirks.Implementation calls
GLContext.getRendererQuirks()on the shared resource context.In case no shared device exist yet or the implementation doesn't support tracking quirks, the result is always
null.- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.glp-GLProfileto identify the device'sGLRendererQuirks, maybenull- See Also:
GLContext.getRendererQuirks(),GLRendererQuirks
-
hasOpenGLDesktopSupport
public abstract boolean hasOpenGLDesktopSupport()
Method returnstrueif underlying implementation may support native desktop OpenGL, otherwisefalse.
-
hasOpenGLESSupport
public abstract boolean hasOpenGLESSupport()
Method returnstrueif underlying implementation may support native embedded OpenGL ES, otherwisefalse.
-
getDesktopFactory
public static GLDrawableFactory getDesktopFactory()
Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or nullTo fetch the appropriate
GLDrawableFactoryfor native desktop or mobile, usegetFactory(boolean).It is possible that the desktop
GLDrawableFactorywill be used for native mobile GL profiles, e.g.Platform.OSType.IOS.- Returns:
- the matching
GLDrawableFactoryornullif none is available
-
getEGLFactory
public static GLDrawableFactory getEGLFactory()
Returns the soleGLDrawableFactoryinstance for EGL if exist or null.To fetch the appropriate
GLDrawableFactoryfor native desktop or mobile, usegetFactory(boolean).It is possible that a non EGL
GLDrawableFactorywill be used for native mobile GL profiles, e.g.Platform.OSType.IOS.- Returns:
- the matching
GLDrawableFactoryornullif none is available
-
getFactory
public static GLDrawableFactory getFactory(GLProfile glProfile) throws GLException
Returns the soleGLDrawableFactoryinstance.- Parameters:
glProfile- GLProfile to determine the factory type, ie for native mobile GL or native desktop GL.- Returns:
- the matching
GLDrawableFactory - Throws:
GLException- if no matchingGLDrawableFactoryexists
-
getFactory
public static GLDrawableFactory getFactory(boolean useNativeGLES)
Returns the soleGLDrawableFactoryinstance, either for mobile ifusesNativeGLESis true, or for desktop otherwise.- Parameters:
useNativeGLES- request native mobile GLES support if true- Returns:
- the matching
GLDrawableFactoryornullif none is available
-
getFactory
public static GLDrawableFactory getFactory(AbstractGraphicsDevice device)
Returns the soleGLDrawableFactorymatching the givenAbstractGraphicsDeviceinstance, which will be suitable either for native mobile or native desktop.- Parameters:
device- the queriesAbstractGraphicsDeviceseeking for its matching factory- Returns:
- the matching
GLDrawableFactoryornullif none is available
-
getAvailableCapabilities
public final List<GLCapabilitiesImmutable> getAvailableCapabilities(AbstractGraphicsDevice device)
Returns an array of available GLCapabilities for the device.
The list is sorted by the native ID, ascending.
The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.- Returns:
- A list of
GLCapabilitiesImmutable's, maybe empty if none is available.
-
createGLDrawable
public abstract GLDrawable createGLDrawable(NativeSurface target) throws IllegalArgumentException, GLException
Returns anunrealizedGLDrawable according to it's chosenGLCapabilitiesImmutable,
which determines pixel format, on- and offscreen incl. PBuffer type.The chosen
GLCapabilitiesImmutableare referenced within the targetNativeSurface'sAbstractGraphicsConfiguration.An onscreen GLDrawable is created if
caps.isOnscreen()is true.A FBO drawable is created if both
caps.isFBO()andcanCreateFBO(device, caps.getGLProfile())is true.A Pbuffer drawable is created if both
caps.isPBuffer()andcanCreateGLPbuffer(device)is true.If not onscreen and neither FBO nor Pbuffer is available, a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.
- Throws:
IllegalArgumentException- if the passed target is nullGLException- if any window system-specific errors caused the creation of the GLDrawable to fail.- See Also:
canCreateGLPbuffer(AbstractGraphicsDevice, GLProfile),GLContext.isFBOAvailable(AbstractGraphicsDevice, GLProfile),Capabilities.isOnscreen(),GLCapabilities.isFBO(),GLCapabilities.isPBuffer(),GraphicsConfigurationFactory#chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int)
-
createOffscreenAutoDrawable
public abstract GLOffscreenAutoDrawable createOffscreenAutoDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height) throws GLException
Creates arealizedGLOffscreenAutoDrawableincl it's offscreenNativeSurfacewith the given capabilities and dimensions.The
GLOffscreenAutoDrawable'sGLDrawableisrealizedwithout an assignedGLContext, hence not initialized completely.
TheGLContextcan be assigned later manually viasetContext(ctx)or it will be created lazily at the 1stdisplay()method call.
LazyGLContextcreation will take a sharedGLContextinto account which has been setdirectlyorvia another GLAutoDrawable.In case the passed
GLCapabilitiesImmutablecontains default values, i.e.caps.isOnscreen()== true, it is auto-configured. Auto configuration will setcapsto offscreen and FBO or Pbuffer, whichever is available in that order.A FBO based auto drawable,
GLOffscreenAutoDrawable.FBO, is created if bothcaps.isFBO()andcanCreateFBO(device, caps.getGLProfile())is true.A Pbuffer based auto drawable is created if both
caps.isPBuffer()andcanCreateGLPbuffer(device)is true.If neither FBO nor Pbuffer is available, a simple pixmap/bitmap auto drawable is created, which is unlikely to be hardware accelerated.
The resulting
GLOffscreenAutoDrawablehas it's own independent device instance usingdevicedetails.- Parameters:
device- whichconnectiondenotes the shared device to be used, may benullfor the platform's default device.caps- the requested GLCapabiltieschooser- the custom chooser, may be null for defaultwidth- the requested offscreen widthheight- the requested offscreen height- Returns:
- the created and realized offscreen
GLOffscreenAutoDrawableinstance - Throws:
GLException- if any window system-specific errors caused the creation of the Offscreen to fail.- See Also:
createOffscreenDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int)
-
createDummyAutoDrawable
public abstract GLAutoDrawable createDummyAutoDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)
Creates arealizeddummyGLAutoDrawableincl it's dummy, invisibleNativeSurfaceas created withcreateDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser).The dummy
GLAutoDrawable'sGLDrawableisrealizedwithout an assignedGLContext, hence not initialized completely.
TheGLContextcan be assigned later manually viasetContext(ctx)or it will be created lazily at the 1stdisplay()method call.
LazyGLContextcreation will take a sharedGLContextinto account which has been setdirectlyorvia another GLAutoDrawable.- Parameters:
deviceReq- whichconnectiondenotes the shared device to be used, may benullfor the platform's default device.createNewDevice- iftruea new independent device instance is created from thedeviceReq, otherwisedeviceReqis used as-is and must be valid!capsRequested- the desiredGLCapabilitiesImmutable, incl. it'sGLProfile. For shared context, sameVisualIDHolder.getVisualID(com.jogamp.nativewindow.VisualIDHolder.VIDType)across shared drawables will yield best compatibility.chooser- the custom chooser, may be null for default- Returns:
- the created and realized dummy
GLAutoDrawableinstance - See Also:
createDummyDrawable(AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser)
-
createOffscreenDrawable
public abstract GLDrawable createOffscreenDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height) throws GLException
Creates anunrealizedoffscreenGLDrawableincl it's offscreenNativeSurfacewith the given capabilities and dimensions.In case the passed
GLCapabilitiesImmutablecontains default values, i.e.caps.isOnscreen()== true, it is auto-configured. The latter will set offscreen and also FBO or Pbuffer, whichever is available in that order.A resizeable FBO drawable,
GLFBODrawable.Resizeable, is created if bothcaps.isFBO()andcanCreateFBO(device, caps.getGLProfile())is true.A Pbuffer drawable is created if both
caps.isPBuffer()andcanCreateGLPbuffer(device)is true.If neither FBO nor Pbuffer is available, a simple pixmap/bitmap drawable is created, which is unlikely to be hardware accelerated.
The resulting
GLDrawablehas it's own independent device instance usingdevicedetails.- Parameters:
device- whichconnectiondenotes the shared device to be used, may benullfor the platform's default device.caps- the requested GLCapabiltieschooser- the custom chooser, may be null for defaultwidth- the requested offscreen widthheight- the requested offscreen height- Returns:
- the created unrealized offscreen
GLDrawable - Throws:
GLException- if any window system-specific errors caused the creation of the Offscreen to fail.- See Also:
#createOffscreenAutoDrawable(AbstractGraphicsDevice, GLCapabilitiesImmutable, GLCapabilitiesChooser, int, int, GLContext)
-
createDummyDrawable
public abstract GLDrawable createDummyDrawable(AbstractGraphicsDevice deviceReq, boolean createNewDevice, GLCapabilitiesImmutable capsRequested, GLCapabilitiesChooser chooser)
Creates anunrealizeddummyGLDrawable. A dummy drawable is not visible on screen and will not be used to render directly to, it maybe on- or offscreen and implementation prefers creating a surfaceless drawable.It is used to allow the creation of a
GLContextto query information. It also allows creation of framebuffer objects which are used for rendering or creating a shared GLContext w/o actually rendering to this dummy drawable's framebuffer.- Parameters:
deviceReq- whichconnectiondenotes the shared device to be used, may benullfor the platform's default device.createNewDevice- iftruea new independent device instance is created from thedeviceReq, otherwisedeviceReqis used as-is and must be valid!capsRequested- the desiredGLCapabilitiesImmutable, incl. it'sGLProfile. For shared context, samevisual IDorcapsacross shared drawables will yield best compatibility.chooser- the custom chooser, may be null for default- Returns:
- the created unrealized dummy
GLDrawable
-
createProxySurface
public abstract ProxySurface createProxySurface(AbstractGraphicsDevice device, int screenIdx, long windowHandle, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, UpstreamSurfaceHook upstream)
Creates a proxyNativeSurfacew/ defined surface handle, i.e. aWrappedSurfaceorGDISurfaceinstance.It's
AbstractGraphicsConfigurationis properly set according to the givenwindowHandle's native visualID if set or the givenGLCapabilitiesImmutable.Lifecycle (creation and destruction) of the given surface handle shall be handled by the caller via
ProxySurface.createNotify()andProxySurface.destroyNotify().Such surface can be used to instantiate a GLDrawable. With the help of
GLAutoDrawableDelegateyou will be able to implement a new native windowing system binding almost on-the-fly, seeGLCanvas.The resulting
GLOffscreenAutoDrawablehas it's own independent device instance usingdevicedetails which may be blocking depending on platform and windowing-toolkit requirements.- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device. Caller has to ensure it is compatible w/ the givenwindowHandlescreenIdx- matching screen index of givenwindowHandlewindowHandle- the native window handlecaps- the requested GLCapabiltieschooser- the custom chooser, may be null for defaultupstream- optionalUpstreamSurfaceHookallowing control of theProxySurface's lifecycle and data it presents.- Returns:
- the created
ProxySurfaceinstance w/ defined surface handle.
-
canCreateFBO
public abstract boolean canCreateFBO(AbstractGraphicsDevice device, GLProfile glp)
Returns true if it is possible to create an framebuffer object (FBO).FBO feature is implemented in OpenGL, hence it is
GLProfiledependent.FBO support is queried as described in
GLContext.hasBasicFBOSupport().- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.glp-GLProfileto check for FBO capabilities- See Also:
GLContext.hasBasicFBOSupport()
-
canCreateGLPbuffer
public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device, GLProfile glp)
Returns true if it is possible to create an pbuffer surface.Some older graphics cards do not have this capability, as well as some new GL implementation, i.e. OpenGL 3 core on OSX.
- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.glp-GLProfileto check for FBO capabilities
-
createExternalGLContext
public abstract GLContext createExternalGLContext() throws GLException
Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library. This GLContext object may be used to draw into this preexisting context using its
GLandGLUobjects. New contexts created throughGLDrawables may share textures and display lists with this external context.The underlying OpenGL context must be current on the current thread at the time this method is called. The user is responsible for the maintenance of the underlying OpenGL context; calls to
makeCurrentandreleaseon the returned GLContext object have no effect. If the underlying OpenGL context is destroyed, thedestroymethod should be called on theGLContext. A newGLContextobject should be created for each newly-created underlying OpenGL context.- Throws:
GLException- if any window system-specific errors caused the creation of the external GLContext to fail.
-
canCreateExternalGLDrawable
public abstract boolean canCreateExternalGLDrawable(AbstractGraphicsDevice device)
Returns true if it is possible to create an external GLDrawable object viacreateExternalGLDrawable().- Parameters:
device- whichconnectiondenotes the shared the target device, may benullfor the platform's default device.
-
createExternalGLDrawable
public abstract GLDrawable createExternalGLDrawable() throws GLException
Creates a
GLDrawableobject representing an existing OpenGL drawable in an external (third-party) OpenGL-based library. This GLDrawable object may be used to create new, fully-functionalGLContexts on the OpenGL drawable. This is useful when interoperating with a third-party OpenGL-based library and it is essential to not perturb the state of the library's existing context, even to the point of not sharing textures or display lists with that context.An underlying OpenGL context must be current on the desired drawable and the current thread at the time this method is called. The user is responsible for the maintenance of the underlying drawable. If one or more contexts are created on the drawable using
GLDrawable.createContext(com.jogamp.opengl.GLContext), and the drawable is deleted by the third-party library, the user is responsible for callingGLContext.destroy()on these contexts.Calls to
setSize,getWidthandgetHeightare illegal on the returned GLDrawable. If these operations are required by the user, they must be performed by the third-party library.It is legal to create both an external GLContext and GLDrawable representing the same third-party OpenGL entities. This can be used, for example, to query current state information using the external GLContext and then create and set up new GLContexts using the external GLDrawable.
This functionality may not be available on all platforms and
canCreateExternalGLDrawable(com.jogamp.nativewindow.AbstractGraphicsDevice)should be called first to see if it is present. For example, on X11 platforms, this API requires the presence of GLX 1.3 or later.- Throws:
GLException- if any window system-specific errors caused the creation of the external GLDrawable to fail.
-
-