diff options
Diffstat (limited to 'src/nativewindow/classes/javax/media/nativewindow')
7 files changed, 292 insertions, 426 deletions
diff --git a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java index 0b0ee99f7..6fadd3e7e 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java +++ b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java @@ -39,45 +39,21 @@ package javax.media.nativewindow; -/** Specifies a set of OpenGL capabilities that a rendering context - must support, such as color depth and whether stereo is enabled. - It currently contains the minimal number of routines which allow - configuration on all supported window systems. */ +/** Specifies a set of capabilities that a window's rendering context + must support, such as color depth per channel. It currently + contains the minimal number of routines which allow configuration + on all supported window systems. */ -public class NWCapabilities implements Cloneable { - private boolean doubleBuffered = true; - private boolean stereo = false; - private boolean hardwareAccelerated = true; - private int depthBits = 24; - private int stencilBits = 0; +public class Capabilities implements Cloneable { private int redBits = 8; private int greenBits = 8; private int blueBits = 8; private int alphaBits = 0; - private int accumRedBits = 0; - private int accumGreenBits = 0; - private int accumBlueBits = 0; - private int accumAlphaBits = 0; - // Shift bits from PIXELFORMATDESCRIPTOR not present because they - // are unlikely to be supported on Windows anyway - // Support for full-scene antialiasing (FSAA) - private boolean sampleBuffers = false; - private int numSamples = 2; - - // Support for transparent windows containing OpenGL content - // (currently only has an effect on Mac OS X) - private boolean backgroundOpaque = true; - - // Bits for pbuffer creation - private boolean pbufferFloatingPointBuffers; - private boolean pbufferRenderToTexture; - private boolean pbufferRenderToTextureRectangle; - - /** Creates a NWCapabilities object. All attributes are in a default + /** Creates a Capabilities object. All attributes are in a default state. */ - public NWCapabilities() {} + public Capabilities() {} public Object clone() { try { @@ -87,56 +63,6 @@ public class NWCapabilities implements Cloneable { } } - /** Indicates whether double-buffering is enabled. */ - public boolean getDoubleBuffered() { - return doubleBuffered; - } - - /** Enables or disables double buffering. */ - public void setDoubleBuffered(boolean onOrOff) { - doubleBuffered = onOrOff; - } - - /** Indicates whether stereo is enabled. */ - public boolean getStereo() { - return stereo; - } - - /** Enables or disables stereo viewing. */ - public void setStereo(boolean onOrOff) { - stereo = onOrOff; - } - - /** Indicates whether hardware acceleration is enabled. */ - public boolean getHardwareAccelerated() { - return hardwareAccelerated; - } - - /** Enables or disables hardware acceleration. */ - public void setHardwareAccelerated(boolean onOrOff) { - hardwareAccelerated = onOrOff; - } - - /** Returns the number of bits requested for the depth buffer. */ - public int getDepthBits() { - return depthBits; - } - - /** Sets the number of bits requested for the depth buffer. */ - public void setDepthBits(int depthBits) { - this.depthBits = depthBits; - } - - /** Returns the number of bits requested for the stencil buffer. */ - public int getStencilBits() { - return stencilBits; - } - - /** Sets the number of bits requested for the stencil buffer. */ - public void setStencilBits(int stencilBits) { - this.stencilBits = stencilBits; - } - /** Returns the number of bits requested for the color buffer's red component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered. */ @@ -192,177 +118,15 @@ public class NWCapabilities implements Cloneable { public void setAlphaBits(int alphaBits) { this.alphaBits = alphaBits; } - - /** Returns the number of bits requested for the accumulation - buffer's red component. On some systems only the accumulation - buffer depth, which is the sum of the red, green, and blue bits, - is considered. */ - public int getAccumRedBits() { - return accumRedBits; - } - - /** Sets the number of bits requested for the accumulation buffer's - red component. On some systems only the accumulation buffer - depth, which is the sum of the red, green, and blue bits, is - considered. */ - public void setAccumRedBits(int accumRedBits) { - this.accumRedBits = accumRedBits; - } - - /** Returns the number of bits requested for the accumulation - buffer's green component. On some systems only the accumulation - buffer depth, which is the sum of the red, green, and blue bits, - is considered. */ - public int getAccumGreenBits() { - return accumGreenBits; - } - - /** Sets the number of bits requested for the accumulation buffer's - green component. On some systems only the accumulation buffer - depth, which is the sum of the red, green, and blue bits, is - considered. */ - public void setAccumGreenBits(int accumGreenBits) { - this.accumGreenBits = accumGreenBits; - } - - /** Returns the number of bits requested for the accumulation - buffer's blue component. On some systems only the accumulation - buffer depth, which is the sum of the red, green, and blue bits, - is considered. */ - public int getAccumBlueBits() { - return accumBlueBits; - } - - /** Sets the number of bits requested for the accumulation buffer's - blue component. On some systems only the accumulation buffer - depth, which is the sum of the red, green, and blue bits, is - considered. */ - public void setAccumBlueBits(int accumBlueBits) { - this.accumBlueBits = accumBlueBits; - } - - /** Returns the number of bits requested for the accumulation - buffer's alpha component. On some systems only the accumulation - buffer depth, which is the sum of the red, green, and blue bits, - is considered. */ - public int getAccumAlphaBits() { - return accumAlphaBits; - } - - /** Sets number of bits requested for accumulation buffer's alpha - component. On some systems only the accumulation buffer depth, - which is the sum of the red, green, and blue bits, is - considered. */ - public void setAccumAlphaBits(int accumAlphaBits) { - this.accumAlphaBits = accumAlphaBits; - } - - /** Indicates whether sample buffers for full-scene antialiasing - (FSAA) should be allocated for this drawable. Defaults to - false. */ - public void setSampleBuffers(boolean onOrOff) { - sampleBuffers = onOrOff; - } - - /** Returns whether sample buffers for full-scene antialiasing - (FSAA) should be allocated for this drawable. Defaults to - false. */ - public boolean getSampleBuffers() { - return sampleBuffers; - } - - /** If sample buffers are enabled, indicates the number of buffers - to be allocated. Defaults to 2. */ - public void setNumSamples(int numSamples) { - this.numSamples = numSamples; - } - - /** Returns the number of sample buffers to be allocated if sample - buffers are enabled. Defaults to 2. */ - public int getNumSamples() { - return numSamples; - } - - /** For pbuffers only, indicates whether floating-point buffers - should be used if available. Defaults to false. */ - public void setPbufferFloatingPointBuffers(boolean onOrOff) { - pbufferFloatingPointBuffers = onOrOff; - } - - /** For pbuffers only, returns whether floating-point buffers should - be used if available. Defaults to false. */ - public boolean getPbufferFloatingPointBuffers() { - return pbufferFloatingPointBuffers; - } - - /** For pbuffers only, indicates whether the render-to-texture - extension should be used if available. Defaults to false. */ - public void setPbufferRenderToTexture(boolean onOrOff) { - pbufferRenderToTexture = onOrOff; - } - - /** For pbuffers only, returns whether the render-to-texture - extension should be used if available. Defaults to false. */ - public boolean getPbufferRenderToTexture() { - return pbufferRenderToTexture; - } - - /** For pbuffers only, indicates whether the - render-to-texture-rectangle extension should be used if - available. Defaults to false. */ - public void setPbufferRenderToTextureRectangle(boolean onOrOff) { - pbufferRenderToTextureRectangle = onOrOff; - } - - /** For pbuffers only, returns whether the render-to-texture - extension should be used. Defaults to false. */ - public boolean getPbufferRenderToTextureRectangle() { - return pbufferRenderToTextureRectangle; - } - - /** For on-screen OpenGL contexts on some platforms, sets whether - the background of the context should be considered opaque. On - supported platforms, setting this to false, in conjunction with - other changes at the window toolkit level, can allow - hardware-accelerated OpenGL content inside of windows of - arbitrary shape. To achieve this effect it is necessary to use - an OpenGL clear color with an alpha less than 1.0. The default - value for this flag is <code>true</code>; setting it to false - may incur a certain performance penalty, so it is not - recommended to arbitrarily set it to false. */ - public void setBackgroundOpaque(boolean opaque) { - backgroundOpaque = opaque; - } - - /** Indicates whether the background of this OpenGL context should - be considered opaque. Defaults to true. - - @see #setBackgroundOpaque - */ - public boolean isBackgroundOpaque() { - return backgroundOpaque; - } - /** Returns a textual representation of this NWCapabilities + /** Returns a textual representation of this Capabilities object. */ public String toString() { - return ("NWCapabilities [" + - "DoubleBuffered: " + doubleBuffered + - ", Stereo: " + stereo + - ", HardwareAccelerated: " + hardwareAccelerated + - ", DepthBits: " + depthBits + - ", StencilBits: " + stencilBits + - ", Red: " + redBits + + return ("Capabilities [" + + "Red: " + redBits + ", Green: " + greenBits + ", Blue: " + blueBits + ", Alpha: " + alphaBits + - ", Red Accum: " + accumRedBits + - ", Green Accum: " + accumGreenBits + - ", Blue Accum: " + accumBlueBits + - ", Alpha Accum: " + accumAlphaBits + - ", Multisample: " + sampleBuffers + - (sampleBuffers ? ", Num samples: " + numSamples : "") + - ", Opaque: " + backgroundOpaque + " ]"); } } diff --git a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java index a980462f5..4d99216f0 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java +++ b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java @@ -40,14 +40,14 @@ package javax.media.nativewindow; /** Provides a mechanism by which applications can customize the - window type selection for a given {@link NWCapabilities}. + window type selection for a given {@link Capabilities}. Developers can implement this interface and pass an instance into - the appropriate method of {@link GLDrawableFactory}; the chooser - will be called during the OpenGL context creation process. */ + the appropriate method of {@link NativeWindowFactory}; the chooser + will be called at window creation time, on some platforms. */ -public interface NWCapabilitiesChooser { +public interface CapabilitiesChooser { /** Chooses the index (0..available.length - 1) of the {@link - NWCapabilities} most closely matching the desired one from the + Capabilities} most closely matching the desired one from the list of all supported. Some of the entries in the <code>available</code> array may be null; the chooser must ignore these. The <em>windowSystemRecommendedChoice</em> @@ -56,12 +56,14 @@ public interface NWCapabilitiesChooser { not necessarily required, that the chooser select that entry. <P> <em>Note:</em> this method is called automatically by the - {@link GLDrawableFactory} when an instance of this class is - passed in to one of its factory methods. It should generally not - be invoked by users directly, unless it is desired to delegate - the choice to some other NWCapabilitiesChooser object. + {@link NativeWindowFactory} when an instance of this class is + passed in to its {@link + NativeWindowFactory#chooseGraphicsConfiguration + chooseGraphicsConfiguration} method. It should generally not be + invoked by users directly, unless it is desired to delegate the + choice to some other CapabilitiesChooser object. */ - public int chooseCapabilities(NWCapabilities desired, - NWCapabilities[] available, + public int chooseCapabilities(Capabilities desired, + Capabilities[] available, int windowSystemRecommendedChoice); } diff --git a/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java b/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java index 0e18a301d..cead0a4a8 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java +++ b/src/nativewindow/classes/javax/media/nativewindow/DefaultCapabilitiesChooser.java @@ -40,48 +40,31 @@ package javax.media.nativewindow; /** <P> The default implementation of the {@link - NWCapabilitiesChooser} interface, which provides consistent visual + CapabilitiesChooser} interface, which provides consistent visual selection behavior across platforms. The precise algorithm is deliberately left loosely specified. Some properties are: </P> - <UL> - - <LI> As long as there is at least one available non-null - NWCapabilities which matches the "stereo" option, will return a - valid index. - <LI> Attempts to match as closely as possible the given - NWCapabilities, but will select one with fewer capabilities (i.e., + Capabilities, but will select one with fewer capabilities (i.e., lower color depth) if necessary. - <LI> Prefers hardware-accelerated visuals to - non-hardware-accelerated. - <LI> If there is no exact match, prefers a more-capable visual to a less-capable one. <LI> If there is more than one exact match, chooses an arbitrary one. - <LI> May select the opposite of a double- or single-buffered - visual (based on the user's request) in dire situations. - - <LI> Color depth (including alpha) mismatches are weighted higher - than depth buffer mismatches, which are in turn weighted higher - than accumulation buffer (including alpha) and stencil buffer - depth mismatches. - <LI> If a valid windowSystemRecommendedChoice parameter is supplied, chooses that instead of using the cross-platform code. </UL> */ -public class DefaultNWCapabilitiesChooser implements NWCapabilitiesChooser { - private static final boolean DEBUG = false; // FIXME: Debug.debug("DefaultNWCapabilitiesChooser"); +public class DefaultCapabilitiesChooser implements CapabilitiesChooser { + private static final boolean DEBUG = false; // FIXME: Debug.debug("DefaultCapabilitiesChooser"); - public int chooseCapabilities(NWCapabilities desired, - NWCapabilities[] available, + public int chooseCapabilities(Capabilities desired, + Capabilities[] available, int windowSystemRecommendedChoice) { if (DEBUG) { System.err.println("Desired: " + desired); @@ -104,86 +87,23 @@ public class DefaultNWCapabilitiesChooser implements NWCapabilitiesChooser { // Create score array int[] scores = new int[available.length]; int NO_SCORE = -9999999; - int DOUBLE_BUFFER_MISMATCH_PENALTY = 1000; - int STENCIL_MISMATCH_PENALTY = 500; - // Pseudo attempt to keep equal rank penalties scale-equivalent - // (e.g., stencil mismatch is 3 * accum because there are 3 accum - // components) int COLOR_MISMATCH_PENALTY_SCALE = 36; - int DEPTH_MISMATCH_PENALTY_SCALE = 6; - int ACCUM_MISMATCH_PENALTY_SCALE = 1; - int STENCIL_MISMATCH_PENALTY_SCALE = 3; for (int i = 0; i < scores.length; i++) { scores[i] = NO_SCORE; } // Compute score for each for (int i = 0; i < scores.length; i++) { - NWCapabilities cur = available[i]; + Capabilities cur = available[i]; if (cur == null) { continue; } - if (desired.getStereo() != cur.getStereo()) { - continue; - } int score = 0; // Compute difference in color depth - // (Note that this decides the direction of all other penalties) score += (COLOR_MISMATCH_PENALTY_SCALE * ((cur.getRedBits() + cur.getGreenBits() + cur.getBlueBits() + cur.getAlphaBits()) - (desired.getRedBits() + desired.getGreenBits() + desired.getBlueBits() + desired.getAlphaBits()))); - // Compute difference in depth buffer depth - score += (DEPTH_MISMATCH_PENALTY_SCALE * sign(score) * - Math.abs(cur.getDepthBits() - desired.getDepthBits())); - // Compute difference in accumulation buffer depth - score += (ACCUM_MISMATCH_PENALTY_SCALE * sign(score) * - Math.abs((cur.getAccumRedBits() + cur.getAccumGreenBits() + cur.getAccumBlueBits() + cur.getAccumAlphaBits()) - - (desired.getAccumRedBits() + desired.getAccumGreenBits() + desired.getAccumBlueBits() + desired.getAccumAlphaBits()))); - // Compute difference in stencil bits - score += STENCIL_MISMATCH_PENALTY_SCALE * sign(score) * (cur.getStencilBits() - desired.getStencilBits()); - if (cur.getDoubleBuffered() != desired.getDoubleBuffered()) { - score += sign(score) * DOUBLE_BUFFER_MISMATCH_PENALTY; - } - if ((desired.getStencilBits() > 0) && (cur.getStencilBits() == 0)) { - score += sign(score) * STENCIL_MISMATCH_PENALTY; - } scores[i] = score; } - // Now prefer hardware-accelerated visuals by pushing scores of - // non-hardware-accelerated visuals out - boolean gotHW = false; - int maxAbsoluteHWScore = 0; - for (int i = 0; i < scores.length; i++) { - int score = scores[i]; - if (score == NO_SCORE) { - continue; - } - NWCapabilities cur = available[i]; - if (cur.getHardwareAccelerated()) { - int absScore = Math.abs(score); - if (!gotHW || - (absScore > maxAbsoluteHWScore)) { - gotHW = true; - maxAbsoluteHWScore = absScore; - } - } - } - if (gotHW) { - for (int i = 0; i < scores.length; i++) { - int score = scores[i]; - if (score == NO_SCORE) { - continue; - } - NWCapabilities cur = available[i]; - if (!cur.getHardwareAccelerated()) { - if (score <= 0) { - score -= maxAbsoluteHWScore; - } else if (score > 0) { - score += maxAbsoluteHWScore; - } - scores[i] = score; - } - } - } if (DEBUG) { System.err.print("Scores: ["); @@ -213,7 +133,7 @@ public class DefaultNWCapabilitiesChooser implements NWCapabilitiesChooser { } } if (chosenIndex < 0) { - throw new NativeWindowException("Unable to select one of the provided NWCapabilities"); + throw new NativeWindowException("Unable to select one of the provided Capabilities"); } if (DEBUG) { System.err.println("Chosen index: " + chosenIndex); diff --git a/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java new file mode 100644 index 000000000..afddaf7aa --- /dev/null +++ b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java @@ -0,0 +1,180 @@ +/* + * Copyright (c) 2008-2009 Sun Microsystems, Inc. All Rights Reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * - Redistribution of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistribution in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * Neither the name of Sun Microsystems, Inc. or the names of + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * This software is provided "AS IS," without a warranty of any kind. ALL + * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, + * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A + * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN + * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR + * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR + * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR + * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR + * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE + * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, + * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF + * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + */ + +package javax.media.nativewindow; + +import java.lang.reflect.*; +import java.util.*; + +import com.sun.nativewindow.impl.*; + +/** + * Provides the mechanism by which the graphics configuration for a + * given window can be chosen before the window is created. On some + * window systems (X11 in particular) the graphics configuration + * decides parameters related to hardware accelerated rendering such + * as the OpenGL pixel format. On these platforms it is necessary to + * choose the graphics configuration early. 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 {@link NativeWindowFactory} so that + * new window toolkits can replace just the {@link + * NativeWindowFactory} and reuse the graphics configuration selection + * algorithm provided by, for example, an OpenGL binding. + */ + +public abstract class GraphicsConfigurationFactory { + private static Map/*<Class, NativeWindowFactory>*/ registeredFactories = + Collections.synchronizedMap(new HashMap()); + private static Class abstractGraphicsDeviceClass; + + static { + initialize(); + } + + /** Creates a new NativeWindowFactory instance. End users do not + need to call this method. */ + protected GraphicsConfigurationFactory() { + } + + private static void initialize() { + String osName = System.getProperty("os.name"); + String osNameLowerCase = osName.toLowerCase(); + String factoryClassName = null; + + abstractGraphicsDeviceClass = javax.media.nativewindow.AbstractGraphicsDevice.class; + + if (!osNameLowerCase.startsWith("wind") && + !osNameLowerCase.startsWith("mac os x")) { + // Assume X11 platform -- should probably test for these explicitly + try { + GraphicsConfigurationFactory factory = (GraphicsConfigurationFactory) + NWReflection.createInstance("com.sun.nativewindow.impl.x11.X11GraphicsConfigurationFactory", new Object[] {}); + registerFactory(javax.media.nativewindow.x11.X11GraphicsDevice.class, factory); + } catch (Exception e) { + throw new RuntimeException(e); + } + } + // Register the default no-op factory for arbitrary + // AbstractGraphicsDevice implementations, including + // AWTGraphicsDevice instances -- the OpenGL binding will take + // care of handling AWTGraphicsDevices on X11 platforms (as + // well as X11GraphicsDevices in non-AWT situations) + registerFactory(abstractGraphicsDeviceClass, new GraphicsConfigurationFactoryImpl()); + } + + /** Returns the factory for use with the given type of + AbstractGraphicsDevice. */ + public static GraphicsConfigurationFactory getFactory(AbstractGraphicsDevice device) { + if (device == null) { + return getFactory(AbstractGraphicsDevice.class); + } + return getFactory(device.getClass()); + } + + /** + * Returns the graphics configuration factory for use with the + * given class, which must implement the {@link + * AbstractGraphicsDevice} interface. + * + * @throws IllegalArgumentException if the given class does not implement AbstractGraphicsDevice + */ + public static GraphicsConfigurationFactory getFactory(Class abstractGraphicsDeviceImplementor) + throws IllegalArgumentException, NativeWindowException + { + if (!(abstractGraphicsDeviceClass.isAssignableFrom(abstractGraphicsDeviceImplementor))) { + throw new IllegalArgumentException("Given class must implement AbstractGraphicsDevice"); + } + Class clazz = abstractGraphicsDeviceImplementor; + while (clazz != null) { + GraphicsConfigurationFactory factory = + (GraphicsConfigurationFactory) registeredFactories.get(clazz); + if (factory != null) { + return factory; + } + clazz = clazz.getSuperclass(); + } + // Return the default + return (GraphicsConfigurationFactory) registeredFactories.get(abstractGraphicsDeviceClass); + } + + /** Registers a GraphicsConfigurationFactory handling graphics + * device objects of the given class. This does not need to be + * called by end users, only implementors of new + * GraphicsConfigurationFactory subclasses. + * + * @throws IllegalArgumentException if the given class does not implement AbstractGraphicsDevice + */ + protected static void registerFactory(Class abstractGraphicsDeviceImplementor, GraphicsConfigurationFactory factory) + throws IllegalArgumentException + { + if (!(abstractGraphicsDeviceClass.isAssignableFrom(abstractGraphicsDeviceImplementor))) { + throw new IllegalArgumentException("Given class must implement AbstractGraphicsDevice"); + } + registeredFactories.put(abstractGraphicsDeviceImplementor, factory); + } + + /** + * <P> Selects a graphics configuration on the specified graphics + * device compatible with the supplied {@link Capabilities}. Some + * platforms (specifically X11) require the graphics configuration + * to be specified when the native window is created. This method + * is mainly intended to be both used and implemented by the + * OpenGL binding, and may return null on platforms on which the + * OpenGL pixel format selection process is performed later or in + * other unspecified situations. </P> + * + * <P> 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 {@link + * AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link + * AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. On + * X11 platforms where the AWT is not in use, it also accepts + * {@link javax.media.nativewindow.x11.X11GraphicsDevice + * X11GraphicsDevice} objects and returns {@link + * javax.media.nativewindow.x11.X11GraphicsConfiguration + * X11GraphicsConfiguration} objects.</P> + * + * @throws IllegalArgumentException if the data type of the passed + * AbstractGraphicsDevice is not supported by this + * NativeWindowFactory. + * @throws NativeWindowException if any window system-specific errors caused + * the selection of the graphics configuration to fail. + */ + public abstract AbstractGraphicsConfiguration + chooseGraphicsConfiguration(Capabilities capabilities, + CapabilitiesChooser chooser, + AbstractGraphicsDevice device) + throws IllegalArgumentException, NativeWindowException; +} diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java index 99b301997..75e8552f9 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java +++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java @@ -39,19 +39,18 @@ package javax.media.nativewindow; -/** Provides the mechanism by which the Java / OpenGL binding - interacts with windows. A window toolkit such as the AWT may - either implement this interface directly with one of its - components, or provide and register an implementation of {@link - NativeWindowFactory NativeWindowFactory} which can create - NativeWindow objects for its components. <P> +/** Provides the low-level information required for + hardware-accelerated rendering in a platform-independent manner. A + window toolkit such as the AWT may either implement this interface + directly with one of its components, or provide and register an + implementation of {@link NativeWindowFactory NativeWindowFactory} + which can create NativeWindow objects for its components. <P> A NativeWindow created for a particular on-screen component is expected to have the same lifetime as that component. As long as the component is alive, the NativeWindow must be able to control it, and any time it is visible and locked, provide information - such as the window handle to the Java / OpenGL binding so that - GLDrawables and GLContexts may be created for the window. + such as the window handle. */ public interface NativeWindow { @@ -107,9 +106,21 @@ public interface NativeWindow { public long getSurfaceHandle(); /** - * Lifetime: after 1st lock, until invalidation + * Returns the graphics configuration corresponding to this window. + * The graphics configuration is most relevant on X11 platforms + * where it also decides other properties related to hardware + * accelerated rendering such as the OpenGL pixel format. This + * method may return null on platforms where it is not needed, and + * is only guaranteed to return a valid value while the window is + * locked. + */ + public AbstractGraphicsConfiguration getGraphicsConfiguration(); + + /** + * Returns the index of the screen on which this window currently + * lies. This method is only guaranteed to return a valid value + * while the window is locked. */ - public long getVisualID(); public int getScreenIndex(); /** Returns the current width of this window. */ diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java index fc9235075..80ee97081 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java +++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. + * Copyright (c) 2008-2009 Sun Microsystems, Inc. All Rights Reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are @@ -32,23 +32,22 @@ package javax.media.nativewindow; -import javax.media.nativewindow.*; import java.lang.reflect.*; import java.security.*; import java.util.*; import com.sun.nativewindow.impl.*; -/** Provides the link between the window toolkit and the Java binding - to the OpenGL API. The NativeWindowFactory, and NativeWindow - instances it creates, encompass all of the toolkit-specific - functionality, leaving the GLDrawableFactory independent of any - particular toolkit. */ +/** Provides a pluggable mechanism for arbitrary window toolkits to + adapt their components to the {@link NativeWindow} interface, + which provides a platform-independent mechanism of accessing the + information required to perform operations like + hardware-accelerated rendering using the OpenGL API. */ public abstract class NativeWindowFactory { private static NativeWindowFactory defaultFactory; - private static HashMap/*<Class, NativeWindowFactory>*/ registeredFactories = - new HashMap(); + private static Map/*<Class, NativeWindowFactory>*/ registeredFactories = + Collections.synchronizedMap(new HashMap()); private static Class nativeWindowClass; /** Creates a new NativeWindowFactory instance. End users do not @@ -56,40 +55,54 @@ public abstract class NativeWindowFactory { protected NativeWindowFactory() { } - static { - initialize(); - } - + private static boolean initialized = false; private static void initialize() { - String osName = System.getProperty("os.name"); - String osNameLowerCase = osName.toLowerCase(); - String factoryClassName = null; + synchronized (NativeWindowFactory.class) { + if (initialized) { + return; + } + initialized = true; - // We break compile-time dependencies on the AWT here to - // make it easier to run this code on mobile devices + String osName = System.getProperty("os.name"); + String osNameLowerCase = osName.toLowerCase(); + String factoryClassName = null; - NativeWindowFactory factory = new NativeWindowFactoryImpl(); - nativeWindowClass = javax.media.nativewindow.NativeWindow.class; - registerFactory(nativeWindowClass, factory); - defaultFactory = factory; + // We break compile-time dependencies on the AWT here to + // make it easier to run this code on mobile devices + + NativeWindowFactory factory = new NativeWindowFactoryImpl(); + nativeWindowClass = javax.media.nativewindow.NativeWindow.class; + registerFactory(nativeWindowClass, factory); + defaultFactory = factory; - Class componentClass = null; - try { - componentClass = Class.forName("java.awt.Component"); - } catch (Exception e) { - } - if (componentClass != null) { - if (!osNameLowerCase.startsWith("wind") && - !osNameLowerCase.startsWith("mac os x")) { - // Assume X11 platform -- should probably test for these explicitly - try { - Constructor factoryConstructor = - NWReflection.getConstructor("com.sun.nativewindow.impl.x11.awt.X11AWTNativeWindowFactory", new Class[] {}); - factory = (NativeWindowFactory) factoryConstructor.newInstance(null); - } catch (Exception e) { } + Class componentClass = null; + try { + componentClass = Class.forName("java.awt.Component"); + } catch (Exception e) { + } + if (componentClass != null) { + if (!osNameLowerCase.startsWith("wind") && + !osNameLowerCase.startsWith("mac os x")) { + // Assume X11 platform -- should probably test for these explicitly + boolean exceptionOccurred = true; + try { + Constructor factoryConstructor = + NWReflection.getConstructor("com.sun.nativewindow.impl.x11.awt.X11AWTNativeWindowFactory", new Class[] {}); + factory = (NativeWindowFactory) factoryConstructor.newInstance(null); + exceptionOccurred = false; + } catch (Exception e) { } + if (exceptionOccurred) { + // Try the non-AWT X11 native window factory + try { + Constructor factoryConstructor = + NWReflection.getConstructor("com.sun.nativewindow.impl.x11.X11NativeWindowFactory", new Class[] {}); + factory = (NativeWindowFactory) factoryConstructor.newInstance(null); + } catch (Exception e) { } + } + } + registerFactory(componentClass, factory); + defaultFactory = factory; } - registerFactory(componentClass, factory); - defaultFactory = factory; } } @@ -105,6 +118,7 @@ public abstract class NativeWindowFactory { within the Java binding to OpenGL. By default, if the AWT is available, the default toolkit will support the AWT. */ public static void setDefaultFactory(NativeWindowFactory factory) { + initialize(); defaultFactory = factory; } @@ -120,6 +134,7 @@ public abstract class NativeWindowFactory { within the Java binding to OpenGL. By default, if the AWT is available, the default toolkit will support the AWT. */ public static NativeWindowFactory getDefaultFactory() { + initialize(); return defaultFactory; } @@ -130,6 +145,7 @@ public abstract class NativeWindowFactory { NativeWindow implementation, or it might be that of a toolkit class like {@link java.awt.Component Component}. */ public static NativeWindowFactory getFactory(Class windowClass) throws IllegalArgumentException { + initialize(); if (nativeWindowClass.isAssignableFrom(windowClass)) { return (NativeWindowFactory) registeredFactories.get(nativeWindowClass); } @@ -146,8 +162,9 @@ public abstract class NativeWindowFactory { /** Registers a NativeWindowFactory handling window objects of the given class. This does not need to be called by end users, - only implementors of new NativeWindowFactory subclasses, .. */ + only implementors of new NativeWindowFactory subclasses. */ protected static void registerFactory(Class windowClass, NativeWindowFactory factory) { + initialize(); registeredFactories.put(windowClass, factory); } @@ -173,38 +190,6 @@ public abstract class NativeWindowFactory { return getFactory(winObj.getClass()).getNativeWindowImpl(winObj); } - /** - * <P> Selects a graphics configuration on the specified graphics - * device compatible with the supplied NWCapabilities. This method - * is intended to be used by applications which do not use the - * supplied GLCanvas class but instead wrap their own Canvas or - * other window toolkit-specific object with a GLDrawable. Some - * platforms (specifically X11) require the graphics configuration - * to be specified when the window toolkit object is created. This - * method may return null on platforms on which the OpenGL pixel - * format selection process is performed later. </P> - * - * <P> 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 {@link - * AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link - * AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. </P> - * - * @see java.awt.Canvas#Canvas(java.awt.GraphicsConfiguration) - * - * @throws IllegalArgumentException if the data type of the passed - * AbstractGraphicsDevice is not supported by this - * NativeWindowFactory. - * @throws NWException if any window system-specific errors caused - * the selection of the graphics configuration to fail. - */ - public abstract AbstractGraphicsConfiguration - chooseGraphicsConfiguration(NWCapabilities capabilities, - NWCapabilitiesChooser chooser, - AbstractGraphicsDevice device) - throws IllegalArgumentException, NWException; - /** Performs the conversion from a toolkit's window object to a NativeWindow. Implementors of concrete NativeWindowFactory subclasses should override this method. */ diff --git a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java index c40f26a94..1cf4da42a 100644 --- a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java +++ b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java @@ -52,4 +52,8 @@ public class X11GraphicsConfiguration implements AbstractGraphicsConfiguration { public long getVisualID() { return visualID; } + + public String toString() { + return "[X11GraphicsConfiguration visualID = " + visualID + "]"; + } } |