JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
DefaultGraphicsDevice.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010-2024 JogAmp Community. All rights reserved.
3 * Copyright (c) 2008-2009 Sun Microsystems, Inc. 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
34package com.jogamp.nativewindow;
35
36import jogamp.nativewindow.NativeWindowFactoryImpl;
37
38public class DefaultGraphicsDevice implements Cloneable, AbstractGraphicsDevice {
39 private static final String separator = "_";
40 private final String type;
41 protected final String connection;
42 protected final int unitID;
43 protected final String uniqueID;
44 protected long handle;
45 private Object handleOwner;
47
48 /**
49 * Return the default display connection for the given windowing toolkit type
50 * gathered via {@link NativeWindowFactory#getDefaultDisplayConnection()}.
51 * @param type
52 */
53 public static String getDefaultDisplayConnection() {
55 }
56 /**
57 * Return the default display connection for the given windowing toolkit type
58 * gathered via {@link NativeWindowFactory#getDefaultDisplayConnection(String)}.
59 * @param type
60 */
61 public static String getDefaultDisplayConnection(final String type) {
63 }
64
65 /**
66 * Create an instance with the system default {@link ToolkitLock},
67 * gathered via {@link NativeWindowFactory#getDefaultToolkitLock(String)}.
68 * @param type
69 */
70 public DefaultGraphicsDevice(final String type, final String connection, final int unitID) {
72 }
73
74 /**
75 * Create an instance with the system default {@link ToolkitLock}.
76 * gathered via {@link NativeWindowFactory#getDefaultToolkitLock(String)}.
77 * @param type
78 * @param handle
79 */
80 public DefaultGraphicsDevice(final String type, final String connection, final int unitID, final long handle) {
82 }
83
84 /**
85 * Create an instance with the given {@link ToolkitLock} instance, or <i>null</i> {@link ToolkitLock} if null.
86 * @param type
87 * @param handle
88 * @param locker if null, a non blocking <i>null</i> lock is used.
89 */
90 public DefaultGraphicsDevice(final String type, final String connection, final int unitID, final long handle, final ToolkitLock locker) {
91 this.type = type;
92 this.connection = connection;
93 this.unitID = unitID;
94 this.uniqueID = getUniqueID(type, connection, unitID);
95 this.handle = handle;
96 this.handleOwner = null;
97 this.toolkitLock = null != locker ? locker : NativeWindowFactoryImpl.getNullToolkitLock();
98 }
99
100 @Override
101 public Object clone() {
102 try {
103 return super.clone();
104 } catch (final CloneNotSupportedException e) {
105 throw new NativeWindowException(e);
106 }
107 }
108
109 @Override
110 public final String getType() {
111 return type;
112 }
113
114 @Override
115 public final String getConnection() {
116 return connection;
117 }
118
119 @Override
120 public final int getUnitID() {
121 return unitID;
122 }
123
124 @Override
125 public final String getUniqueID() {
126 return uniqueID;
127 }
128
129 @Override
130 public final long getHandle() {
131 return handle;
132 }
133
134 /**
135 * {@inheritDoc}
136 * <p>
137 * Locking is perfomed via delegation to {@link ToolkitLock#lock()}, {@link ToolkitLock#unlock()}.
138 * </p>
139 *
140 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)
141 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, com.jogamp.nativewindow.ToolkitLock)
142 */
143 @Override
144 public final void lock() {
146 }
147
148 @Override
149 public final void validateLocked() throws RuntimeException {
151 }
152
153 /**
154 * {@inheritDoc}
155 * <p>
156 * Locking is perfomed via delegation to {@link ToolkitLock#lock()}, {@link ToolkitLock#unlock()}.
157 * </p>
158 *
159 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)
160 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, com.jogamp.nativewindow.ToolkitLock)
161 */
162 @Override
163 public final void unlock() {
165 }
166
167 @Override
168 public boolean open() {
169 return false;
170 }
171
172 @Override
173 public boolean close() {
175 if(0 != handle) {
176 handle = 0;
177 return true;
178 }
179 return false;
180 }
181
182 @Override
183 public final boolean isHandleOwner() {
184 return null != handleOwner;
185 }
186
187 @Override
188 public final void clearHandleOwner() {
189 handleOwner = null;
190 }
191
192 @Override
193 public String toString() {
194 return getClass().getSimpleName()+"[type "+getType()+", connection "+getConnection()+", unitID "+getUnitID()+
195 ", handle 0x"+Long.toHexString(getHandle())+", owner "+isHandleOwner()+", "+toolkitLock+", obj 0x"+Integer.toHexString(hashCode())+"]";
196 }
197
198 /**
199 * Set the native handle of the underlying native device
200 * and return the previous one.
201 */
202 protected final long setHandle(final long newHandle) {
203 final long oldHandle = handle;
204 handle = newHandle;
205 return oldHandle;
206 }
207
208 protected final Object getHandleOwnership() {
209 return handleOwner;
210 }
211 protected final Object setHandleOwnership(final Object newOwnership) {
212 final Object old = handleOwner;
213 handleOwner = newOwnership;
214 return old;
215 }
216
217 public static final void swapHandleAndOwnership(final DefaultGraphicsDevice a, final DefaultGraphicsDevice b) {
218 a.lock();
219 try {
220 b.lock();
221 try {
222 final long aHandle = a.getHandle();
223 final long bHandle = b.setHandle(aHandle);
224 a.setHandle(bHandle);
225 final Object aOwnership = a.getHandleOwnership();
226 final Object bOwnership = b.setHandleOwnership(aOwnership);
227 a.setHandleOwnership(bOwnership);
228 } finally {
229 b.unlock();
230 }
231 } finally {
232 a.unlock();
233 }
234 }
235
236 /**
237 * Set the internal ToolkitLock, which is used within the
238 * {@link #lock()} and {@link #unlock()} implementation.
239 *
240 * <p>
241 * The current ToolkitLock is being locked/unlocked while swapping the reference,
242 * ensuring no concurrent access can occur during the swap.
243 * </p>
244 *
245 * @param locker the ToolkitLock, if null, {@link jogamp.nativewindow.NullToolkitLock} is being used
246 * @return the previous ToolkitLock instance
247 */
248 protected ToolkitLock setToolkitLock(final ToolkitLock locker) {
249 final ToolkitLock _toolkitLock = toolkitLock;
250 _toolkitLock.lock();
251 try {
252 toolkitLock = ( null == locker ) ? NativeWindowFactoryImpl.getNullToolkitLock() : locker ;
253 } finally {
254 _toolkitLock.unlock();
255 }
256 return _toolkitLock;
257 }
258
259 /**
260 * @return the used ToolkitLock
261 *
262 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)
263 * @see DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, com.jogamp.nativewindow.ToolkitLock)
264 */
266 return toolkitLock;
267 }
268
269 /**
270 * Returns a unique String object using {@link String#intern()} for the given arguments,
271 * which object reference itself can be used as a key.
272 */
273 private static String getUniqueID(final String type, final String connection, final int unitID) {
274 return (type + separator + connection + separator + unitID).intern();
275 }
276}
boolean close()
Optionally closing the device if handle is not null.
static String getDefaultDisplayConnection(final String type)
Return the default display connection for the given windowing toolkit type gathered via NativeWindowF...
boolean open()
Optionally [re]opening the device if handle is null.
final String getUniqueID()
Returns a unique ID object of this device using type, connection and unitID as it's key components.
final void unlock()
Optionally unlocking the device, utilizing eg com.jogamp.nativewindow.ToolkitLock#unlock()....
final void lock()
Optionally locking the device, utilizing eg com.jogamp.nativewindow.ToolkitLock#lock()....
ToolkitLock setToolkitLock(final ToolkitLock locker)
Set the internal ToolkitLock, which is used within the lock() and unlock() implementation.
final String getType()
Returns the type of the underlying subsystem, ie NativeWindowFactory.TYPE_KD, NativeWindowFactory....
DefaultGraphicsDevice(final String type, final String connection, final int unitID, final long handle)
Create an instance with the system default ToolkitLock.
DefaultGraphicsDevice(final String type, final String connection, final int unitID, final long handle, final ToolkitLock locker)
Create an instance with the given ToolkitLock instance, or null ToolkitLock if null.
final int getUnitID()
Returns the graphics device unit ID.
final String getConnection()
Returns the semantic GraphicsDevice connection.
static final void swapHandleAndOwnership(final DefaultGraphicsDevice a, final DefaultGraphicsDevice b)
final long setHandle(final long newHandle)
Set the native handle of the underlying native device and return the previous one.
DefaultGraphicsDevice(final String type, final String connection, final int unitID)
Create an instance with the system default ToolkitLock, gathered via NativeWindowFactory#getDefaultTo...
final long getHandle()
Returns the native handle of the underlying native device, if such thing exist.
static String getDefaultDisplayConnection()
Return the default display connection for the given windowing toolkit type gathered via NativeWindowF...
final Object setHandleOwnership(final Object newOwnership)
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 ToolkitLock getDefaultToolkitLock()
Provides the system default ToolkitLock for the default system windowing type.
A interface describing a graphics device in a toolkit-independent manner.
Marker for a singleton global recursive blocking lock implementation, optionally locking a native win...
void dispose()
Dispose this instance.
void unlock()
Release the lock.
void lock()
Blocking until the lock is acquired by this Thread or a timeout is reached.