javax.media.nativewindow

## Class GraphicsConfigurationFactory

- java.lang.Object
- - javax.media.nativewindow.GraphicsConfigurationFactory

-     public abstract class GraphicsConfigurationFactory
      extends Object

  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.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `AbstractGraphicsConfiguration` | `chooseGraphicsConfiguration(CapabilitiesImmutable capsChosen, CapabilitiesImmutable capsRequested, CapabilitiesChooser chooser, AbstractGraphicsScreen screen, int nativeVisualID)` Selects a graphics configuration on the specified graphics device compatible with the supplied `Capabilities`.
    `static GraphicsConfigurationFactory` | `getFactory(AbstractGraphicsDevice device, CapabilitiesImmutable caps)` Returns the graphics configuration factory for use with the given device and capability.
    `static GraphicsConfigurationFactory` | `getFactory(Class<?> deviceType, Class<?> capabilitiesType)` Returns the graphics configuration factory for use with the given device and capability class.
    `static void` | `initSingleton()`
    `static void` | `shutdown()`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### initSingleton

          public static void initSingleton()

    - #### shutdown

          public static void shutdown()

    - #### getFactory

          public static GraphicsConfigurationFactory getFactory(AbstractGraphicsDevice device,
                                                CapabilitiesImmutable caps)

      Returns the graphics configuration factory for use with the given device and capability.
      See Also:
        `getFactory(Class, Class)`

    - #### getFactory

          public static GraphicsConfigurationFactory getFactory(Class<?> deviceType,
                                                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` - the minimum capabilities class type accepted, must implement or extend `AbstractGraphicsDevice`
        `capabilitiesType` - the minimum capabilities class type accepted, must implement or extend `CapabilitiesImmutable`
      Throws:
        `IllegalArgumentException` - if the deviceType does not implement `AbstractGraphicsDevice` or capabilitiesType does not implement `CapabilitiesImmutable`
        `NativeWindowException`

    - #### chooseGraphicsConfiguration

          public final AbstractGraphicsConfiguration chooseGraphicsConfiguration(CapabilitiesImmutable capsChosen,
                                                                  CapabilitiesImmutable capsRequested,
                                                                  CapabilitiesChooser chooser,
                                                                  AbstractGraphicsScreen screen,
                                                                  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` - the intermediate chosen capabilities to be refined by this implementation, may be equal to capsRequested
        `capsRequested` - the original requested capabilities
        `chooser` - the choosing implementation
        `screen` - the referring Screen
        `nativeVisualID` - if not `VisualIDHolder.VID_UNDEFINED` it reflects a pre-chosen visualID of the native platform's windowing system.
      Returns:
        the complete GraphicsConfiguration
      Throws:
        `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:
        `javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)`, `javax.media.nativewindow.DefaultGraphicsConfiguration#setChosenCapabilities(Capabilities caps)`

Copyright 2010 JogAmp Community.