Top Description Inners Fields Constructors Methods
com.jogamp.nativewindow

public abstract Class GraphicsConfigurationFactory

extends Object
Class Inheritance
Known Direct Subclasses
jogamp.nativewindow.DefaultGraphicsConfigurationFactoryImpl, jogamp.nativewindow.x11.X11GraphicsConfigurationFactory, jogamp.nativewindow.x11.awt.X11AWTGraphicsConfigurationFactory, jogamp.opengl.GLGraphicsConfigurationFactory
Imports
com.jogamp.common.ExceptionUtils, com.jogamp.common.util.ReflectionUtil, jogamp.nativewindow.Debug, .DefaultGraphicsConfigurationFactoryImpl, java.util.ArrayList, .Arrays, .Collections, .HashMap, .Iterator, .List, .Map, .Set
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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
GraphicsConfigurationFactory.DeviceCapsType

Field Summary

Modifier and TypeField and Description
protected static final boolean
DEBUG

private static final GraphicsConfigurationFactory.DeviceCapsType
defaultDeviceCapsType

pack-priv static boolean
initialized

private static final Map<GraphicsConfigurationFactory.DeviceCapsType, GraphicsConfigurationFactory>
registeredFactories

Constructor Summary

AccessConstructor and Description
protected
GraphicsConfigurationFactory()

Creates a new NativeWindowFactory instance.

Method Summary

Modifier and TypeMethod and Description
public final AbstractGraphicsConfiguration

Returns:

the complete GraphicsConfiguration
chooseGraphicsConfiguration(final CapabilitiesImmutable
the intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested
capsChosen, final CapabilitiesImmutable
the original requested capabilities
capsRequested, final CapabilitiesChooser
the choosing implementation
chooser, final AbstractGraphicsScreen
the referring Screen
screen, final int
if not VisualIDHolder#VID_UNDEFINED it reflects a pre-chosen visualID of the native platform's windowing system.
nativeVisualID)

Selects a graphics configuration on the specified graphics device compatible with the supplied Capabilities.

protected abstract AbstractGraphicsConfiguration
chooseGraphicsConfigurationImpl(CapabilitiesImmutable capsChosen, CapabilitiesImmutable capsRequested, CapabilitiesChooser chooser, AbstractGraphicsScreen screen, int nativeVisualID)

private static void
dumpFactories()

private static ArrayList<Class<?>>
getAllAssignableClassesFrom(final Class<?> superClassOrInterface, final Class<?> fromClass, final boolean interfacesOnly)

private static void
getAllAssignableClassesFrom(final Class<?> superClassOrInterface, final Class<?> fromClass, final boolean interfacesOnly, final List<Class<?>> resolvedInterfaces, final List<Class<?>> inspectClasses)

public static GraphicsConfigurationFactory
getFactory(final AbstractGraphicsDevice device, final CapabilitiesImmutable caps)

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

public static GraphicsConfigurationFactory
getFactory(final Class<?>
the minimum capabilities class type accepted, must implement or extend AbstractGraphicsDevice
deviceType, final Class<?>
the minimum capabilities class type accepted, must implement or extend CapabilitiesImmutable
capabilitiesType)

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

protected static String
getThreadName()

public static synchronized void
initSingleton()

protected static GraphicsConfigurationFactory

Returns:

the previous registered factory, or null if none
registerFactory(final Class<?>
the minimum capabilities class type accepted, must implement or extend interface AbstractGraphicsDevice
abstractGraphicsDeviceImplementor, final Class<?>
the minimum capabilities class type accepted, must extend interface CapabilitiesImmutable
capabilitiesType, final GraphicsConfigurationFactory factory)

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

public static synchronized void
shutdown()

protected static String
toHexString(final int val)

protected static String
toHexString(final long val)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEBUGback to summary
protected static final boolean DEBUG
defaultDeviceCapsTypeback to summary
private static final GraphicsConfigurationFactory.DeviceCapsType defaultDeviceCapsType
initializedback to summary
pack-priv static boolean initialized
registeredFactoriesback to summary
private static final Map<GraphicsConfigurationFactory.DeviceCapsType, GraphicsConfigurationFactory> registeredFactories

Constructor Detail

GraphicsConfigurationFactoryback to summary
protected GraphicsConfigurationFactory()

Creates a new NativeWindowFactory instance. End users do not need to call this method.

Method Detail

chooseGraphicsConfigurationback to summary
public final AbstractGraphicsConfiguration 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
capsChosen:CapabilitiesImmutable

the intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested

capsRequested:CapabilitiesImmutable

the original requested capabilities

chooser:CapabilitiesChooser

the choosing implementation

screen:AbstractGraphicsScreen

the referring Screen

nativeVisualID:int

if not VisualIDHolder#VID_UNDEFINED it reflects a pre-chosen visualID of the native platform's windowing system.

Returns:AbstractGraphicsConfiguration

the complete GraphicsConfiguration

Exceptions
IllegalArgumentException:
if the data type of the passed AbstractGraphicsDevice is not supported by this NativeWindowFactory.
NativeWindowException:
if 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)
chooseGraphicsConfigurationImplback to summary
protected abstract AbstractGraphicsConfiguration chooseGraphicsConfigurationImpl(CapabilitiesImmutable capsChosen, CapabilitiesImmutable capsRequested, CapabilitiesChooser chooser, AbstractGraphicsScreen screen, int nativeVisualID) throws IllegalArgumentException, NativeWindowException
dumpFactoriesback to summary
private static void dumpFactories()
getAllAssignableClassesFromback to summary
private static ArrayList<Class<?>> getAllAssignableClassesFrom(final Class<?> superClassOrInterface, final Class<?> fromClass, final boolean interfacesOnly)
getAllAssignableClassesFromback to summary
private static void getAllAssignableClassesFrom(final Class<?> superClassOrInterface, final Class<?> fromClass, final boolean interfacesOnly, final List<Class<?>> resolvedInterfaces, final List<Class<?>> inspectClasses)
getFactoryback to summary
public static GraphicsConfigurationFactory getFactory(final AbstractGraphicsDevice device, final CapabilitiesImmutable caps)

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

See Also
getFactory(Class, Class)
getFactoryback to summary
public 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.

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
deviceType:Class<?>

the minimum capabilities class type accepted, must implement or extend AbstractGraphicsDevice

capabilitiesType:Class<?>

the minimum capabilities class type accepted, must implement or extend CapabilitiesImmutable

Exceptions
IllegalArgumentException:
if the deviceType does not implement AbstractGraphicsDevice or capabilitiesType does not implement CapabilitiesImmutable
getThreadNameback to summary
protected static String getThreadName()
initSingletonback to summary
public static synchronized void initSingleton()
registerFactoryback to summary
protected 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.

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
abstractGraphicsDeviceImplementor:Class<?>

the minimum capabilities class type accepted, must implement or extend interface AbstractGraphicsDevice

capabilitiesType:Class<?>

the minimum capabilities class type accepted, must extend interface CapabilitiesImmutable

Returns:GraphicsConfigurationFactory

the previous registered factory, or null if none

Exceptions
IllegalArgumentException:
if the given class does not implement AbstractGraphicsDevice
shutdownback to summary
public static synchronized void shutdown()
toHexStringback to summary
protected static String toHexString(final int val)
toHexStringback to summary
protected static String toHexString(final long val)
com.jogamp.nativewindow back to summary

private Class GraphicsConfigurationFactory.DeviceCapsType

extends Object
Class Inheritance
  • java.lang.Object
  • com.jogamp.nativewindow.GraphicsConfigurationFactory.DeviceCapsType

Field Summary

Modifier and TypeField and Description
public final Class<?>
capsType

public final Class<?>
deviceType

private final int
hash32

Constructor Summary

AccessConstructor and Description
public
DeviceCapsType(final Class<?> deviceType, final Class<?> capsType)

Method Summary

Modifier and TypeMethod and Description
public final boolean
equals(final Object
the reference object with which to compare.
obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.
public final int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.
public final String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

capsTypeback to summary
public final Class<?> capsType
deviceTypeback to summary
public final Class<?> deviceType
hash32back to summary
private final int hash32

Constructor Detail

DeviceCapsTypeback to summary
public DeviceCapsType(final Class<?> deviceType, final Class<?> capsType)

Method Detail

equalsback to summary
public final boolean equals(final Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
hashCodeback to summary
public final int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
toStringback to summary
public final String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations
@Override