JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.nativewindow.GraphicsConfigurationFactory Class Referenceabstract

Provides the mechanism by which the graphics configuration for a window can be chosen before the window is created. More...

Collaboration diagram for com.jogamp.nativewindow.GraphicsConfigurationFactory:

Public Member Functions

final AbstractGraphicsConfiguration chooseGraphicsConfiguration (final CapabilitiesImmutable capsChosen, final CapabilitiesImmutable capsRequested, final CapabilitiesChooser chooser, final AbstractGraphicsScreen screen, final int nativeVisualID) throws IllegalArgumentException, NativeWindowException
 

Static Public Member Functions

static synchronized void initSingleton ()
 
static synchronized void shutdown ()
 
static GraphicsConfigurationFactory getFactory (final AbstractGraphicsDevice device, final CapabilitiesImmutable caps)
 Returns the graphics configuration factory for use with the given device and capability. More...
 
static GraphicsConfigurationFactory getFactory (final Class<?> deviceType, final Class<?> capabilitiesType) throws IllegalArgumentException, NativeWindowException
 Returns the graphics configuration factory for use with the given device and capability class. More...
 

Protected Member Functions

 GraphicsConfigurationFactory ()
 Creates a new NativeWindowFactory instance. More...
 
abstract AbstractGraphicsConfiguration chooseGraphicsConfigurationImpl (CapabilitiesImmutable capsChosen, CapabilitiesImmutable capsRequested, CapabilitiesChooser chooser, AbstractGraphicsScreen screen, int nativeVisualID) throws IllegalArgumentException, NativeWindowException
 Called by chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int) post argument validation within AbstractGraphicsDevice#lock()ed segment. More...
 

Static Protected Member Functions

static String getThreadName ()
 
static String toHexString (final int val)
 
static String toHexString (final long val)
 
static GraphicsConfigurationFactory registerFactory (final Class<?> abstractGraphicsDeviceImplementor, final Class<?> capabilitiesType, final GraphicsConfigurationFactory factory) throws IllegalArgumentException
 Registers a GraphicsConfigurationFactory handling the given graphics device and capability class. More...
 

Static Protected Attributes

static final boolean DEBUG
 

Detailed Description

Provides the mechanism by which the graphics configuration for a window can be chosen before the window is created.

The graphics configuration decides parameters related to hardware accelerated rendering such as the OpenGL pixel format.
On some window systems (EGL/OpenKODE and X11 in particular) it is necessary to choose the graphics configuration early at window creation time.
Note that the selection of the graphics configuration is an algorithm which does not have strong dependencies on the particular Java window toolkit in use (e.g., AWT) and therefore it is strongly desirable to factor this functionality out of the core NativeWindowFactory so that new window toolkits can replace just the NativeWindowFactory and reuse the graphics configuration selection algorithm provided by, for example, an OpenGL binding.

Definition at line 67 of file GraphicsConfigurationFactory.java.

Constructor & Destructor Documentation

◆ GraphicsConfigurationFactory()

com.jogamp.nativewindow.GraphicsConfigurationFactory.GraphicsConfigurationFactory ( )
protected

Creates a new NativeWindowFactory instance.

End users do not need to call this method.

Definition at line 177 of file GraphicsConfigurationFactory.java.

Member Function Documentation

◆ chooseGraphicsConfiguration()

final AbstractGraphicsConfiguration com.jogamp.nativewindow.GraphicsConfigurationFactory.chooseGraphicsConfiguration ( final CapabilitiesImmutable  capsChosen,
final CapabilitiesImmutable  capsRequested,
final CapabilitiesChooser  chooser,
final AbstractGraphicsScreen  screen,
final int  nativeVisualID 
) throws IllegalArgumentException, NativeWindowException

Selects a graphics configuration on the specified graphics device compatible with the supplied Capabilities. Some platforms (e.g.: X11, EGL, KD) require the graphics configuration to be specified when the native window is created. These architectures have seperated their device, screen, window and drawable context and hence are capable of quering the capabilities for each screen. A fully established window is not required.

Other platforms (e.g. Windows, MacOSX) don't offer the mentioned seperation and hence need a fully established window and it's drawable. Here the validation of the capabilities is performed later. In this case, the AbstractGraphicsConfiguration implementation must allow an overwrite of the Capabilites, for example DefaultGraphicsConfiguration.setChosenCapabilities(..).

This method is mainly intended to be both used and implemented by the OpenGL binding.

The concrete data type of the passed graphics device and returned graphics configuration must be specified in the documentation binding this particular API to the underlying window toolkit. The Reference Implementation accepts AWTGraphicsDevice objects and returns AWTGraphicsConfiguration objects. On X11 platforms where the AWT is not in use, it also accepts X11GraphicsDevice objects and returns X11GraphicsConfiguration objects.

Parameters
capsChosenthe intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested
capsRequestedthe original requested capabilities
chooserthe choosing implementation
screenthe referring Screen
nativeVisualIDif not VisualIDHolder#VID_UNDEFINED it reflects a pre-chosen visualID of the native platform's windowing system.
Returns
the complete GraphicsConfiguration
Exceptions
IllegalArgumentExceptionif the data type of the passed AbstractGraphicsDevice is not supported by this NativeWindowFactory.
NativeWindowExceptionif any window system-specific errors caused the selection of the graphics configuration to fail.
See also
com.jogamp.nativewindow.GraphicsConfigurationFactory::chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
com.jogamp.nativewindow.DefaultGraphicsConfiguration::setChosenCapabilities(Capabilities caps)

