JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
NewtFactory.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 * Copyright (c) 2010 JogAmp Community. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * - Redistribution of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * - Redistribution in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * Neither the name of Sun Microsystems, Inc. or the names of
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * This software is provided "AS IS," without a warranty of any kind. ALL
21 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
22 * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
23 * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
24 * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
25 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
26 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
27 * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
28 * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
29 * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
30 * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
31 * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
32 *
33 */
34
35package com.jogamp.newt;
36
37import java.security.PrivilegedAction;
38import java.util.Arrays;
39
40import com.jogamp.nativewindow.AbstractGraphicsConfiguration;
41import com.jogamp.nativewindow.AbstractGraphicsDevice;
42import com.jogamp.nativewindow.AbstractGraphicsScreen;
43import com.jogamp.nativewindow.CapabilitiesImmutable;
44import com.jogamp.nativewindow.NativeWindow;
45import com.jogamp.nativewindow.NativeWindowException;
46import com.jogamp.nativewindow.NativeWindowFactory;
47
48import com.jogamp.common.util.IOUtil;
49import com.jogamp.common.util.PropertyAccess;
50import com.jogamp.common.util.SecurityUtil;
51
52import jogamp.newt.Debug;
53import jogamp.newt.DisplayImpl;
54import jogamp.newt.ScreenImpl;
55import jogamp.newt.WindowImpl;
56
57public class NewtFactory {
58 public static final boolean DEBUG_IMPLEMENTATION = Debug.debug("Window");
59
60 public static final String DRIVER_DEFAULT_ROOT_PACKAGE = "jogamp.newt.driver";
61
62 private static IOUtil.ClassResources defaultWindowIcons;
63 private static String sysPaths = "jogamp/newt/assets/jogamp-16x16.png jogamp/newt/assets/jogamp-32x32.png";
64
65 static {
66 SecurityUtil.doPrivileged(new PrivilegedAction<Object>() {
67 @Override
68 public Object run() {
69 NativeWindowFactory.initSingleton(); // last resort ..
70 {
71 /** See API Doc in {@link Window} ! */
72 final String[] paths = PropertyAccess.getProperty("newt.window.icons", true, sysPaths).split("[\\s,]");
73 if( paths.length < 2 ) {
74 throw new IllegalArgumentException("Property 'newt.window.icons' did not specify at least two PNG icons, but "+Arrays.toString(paths));
75 }
76 defaultWindowIcons = new IOUtil.ClassResources(paths, NewtFactory.class.getClassLoader(), null);
77 }
78 return null;
79 } } );
80 }
81
82 /**
83 * Returns the application window icon resources to be used.
84 * <p>
85 * Property <code>newt.window.icons</code> may define a list of PNG icons separated by one whitespace or one comma character.
86 * Shall reference at least two PNG icons, from lower (16x16) to higher (>= 32x32) resolution.
87 * </p>
88 * <p>
89 * Users may also specify application window icons using {@link #setWindowIcons(com.jogamp.common.util.IOUtil.ClassResources)}.
90 * </p>
91 */
92 public static IOUtil.ClassResources getWindowIcons() { return defaultWindowIcons; }
93
94 /**
95 * Allow user to set custom window icons, only applicable at application start before creating any NEWT instance.
96 * <p>
97 * Shall reference at least two PNG icons, from lower (16x16) to higher (>= 32x32) resolution.
98 * </p>
99 */
100 public static void setWindowIcons(final IOUtil.ClassResources cres) { defaultWindowIcons = cres; }
101
102 public static Class<?> getCustomClass(final String packageName, final String classBaseName) {
103 Class<?> clazz = null;
104 final String clazzName;
105 if(packageName!=null && classBaseName!=null) {
106 if( packageName.startsWith(".") ) {
107 clazzName = DRIVER_DEFAULT_ROOT_PACKAGE + packageName + "." + classBaseName ;
108 } else {
109 clazzName = packageName + "." + classBaseName ;
110 }
111 try {
112 clazz = Class.forName(clazzName);
113 } catch (final Throwable t) {
114 throw new NativeWindowException("Failed to find or initialize class <"+packageName+"."+classBaseName+"> -> <"+clazzName+">: "+t.getMessage(), t);
115 }
116 } else {
117 clazzName = null;
118 }
119 if( null == clazz ) {
120 throw new NativeWindowException("Failed to determine class <"+packageName+"."+classBaseName+"> -> <"+clazzName+">");
121 }
122 return clazz;
123 }
124
125 private static boolean useEDT = true;
126
127 /**
128 * Toggles the usage of an EventDispatchThread while creating a Display.<br>
129 * The default is enabled.<br>
130 * The EventDispatchThread is thread local to the Display instance.<br>
131 */
132 public static synchronized void setUseEDT(final boolean onoff) {
133 useEDT = onoff;
134 }
135
136 /** @see #setUseEDT(boolean) */
137 public static boolean useEDT() { return useEDT; }
138
139 /**
140 * Create a Display entity.
141 * <p>
142 * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
143 * </p>
144 * <p>
145 * An already existing display connection of the same <code>name</code> will be reused.
146 * </p>
147 * @param name the display connection name which is a technical platform specific detail,
148 * see {@link AbstractGraphicsDevice#getConnection()}. Use <code>null</code> for default.
149 * @return the new or reused Display instance
150 */
151 public static Display createDisplay(final String name) {
152 return createDisplay(name, true);
153 }
154
155 /**
156 * Create a Display entity.
157 * <p>
158 * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
159 * </p>
160 * <p>
161 * An already existing display connection of the same <code>name</code> will be reused
162 * <b>if</b> <code>reuse</code> is <code>true</code>, otherwise a new instance is being created.
163 * </p>
164 * @param name the display connection name which is a technical platform specific detail,
165 * see {@link AbstractGraphicsDevice#getConnection()}. Use <code>null</code> for default.
166 * @param reuse attempt to reuse an existing Display with same <code>name</code> if set true, otherwise create a new instance.
167 * @return the new or reused Display instance
168 */
169 public static Display createDisplay(final String name, final boolean reuse) {
170 return DisplayImpl.create(NativeWindowFactory.getNativeWindowType(true), name, 0, reuse);
171 }
172
173 /**
174 * Create a Display entity.
175 * <p>
176 * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
177 * </p>
178 * <p>
179 * An already existing display connection of the same <code>name</code> will be reused.
180 * </p>
181 * @param type explicit NativeWindow type eg. {@link NativeWindowFactory#TYPE_AWT}
182 * @param name the display connection name which is a technical platform specific detail,
183 * see {@link AbstractGraphicsDevice#getConnection()}. Use <code>null</code> for default.
184 * @return the new or reused Display instance
185 */
186 public static Display createDisplay(final String type, final String name) {
187 return createDisplay(type, name, true);
188 }
189
190 /**
191 * Create a Display entity.
192 * <p>
193 * Native creation is lazily done at usage, ie. {@link Display#addReference()}.
194 * </p>
195 * <p>
196 * An already existing display connection of the same <code>name</code> will be reused
197 * <b>if</b> <code>reuse</code> is <code>true</code>, otherwise a new instance is being created.
198 * </p>
199 * @param type explicit NativeWindow type eg. {@link NativeWindowFactory#TYPE_AWT}
200 * @param name the display connection name which is a technical platform specific detail,
201 * see {@link AbstractGraphicsDevice#getConnection()}. Use <code>null</code> for default.
202 * @param reuse attempt to reuse an existing Display with same <code>name</code> if set true, otherwise create a new instance.
203 * @return the new or reused Display instance
204 */
205 public static Display createDisplay(final String type, final String name, final boolean reuse) {
206 return DisplayImpl.create(type, name, 0, reuse);
207 }
208
209 /**
210 * Create a Screen entity.
211 * <p>
212 * Native creation is lazily done at usage, ie. {@link Screen#addReference()}.
213 * </p>
214 * <p>
215 * The lifecycle of this Screen's Display is handled via {@link Display#addReference()}
216 * and {@link Display#removeReference()}.
217 * </p>
218 */
219 public static Screen createScreen(final Display display, final int index) {
220 return ScreenImpl.create(display, index);
221 }
222
223 /**
224 * Create a top level Window entity on the default Display and default Screen.
225 * <p>
226 * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}.
227 * </p>
228 * <p>
229 * An already existing default Display will be reused.
230 * </p>
231 * <p>
232 * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
233 * and {@link Screen#removeReference()}.
234 * </p>
235 */
236 public static Window createWindow(final CapabilitiesImmutable caps) {
237 return createWindowImpl(NativeWindowFactory.getNativeWindowType(true), caps);
238 }
239
240 /**
241 * Create a top level Window entity.
242 * <p>
243 * Native creation is lazily done at usage, ie. {@link Window#setVisible(boolean)}.
244 * </p>
245 * <p>
246 * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
247 * and {@link Screen#removeReference()}.
248 * </p>
249 */
250 public static Window createWindow(final Screen screen, final CapabilitiesImmutable caps) {
251 return WindowImpl.create(null, 0, screen, caps);
252 }
253
254 /**
255 * Create a child Window entity attached to the given parent.<br>
256 * The Screen and Display information is regenerated utilizing the parents information,
257 * while reusing an existing Display.<br>
258 * <p>
259 * In case <code>parentWindowObject</code> is a {@link com.jogamp.newt.Window} instance,<br>
260 * the new window is added to it's list of children.<br>
261 * This assures proper handling of visibility, creation and destruction.<br>
262 * {@link com.jogamp.newt.event.WindowEvent#EVENT_WINDOW_RESIZED} is not propagated to the child window for layout<br>,
263 * you have to add an appropriate {@link com.jogamp.newt.event.WindowListener} for this use case.<br>
264 * The parents visibility is passed to the new Window<br></p>
265 * <p>
266 * In case <code>parentWindowObject</code> is a different {@link com.jogamp.nativewindow.NativeWindow} implementation,<br>
267 * you have to handle all events appropriate.<br></p>
268 * <p>
269 * <p>
270 * The lifecycle of this Window's Screen and Display is handled via {@link Screen#addReference()}
271 * and {@link Screen#removeReference()}.
272 * </p>
273 *
274 * @param parentWindowObject either a NativeWindow instance
275 */
276 public static Window createWindow(final NativeWindow parentWindow, final CapabilitiesImmutable caps) {
277 final String type = NativeWindowFactory.getNativeWindowType(true);
278 if( null == parentWindow ) {
279 return createWindowImpl(type, caps);
280 }
281 Screen screen = null;
282 Window newtParentWindow = null;
283
284 if ( parentWindow instanceof Window ) {
285 // use parent NEWT Windows Display/Screen
286 newtParentWindow = (Window) parentWindow ;
287 screen = newtParentWindow.getScreen();
288 } else {
289 // create a Display/Screen compatible to the NativeWindow
290 final AbstractGraphicsConfiguration parentConfig = parentWindow.getGraphicsConfiguration();
291 if(null!=parentConfig) {
292 final AbstractGraphicsScreen parentScreen = parentConfig.getScreen();
293 final AbstractGraphicsDevice parentDevice = parentScreen.getDevice();
294 final Display display = NewtFactory.createDisplay(type, parentDevice.getHandle(), true);
295 screen = NewtFactory.createScreen(display, parentScreen.getIndex());
296 } else {
297 final Display display = NewtFactory.createDisplay(type, null, true); // local display
298 screen = NewtFactory.createScreen(display, 0); // screen 0
299 }
300 }
301 final Window win = WindowImpl.create(parentWindow, 0, screen, caps);
302
303 win.setSize(parentWindow.getWidth(), parentWindow.getHeight());
304 if ( null != newtParentWindow ) {
305 newtParentWindow.addChild(win);
306 win.setVisible(newtParentWindow.isVisible());
307 }
308 return win;
309 }
310
311 private static Window createWindowImpl(final String type, final CapabilitiesImmutable caps) {
312 final Display display = NewtFactory.createDisplay(type, null, true); // local display
313 final Screen screen = NewtFactory.createScreen(display, 0); // screen 0
314 return WindowImpl.create(null, 0, screen, caps);
315 }
316
317 /**
318 * Create a child Window entity attached to the given parent, incl native creation<br>
319 *
320 * @param displayConnection the parent window's display connection
321 * @param screenIdx the desired screen index
322 * @param parentWindowHandle the native parent window handle
323 * @param caps the desired capabilities
324 * @return
325 */
326 public static Window createWindow(final String displayConnection, final int screenIdx, final long parentWindowHandle, final CapabilitiesImmutable caps) {
327 final String type = NativeWindowFactory.getNativeWindowType(true);
328 final Display display = NewtFactory.createDisplay(type, displayConnection, true);
329 final Screen screen = NewtFactory.createScreen(display, screenIdx);
330 return WindowImpl.create(null, parentWindowHandle, screen, caps);
331 }
332
333 /**
334 * Ability to try a Window type with a constructor argument, if supported ..<p>
335 * Currently only valid is <code> AWTWindow(Frame frame) </code>,
336 * to support an external created AWT Frame, ie the browsers embedded frame.
337 *
338 * @param undecorated only impacts if the window is in top-level state, while attached to a parent window it's rendered undecorated always
339 */
340 public static Window createWindow(final Object[] cstrArguments, final Screen screen, final CapabilitiesImmutable caps) {
341 return WindowImpl.create(cstrArguments, screen, caps);
342 }
343
344 /**
345 * Instantiate a Display entity using the native handle.
346 */
347 public static Display createDisplay(final String type, final long handle, final boolean reuse) {
348 return DisplayImpl.create(type, null, handle, reuse);
349 }
350
351 public static boolean isScreenCompatible(final NativeWindow parent, final Screen childScreen) {
352 // Get parent's NativeWindow details
353 final AbstractGraphicsConfiguration parentConfig = parent.getGraphicsConfiguration();
354 final AbstractGraphicsScreen parentScreen = parentConfig.getScreen();
355 final AbstractGraphicsDevice parentDevice = parentScreen.getDevice();
356
357 final DisplayImpl childDisplay = (DisplayImpl) childScreen.getDisplay();
358 final String parentDisplayName = childDisplay.validateDisplayName(null, parentDevice.getHandle());
359 final String childDisplayName = childDisplay.getName();
360 if( ! parentDisplayName.equals( childDisplayName ) ) {
361 return false;
362 }
363
364 if( parentScreen.getIndex() != childScreen.getIndex() ) {
365 return false;
366 }
367 return true;
368 }
369
370 public static Screen createCompatibleScreen(final NativeWindow parent) {
371 return createCompatibleScreen(parent, null);
372 }
373
374 public static Screen createCompatibleScreen(final NativeWindow parent, final Screen childScreen) {
375 // Get parent's NativeWindow details
376 final AbstractGraphicsConfiguration parentConfig = parent.getGraphicsConfiguration();
377 final AbstractGraphicsScreen parentScreen = parentConfig.getScreen();
378 final AbstractGraphicsDevice parentDevice = parentScreen.getDevice();
379
380 if(null != childScreen) {
381 // check if child Display/Screen is compatible already
382 final DisplayImpl childDisplay = (DisplayImpl) childScreen.getDisplay();
383 final String parentDisplayName = childDisplay.validateDisplayName(null, parentDevice.getHandle());
384 final String childDisplayName = childDisplay.getName();
385 final boolean displayEqual = parentDisplayName.equals( childDisplayName );
386 final boolean screenEqual = parentScreen.getIndex() == childScreen.getIndex();
388 System.err.println("NewtFactory.createCompatibleScreen: Display: "+
389 parentDisplayName+" =? "+childDisplayName+" : "+displayEqual+"; Screen: "+
390 parentScreen.getIndex()+" =? "+childScreen.getIndex()+" : "+screenEqual);
391 }
392 if( displayEqual && screenEqual ) {
393 // match: display/screen
394 return childScreen;
395 }
396 }
397
398 // Prep NEWT's Display and Screen according to the parent
399 final String type = NativeWindowFactory.getNativeWindowType(true);
400 final Display display = NewtFactory.createDisplay(type, parentDevice.getHandle(), true);
401 return NewtFactory.createScreen(display, parentScreen.getIndex());
402 }
403}
404
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Provides a pluggable mechanism for arbitrary window toolkits to adapt their components to the NativeW...
static synchronized void initSingleton()
Static one time initialization of this factory.
static String getNativeWindowType(final boolean useCustom)
abstract String getName()
static Window createWindow(final Object[] cstrArguments, final Screen screen, final CapabilitiesImmutable caps)
Ability to try a Window type with a constructor argument, if supported ..
static boolean isScreenCompatible(final NativeWindow parent, final Screen childScreen)
static Window createWindow(final String displayConnection, final int screenIdx, final long parentWindowHandle, final CapabilitiesImmutable caps)
Create a child Window entity attached to the given parent, incl native creation
static Class<?> getCustomClass(final String packageName, final String classBaseName)
static Display createDisplay(final String name)
Create a Display entity.
static final String DRIVER_DEFAULT_ROOT_PACKAGE
static Display createDisplay(final String type, final String name, final boolean reuse)
Create a Display entity.
static Window createWindow(final Screen screen, final CapabilitiesImmutable caps)
Create a top level Window entity.
static Display createDisplay(final String name, final boolean reuse)
Create a Display entity.
static final boolean DEBUG_IMPLEMENTATION
static Display createDisplay(final String type, final String name)
Create a Display entity.
static synchronized void setUseEDT(final boolean onoff)
Toggles the usage of an EventDispatchThread while creating a Display.
static Window createWindow(final NativeWindow parentWindow, final CapabilitiesImmutable caps)
Create a child Window entity attached to the given parent.
static Window createWindow(final CapabilitiesImmutable caps)
Create a top level Window entity on the default Display and default Screen.
static void setWindowIcons(final IOUtil.ClassResources cres)
Allow user to set custom window icons, only applicable at application start before creating any NEWT ...
static Screen createCompatibleScreen(final NativeWindow parent, final Screen childScreen)
static IOUtil.ClassResources getWindowIcons()
Returns the application window icon resources to be used.
static Screen createCompatibleScreen(final NativeWindow parent)
static Screen createScreen(final Display display, final int index)
Create a Screen entity.
static Display createDisplay(final String type, final long handle, final boolean reuse)
Instantiate a Display entity using the native handle.
A screen may span multiple MonitorDevices representing their combined virtual size.
Definition: Screen.java:58
abstract Display getDisplay()
abstract int getIndex()
A marker interface describing a graphics configuration, visual, or pixel format in a toolkit-independ...
AbstractGraphicsScreen getScreen()
Return the screen this graphics configuration is valid for.
A interface describing a graphics device in a toolkit-independent manner.
long getHandle()
Returns the native handle of the underlying native device, if such thing exist.
A interface describing a graphics screen in a toolkit-independent manner.
int getIndex()
Returns the screen index this graphics screen is valid for.
AbstractGraphicsDevice getDevice()
Return the device this graphics configuration is valid for.
Specifies an immutable set of capabilities that a window's rendering context must support,...
AbstractGraphicsConfiguration getGraphicsConfiguration()
Returns the graphics configuration corresponding to this window.
Extend the NativeSurface interface with windowing information such as window-handle,...
int getHeight()
Returns the height of the client area excluding insets (window decorations) in window units.
int getWidth()
Returns the width of the client area excluding insets (window decorations) in window units.
Specifying NEWT's Window functionality:
Definition: Window.java:115
boolean addChild(NativeWindow win)
void setSize(int width, int height)
Sets the size of the window's client area in window units, excluding decorations.
void setVisible(boolean visible)
Calls setVisible(true, visible), i.e.