JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
Screen.java
Go to the documentation of this file.
1/**
2 * Copyright 2010 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.newt;
29
30import com.jogamp.newt.event.MonitorModeListener;
31
32import jogamp.newt.Debug;
33
34import java.lang.ref.WeakReference;
35import java.util.ArrayList;
36import java.util.Collection;
37import java.util.List;
38
39import com.jogamp.nativewindow.AbstractGraphicsScreen;
40import com.jogamp.nativewindow.NativeWindowException;
41import com.jogamp.nativewindow.util.Rectangle;
42import com.jogamp.nativewindow.util.RectangleImmutable;
43
44/**
45 * A screen may span multiple {@link MonitorDevice}s representing their combined virtual size.
46 * <p>
47 * All values of this interface are represented in pixel units, if not stated otherwise.
48 * </p>
49 *
50 * <a name="coordinateSystem"><h5>Coordinate System</h5></a>
51 * <p>
52 * <ul>
53 * <li>Screen space has it's origin in the top-left corner, and may not be at 0/0.</li>
54 * <li>{@link #getViewport() Virtual viewport} covers all {@link MonitorDevice}s {@link MonitorDevice#getViewport() viewports} and has it's origin in the top-left corner, and may not be at 0/0.</li>
55 * </ul>
56 * </p>
57*/
58public abstract class Screen {
59
60 /**
61 * A 10s timeout for screen mode change. It is observed, that some platforms
62 * need a notable amount of time for this task, especially in case of rotation change.
63 */
64 public static final int SCREEN_MODE_CHANGE_TIMEOUT = 10000;
65
66 public static final boolean DEBUG = Debug.debug("Screen");
67
68 /** return precomputed hashCode from FQN {@link #getFQName()} */
69 @Override
70 public abstract int hashCode();
71
72 /** return true if obj is of type Display and both FQN {@link #getFQName()} equals */
73 @Override
74 public boolean equals(final Object obj) {
75 if (this == obj) { return true; }
76 if (obj instanceof Screen) {
77 final Screen s = (Screen)obj;
78 return s.getFQName().equals(getFQName());
79 }
80 return false;
81 }
82
83 /**
84 * Manual trigger the native creation, if not done yet..<br>
85 * This is useful to be able to request the {@link com.jogamp.nativewindow.AbstractGraphicsScreen}, via
86 * {@link #getGraphicsScreen()}.<br>
87 * Otherwise the abstract device won't be available before the dependent component (Window) is realized.
88 * <p>
89 * This method is usually invoke by {@link #addReference()}
90 * </p>
91 * <p>
92 * This method invokes {@link Display#addReference()} after creating the native peer,<br>
93 * which will issue {@link Display#createNative()} if the reference count was 0.
94 * </p>
95 * @throws NativeWindowException if the native creation failed.
96 */
97 public abstract void createNative() throws NativeWindowException;
98
99 /**
100 * Manually trigger the destruction, incl. native destruction.<br>
101 * <p>
102 * This method is usually invoke by {@link #removeReference()}
103 * </p>
104 * <p>
105 * This method invokes {@link Display#removeReference()} after it's own destruction,<br>
106 * which will issue {@link Display#destroy()} if the reference count becomes 0.
107 * </p>
108 */
109 public abstract void destroy();
110
111 public abstract boolean isNativeValid();
112
113 /**
114 * @return number of references
115 */
116 public abstract int getReferenceCount();
117
118 /**
119 * See {@link Display#addReference()}
120 *
121 * @return number of references post operation
122 * @throws NativeWindowException if the native creation failed.
123 * @see #removeReference()
124 * @see #setDestroyWhenUnused(boolean)
125 * @see #getDestroyWhenUnused()
126 */
127 public abstract int addReference() throws NativeWindowException;
128
129 /**
130 * See {@link Display#removeReference()}
131 *
132 * @return number of references post operation
133 * @see #addReference()
134 * @see #setDestroyWhenUnused(boolean)
135 * @see #getDestroyWhenUnused()
136 */
137 public abstract int removeReference();
138
140
141 /**
142 * @return this Screen index of all Screens of {@link #getDisplay()}.
143 */
144 public abstract int getIndex();
145
146 /**
147 * See <a href="#coordinateSystem"> Coordinate System</a>.
148 *
149 * @return the x position of the virtual viewport's top-left origin in pixel units.
150 */
151 public abstract int getX();
152
153 /**
154 * See <a href="#coordinateSystem"> Coordinate System</a>.
155 *
156 * @return the y position of the virtual viewport's top-left origin in pixel units.
157 */
158 public abstract int getY();
159
160 /**
161 * @return the <b>rotated</b> virtual viewport's width in pixel units.
162 */
163 public abstract int getWidth();
164
165 /**
166 * @return the <b>rotated</b> virtual viewport's height in pixel units.
167 */
168 public abstract int getHeight();
169
170 /**
171 * See <a href="#coordinateSystem"> Coordinate System</a>.
172 *
173 * @return the <b>rotated</b> virtual viewport, i.e. top-left origin and size, in pixel units.
174 * @see #getViewportInWindowUnits()
175 */
177
178 /**
179 * See <a href="#coordinateSystem"> Coordinate System</a>.
180 *
181 * @return the <b>rotated</b> virtual viewport, i.e. top-left origin and size, in window units.
182 * @see #getViewport()
183 */
185
186 /**
187 * @return the associated Display
188 */
189 public abstract Display getDisplay();
190
191 /**
192 * @return The screen fully qualified Screen name,
193 * which is a key of {@link com.jogamp.newt.Display#getFQName()} + {@link #getIndex()}.
194 */
195 public abstract String getFQName();
196
197 /**
198 * Return a list of all {@link MonitorMode}s for all {@link MonitorDevice}s.
199 * <p>
200 * The list is ordered in descending order,
201 * see {@link MonitorMode#compareTo(MonitorMode)}.
202 * </p>
203 */
204 public abstract List<MonitorMode> getMonitorModes();
205
206 /**
207 * Return a list of available {@link MonitorDevice}s.
208 */
209 public abstract List<MonitorDevice> getMonitorDevices();
210
211 /**
212 * Returns the windowing manager's primary {@link MonitorDevice},
213 * which holds the system menu bar, etc.
214 * @see MonitorDevice#isPrimary()
215 */
217
218 /**
219 * Returns the {@link MonitorDevice} with the highest {@link MonitorDevice#getViewportInWindowUnits() viewport}
220 * {@link RectangleImmutable#coverage(RectangleImmutable) coverage} of the given rectangle in window units,
221 * which is not a {@link MonitorDevice#isClone() clone}.
222 * <p>
223 * If no coverage is detected the first {@link MonitorDevice} is returned.
224 * </p>
225 * @param r arbitrary rectangle in window units
226 */
228 MonitorDevice res = null;
229 float maxCoverage = Float.MIN_VALUE;
230 final List<MonitorDevice> monitors = getMonitorDevices();
231 for(final MonitorDevice monitor : monitors) {
232 if( !monitor.isClone() ) {
233 final float coverage = monitor.getViewportInWindowUnits().coverage(r);
234 if( coverage > maxCoverage ) {
235 maxCoverage = coverage;
236 res = monitor;
237 }
238 }
239 }
240 if( maxCoverage > 0.0f && null != res ) {
241 return res;
242 }
243 return monitors.get(0);
244 }
245
246 /**
247 * Returns the {@link MonitorDevice} which completely which {@link MonitorDevice#getViewportInWindowUnits() viewport}
248 * completely {@link RectangleImmutable#contains(RectangleImmutable) coverage} the given rectangle in window units,
249 * which is not a {@link MonitorDevice#isClone() clone}.
250 * <p>
251 * If no match is found, null is being returned
252 * </p>
253 * @param r arbitrary rectangle in window units
254 */
256 for(final MonitorDevice monitor : getMonitorDevices()) {
257 if( !monitor.isClone() && monitor.getViewportInWindowUnits().contains(r) ) {
258 return monitor;
259 }
260 }
261 return null;
262 }
263
264 /**
265 * Returns the {@link MonitorDevice} which matches the given integer monitorId.
266 * <p>
267 * If no match is found, null is being returned
268 * </p>
269 */
270 public final MonitorDevice getMonitorById(final int monitorId) {
271 for(final MonitorDevice monitor : getMonitorDevices()) {
272 if( monitor.getId() == monitorId ) {
273 return monitor;
274 }
275 }
276 return null;
277 }
278
279 /**
280 * Returns the {@link MonitorDevice} which matches the given long monitorHandle.
281 * <p>
282 * If no match is found, null is being returned
283 * </p>
284 */
285 public final MonitorDevice getMonitorByHandle(final long monitorHandle) {
286 for(final MonitorDevice monitor : getMonitorDevices()) {
287 if( monitor.getHandle() == monitorHandle ) {
288 return monitor;
289 }
290 }
291 return null;
292 }
293
294 /**
295 * Returns the {@link MonitorDevice} which matches the given name.
296 * <p>
297 * If no match is found or the given name is null or empty, null is being returned
298 * </p>
299 */
300 public final MonitorDevice getMonitorByName(final String name) {
301 if( null == name || name.isEmpty() ) {
302 return null;
303 }
304 for(final MonitorDevice monitor : getMonitorDevices()) {
305 if( name.equals( monitor.getName() ) ) {
306 return monitor;
307 }
308 }
309 return null;
310 }
311
312 /**
313 * Calculates the union of all monitor's {@link MonitorDevice#getViewport() viewport} in pixel- and window units.
314 * <p>
315 * Should be equal to {@link #getX()}, {@link #getY()}, {@link #getWidth()} and {@link #getHeight()},
316 * however, some native toolkits may choose a different virtual screen area.
317 * </p>
318 * @param viewport storage for result in pixel units, maybe null
319 * @param viewportInWindowUnits storage for result in window units, maybe null
320 */
321 public final void unionOfMonitorViewports(final Rectangle viewport, final Rectangle viewportInWindowUnits) {
322 MonitorDevice.unionOfViewports(viewport, viewportInWindowUnits, getMonitorDevices());
323 }
324
325 /**
326 * @param sml {@link MonitorModeListener} to be added for {@link MonitorEvent}
327 */
329
330 /**
331 * @param sml {@link MonitorModeListener} to be removed from {@link MonitorEvent}
332 */
334
335 // Global Screens
336 protected static final ArrayList<WeakReference<Screen>> screenList = new ArrayList<WeakReference<Screen>>();
337 protected static int screensActive = 0;
338
339 /**
340 *
341 * @param type
342 * @param name
343 * @param fromIndex start index, then increasing until found or end of list *
344 * @return
345 */
346 public static Screen getFirstScreenOf(final Display display, final int idx, final int fromIndex) {
347 return getScreenOfImpl(display, idx, fromIndex, 1);
348 }
349
350 /**
351 *
352 * @param type
353 * @param name
354 * @param fromIndex start index, then decreasing until found or end of list. -1 is interpreted as size - 1.
355 * @return
356 */
357 public static Screen getLastScreenOf(final Display display, final int idx, final int fromIndex) {
358 return getScreenOfImpl(display, idx, fromIndex, -1);
359 }
360
361 private static Screen getScreenOfImpl(final Display display, final int idx, final int fromIndex, final int incr) {
362 synchronized(screenList) {
363 int i = fromIndex >= 0 ? fromIndex : screenList.size() - 1 ;
364 while( ( incr > 0 ) ? i < screenList.size() : i >= 0 ) {
365 final Screen screen = screenList.get(i).get();
366 if( null == screen ) {
367 // Clear GC'ed dead reference entry!
368 screenList.remove(i);
369 if( incr < 0 ) {
370 // decrease
371 i+=incr;
372 } // else nop - remove shifted subsequent elements to the left
373 } else {
374 if( screen.getDisplay().equals(display) &&
375 screen.getIndex() == idx ) {
376 return screen;
377 }
378 i+=incr;
379 }
380 }
381 }
382 return null;
383 }
384
385 protected static void addScreen2List(final Screen screen) {
386 synchronized(screenList) {
387 // GC before add
388 int i=0;
389 while( i < screenList.size() ) {
390 if( null == screenList.get(i).get() ) {
391 screenList.remove(i);
392 } else {
393 i++;
394 }
395 }
396 screenList.add(new WeakReference<Screen>(screen));
397 }
398 }
399
400 /** Returns the global screen collection */
401 public static Collection<Screen> getAllScreens() {
402 ArrayList<Screen> list;
403 synchronized(screenList) {
404 list = new ArrayList<Screen>();
405 int i = 0;
406 while( i < screenList.size() ) {
407 final Screen s = screenList.get(i).get();
408 if( null == s ) {
409 screenList.remove(i);
410 } else {
411 list.add( screenList.get(i).get() );
412 i++;
413 }
414 }
415 }
416 return list;
417 }
418
419 public static int getActiveScreenNumber() {
420 synchronized(screenList) {
421 return screensActive;
422 }
423 }
424}
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
boolean equals(final Object obj)
return true if obj is of type Display and both FQN getFQName() equals
Definition: Display.java:58
Visual output device, i.e.
static void unionOfViewports(final Rectangle viewport, final Rectangle viewportInWindowUnits, final List< MonitorDevice > monitors)
Calculates the union of the given monitor's viewport in pixel- and window units.
Immutable MonitorMode Class, consisting of it's read only components:
A screen may span multiple MonitorDevices representing their combined virtual size.
Definition: Screen.java:58
static final ArrayList< WeakReference< Screen > > screenList
Definition: Screen.java:336
abstract int getHeight()
abstract AbstractGraphicsScreen getGraphicsScreen()
abstract int addReference()
See Display#addReference().
final void unionOfMonitorViewports(final Rectangle viewport, final Rectangle viewportInWindowUnits)
Calculates the union of all monitor's viewport in pixel- and window units.
Definition: Screen.java:321
abstract int hashCode()
return precomputed hashCode from FQN getFQName()
abstract Display getDisplay()
static final boolean DEBUG
Definition: Screen.java:66
abstract void addMonitorModeListener(MonitorModeListener sml)
abstract String getFQName()
static Collection< Screen > getAllScreens()
Returns the global screen collection.
Definition: Screen.java:401
abstract int removeReference()
See Display#removeReference().
static Screen getFirstScreenOf(final Display display, final int idx, final int fromIndex)
Definition: Screen.java:346
abstract RectangleImmutable getViewport()
See Coordinate System.
abstract int getX()
See Coordinate System.
abstract RectangleImmutable getViewportInWindowUnits()
See Coordinate System.
static int screensActive
Definition: Screen.java:337
abstract void removeMonitorModeListener(MonitorModeListener sml)
static int getActiveScreenNumber()
Definition: Screen.java:419
abstract List< MonitorMode > getMonitorModes()
Return a list of all MonitorModes for all MonitorDevices.
static void addScreen2List(final Screen screen)
Definition: Screen.java:385
abstract MonitorDevice getPrimaryMonitor()
Returns the windowing manager's primary MonitorDevice, which holds the system menu bar,...
abstract int getY()
See Coordinate System.
final MonitorDevice getFullyEnteredMonitor(final RectangleImmutable r)
Returns the MonitorDevice which completely which viewport completely coverage the given rectangle in ...
Definition: Screen.java:255
abstract void destroy()
Manually trigger the destruction, incl.
abstract int getReferenceCount()
static Screen getLastScreenOf(final Display display, final int idx, final int fromIndex)
Definition: Screen.java:357
final MonitorDevice getMainMonitor(final RectangleImmutable r)
Returns the MonitorDevice with the highest viewport coverage of the given rectangle in window units,...
Definition: Screen.java:227
boolean equals(final Object obj)
return true if obj is of type Display and both FQN getFQName() equals
Definition: Screen.java:74
final MonitorDevice getMonitorByHandle(final long monitorHandle)
Returns the MonitorDevice which matches the given long monitorHandle.
Definition: Screen.java:285
static final int SCREEN_MODE_CHANGE_TIMEOUT
A 10s timeout for screen mode change.
Definition: Screen.java:64
abstract boolean isNativeValid()
abstract void createNative()
Manual trigger the native creation, if not done yet.. This is useful to be able to request the com....
final MonitorDevice getMonitorByName(final String name)
Returns the MonitorDevice which matches the given name.
Definition: Screen.java:300
abstract int getWidth()
final MonitorDevice getMonitorById(final int monitorId)
Returns the MonitorDevice which matches the given integer monitorId.
Definition: Screen.java:270
abstract int getIndex()
abstract List< MonitorDevice > getMonitorDevices()
Return a list of available MonitorDevices.
A interface describing a graphics screen in a toolkit-independent manner.
Immutable Rectangle interface, with its position on the top-left.