Definition at line 405 of file GraphicsConfigurationFactory.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ chooseGraphicsConfigurationImpl()

abstract AbstractGraphicsConfiguration com.jogamp.nativewindow.GraphicsConfigurationFactory.chooseGraphicsConfigurationImpl ( CapabilitiesImmutable  capsChosen,
CapabilitiesImmutable  capsRequested,
CapabilitiesChooser  chooser,
AbstractGraphicsScreen  screen,
int  nativeVisualID 
) throws IllegalArgumentException, NativeWindowException
abstractprotected

Called by chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int) post argument validation within AbstractGraphicsDevice#lock()ed segment.

Parameters
capsChosenthe intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested
capsRequestedthe original requested capabilities
chooserthe choosing implementation
screenthe referring Screen
nativeVisualIDif not VisualIDHolder#VID_UNDEFINED it reflects a pre-chosen visualID of the native platform's windowing system.
Returns
the complete GraphicsConfiguration
Exceptions
IllegalArgumentExceptionif the data type of the passed AbstractGraphicsDevice is not supported by this NativeWindowFactory.
NativeWindowExceptionif any window system-specific errors caused the selection of the graphics configuration to fail.
See also
chooseGraphicsConfiguration(CapabilitiesImmutable, CapabilitiesImmutable, CapabilitiesChooser, AbstractGraphicsScreen, int)
Here is the caller graph for this function:

◆ getFactory() [1/2]

static GraphicsConfigurationFactory com.jogamp.nativewindow.GraphicsConfigurationFactory.getFactory ( final AbstractGraphicsDevice  device,
final CapabilitiesImmutable  caps 
)
static

Returns the graphics configuration factory for use with the given device and capability.

See also
#getFactory(Class, Class)

Definition at line 186 of file GraphicsConfigurationFactory.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getFactory() [2/2]

static GraphicsConfigurationFactory com.jogamp.nativewindow.GraphicsConfigurationFactory.getFactory ( final Class<?>  deviceType,
final Class<?>  capabilitiesType 
) throws IllegalArgumentException, NativeWindowException
static

Returns the graphics configuration factory for use with the given device and capability class.

Note: Registered device types maybe classes or interfaces, where capabilities types are interfaces only.

Pseudo code for finding a suitable factory is:

 For-All devT := getTopDownDeviceTypes(deviceType)
     For-All capsT := getTopDownCapabilitiesTypes(capabilitiesType)
        f = factory.get(devT, capsT);
        if(f) { return f; }
     end
 end
Parameters
deviceTypethe minimum capabilities class type accepted, must implement or extend AbstractGraphicsDevice
capabilitiesTypethe minimum capabilities class type accepted, must implement or extend CapabilitiesImmutable
Exceptions
IllegalArgumentExceptionif the deviceType does not implement AbstractGraphicsDevice or capabilitiesType does not implement CapabilitiesImmutable

Definition at line 221 of file GraphicsConfigurationFactory.java.

◆ getThreadName()

static String com.jogamp.nativewindow.GraphicsConfigurationFactory.getThreadName ( )
staticprotected

Definition at line 163 of file GraphicsConfigurationFactory.java.

◆ initSingleton()

static synchronized void com.jogamp.nativewindow.GraphicsConfigurationFactory.initSingleton ( )
static

Definition at line 121 of file GraphicsConfigurationFactory.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ registerFactory()

static GraphicsConfigurationFactory com.jogamp.nativewindow.GraphicsConfigurationFactory.registerFactory ( final Class<?>  abstractGraphicsDeviceImplementor,
final Class<?>  capabilitiesType,
final GraphicsConfigurationFactory  factory 
) throws IllegalArgumentException
staticprotected

Registers a GraphicsConfigurationFactory handling the given graphics device and capability class.

This does not need to be called by end users, only implementors of new GraphicsConfigurationFactory subclasses.

Note: Registered device types maybe classes or interfaces, where capabilities types are interfaces only.

See getFactory(Class, Class) for a description of the find algorithm.

Parameters
deviceTypethe minimum capabilities class type accepted, must implement or extend interface AbstractGraphicsDevice
capabilitiesTypethe minimum capabilities class type accepted, must extend interface CapabilitiesImmutable
Returns
the previous registered factory, or null if none
Exceptions
IllegalArgumentExceptionif the given class does not implement AbstractGraphicsDevice

Definition at line 328 of file GraphicsConfigurationFactory.java.

Here is the caller graph for this function:

◆ shutdown()

static synchronized void com.jogamp.nativewindow.GraphicsConfigurationFactory.shutdown ( )
static

Definition at line 153 of file GraphicsConfigurationFactory.java.

Here is the caller graph for this function:

◆ toHexString() [1/2]

static String com.jogamp.nativewindow.GraphicsConfigurationFactory.toHexString ( final int  val)
staticprotected

Definition at line 167 of file GraphicsConfigurationFactory.java.

Here is the caller graph for this function:

◆ toHexString() [2/2]

static String com.jogamp.nativewindow.GraphicsConfigurationFactory.toHexString ( final long  val)
staticprotected

Definition at line 171 of file GraphicsConfigurationFactory.java.

Member Data Documentation

◆ DEBUG

final boolean com.jogamp.nativewindow.GraphicsConfigurationFactory.DEBUG
staticprotected

Definition at line 68 of file GraphicsConfigurationFactory.java.


The documentation for this class was generated from the following file: