JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
NativeSurface.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 */
28
29package com.jogamp.nativewindow;
30
31import com.jogamp.common.util.locks.RecursiveLock;
32
33/**
34 * Provides low-level information required for
35 * hardware-accelerated rendering using a surface in a platform-independent manner.
36 * <p>
37 * All values of this interface are represented in pixel units, if not stated otherwise.
38 * See {@link NativeWindow}.
39 * </p>
40 * <p>
41 * A NativeSurface created for a particular on- or offscreen component is
42 * expected to have the same lifetime as that component. As long as
43 * the component is alive and realized/visible, NativeSurface must be able
44 * provide information such as the surface handle while it is locked.
45 * </p>
46 */
47public interface NativeSurface extends SurfaceUpdatedListener {
48 /** Unlocked state, {@value}. */
49 public static final int LOCK_SURFACE_UNLOCKED = 0;
50
51 /** Returned by {@link #lockSurface()} if the surface is not ready to be locked, {@value}. */
52 public static final int LOCK_SURFACE_NOT_READY = 1;
53
54 /** Returned by {@link #lockSurface()} if the surface is locked, but has changed, {@value}. */
55 public static final int LOCK_SURFACE_CHANGED = 2;
56
57 /** Returned by {@link #lockSurface()} if the surface is locked, and is unchanged, {@value}. */
58 public static final int LOCK_SUCCESS = 3;
59
60
61 /**
62 * Returns the implementation's {@link RecursiveLock} synchronizing multithreaded access
63 * if used. Otherwise {@code null} is being returned.
64 * <p>
65 * {@link NativeSurface}'s {@link RecursiveLock} is only exposed to resolve special
66 * situations within the implementation and its usage is not advised if not absolutely necessary.
67 * </p>
68 * <p>
69 * Note that certain {@link NativeSurface} implementations only use the {@link RecursiveLock}
70 * as an upfront re-entrance lock vehicle, but actually acquire and release
71 * the underlying windowing toolkit's lock facility on the first or last re-entrance lock,
72 * respectively.
73 * </p>
74 */
75 public RecursiveLock getLock();
76
77 /**
78 * Lock the surface of this native window.
79 * <p>
80 * The surface handle shall be valid after a successfull call,
81 * ie return a value other than {@link #LOCK_SURFACE_UNLOCKED} and {@link #LOCK_SURFACE_NOT_READY},
82 * which is
83 * <pre>
84 * boolean ok = LOCK_SURFACE_NOT_READY < lockSurface();
85 * </pre>
86 * </p>
87 * <p>
88 * The caller may need to take care of the result {@link #LOCK_SURFACE_CHANGED},
89 * where the surface handle is valid but has changed.
90 * </p>
91 * <p>
92 * This call is blocking until the surface has been locked
93 * or a timeout is reached. The latter will throw a runtime exception.
94 * </p>
95 * <p>
96 * This call allows recursion from the same thread.
97 * </p>
98 * <p>
99 * The implementation may want to aquire the
100 * application level {@link com.jogamp.common.util.locks.RecursiveLock}
101 * first before proceeding with a native surface lock.
102 * </p>
103 * <p>
104 * The implementation shall also invoke {@link AbstractGraphicsDevice#lock()}
105 * for the initial lock (recursive count zero).
106 * </p>
107 *
108 * @return {@link #LOCK_SUCCESS}, {@link #LOCK_SURFACE_CHANGED} or {@link #LOCK_SURFACE_NOT_READY}.
109 *
110 * @throws RuntimeException after timeout when waiting for the surface lock
111 * @throws NativeWindowException if native locking failed, maybe platform related
112 *
113 * @see com.jogamp.common.util.locks.RecursiveLock
114 */
115 public int lockSurface() throws NativeWindowException, RuntimeException;
116
117 /**
118 * Unlock the surface of this native window
119 *
120 * Shall not modify the surface handle, see {@link #lockSurface()} <P>
121 *
122 * The implementation shall also invoke {@link AbstractGraphicsDevice#unlock()}
123 * for the final unlock (recursive count zero).<P>
124 *
125 * The implementation shall be fail safe, i.e. tolerant in case the native resources
126 * are already released / unlocked. In this case the implementation shall simply ignore the call.
127 *
128 * @see #lockSurface
129 * @see com.jogamp.common.util.locks.RecursiveLock
130 */
131 public void unlockSurface();
132
133 /**
134 * Query if surface is locked by another thread, i.e. not the current one.
135 * <br>
136 * Convenient shortcut for:
137 * <pre>
138 * final Thread o = getSurfaceLockOwner();
139 * if( null != o && Thread.currentThread() != o ) { .. }
140 * </pre>
141 */
143
144 /**
145 * Return the locking owner's Thread, or null if not locked.
146 */
147 public Thread getSurfaceLockOwner();
148
149 /**
150 * Provide a mechanism to utilize custom (pre-) swap surface
151 * code. This method is called before the render toolkit (e.g. JOGL)
152 * swaps the buffer/surface if double buffering is enabled.
153 * <p>
154 * The implementation may itself apply the swapping,
155 * in which case true shall be returned.
156 * </p>
157 *
158 * @return true if this method completed swapping the surface,
159 * otherwise false, in which case eg the GLDrawable
160 * implementation has to swap the code.
161 */
162 public boolean surfaceSwap();
163
164 /** Appends the given {@link SurfaceUpdatedListener} to the end of the list. */
166
167 /**
168 * Inserts the given {@link SurfaceUpdatedListener} at the
169 * specified position in the list.<br>
170 *
171 * @param index Position where the listener will be inserted.
172 * Should be within (0 <= index && index <= size()).
173 * An index value of -1 is interpreted as the end of the list, size().
174 * @param l The listener object to be inserted
175 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
176 */
177 public void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException;
178
179 /** Remove the specified {@link SurfaceUpdatedListener} from the list. */
181
182 /**
183 * Returns the handle to the surface for this NativeSurface. <P>
184 *
185 * The surface handle should be set/update by {@link #lockSurface()},
186 * where {@link #unlockSurface()} is not allowed to modify it.
187 * After {@link #unlockSurface()} it is no more guaranteed
188 * that the surface handle is still valid.
189 *
190 * The surface handle shall reflect the platform one
191 * for all drawable surface operations, e.g. opengl, swap-buffer. <P>
192 *
193 * On X11 this returns an entity of type Window,
194 * since there is no differentiation of surface and window there. <BR>
195 * On Microsoft Windows this returns an entity of type HDC.
196 */
197 public long getSurfaceHandle();
198
199 /**
200 * Returns the width of the client area excluding insets (window decorations) in pixel units.
201 * @return width of the client area in pixel units
202 * @see NativeWindow#getWidth()
203 * @see #convertToWindowUnits(int[])
204 */
205 public int getSurfaceWidth();
206
207 /**
208 * Returns the height of the client area excluding insets (window decorations) in pixel units.
209 * @return height of the client area in pixel units
210 * @see NativeWindow#getHeight()
211 * @see #convertToWindowUnits(int[])
212 */
213 public int getSurfaceHeight();
214
215 /**
216 * Converts the given pixel units into window units <i>in place</i>.
217 * @param pixelUnitsAndResult int[2] storage holding the pixel units for the x- and y-coord to convert
218 * and the resulting values.
219 * @return result int[2] storage pixelUnitsAndResult for chaining holding the converted values
220 * @see ScalableSurface
221 */
222 public int[] convertToWindowUnits(final int[] pixelUnitsAndResult);
223
224 /**
225 * Converts the given window units into pixel units <i>in place</i>.
226 * @param windowUnitsAndResult int[2] storage holding the window units for the x- and y-coord to convert
227 * and the resulting values.
228 * @return result int[2] storage windowUnitsAndResult for chaining holding the converted values
229 * @see ScalableSurface
230 */
231 public int[] convertToPixelUnits(final int[] windowUnitsAndResult);
232
233 /**
234 * Returns the graphics configuration corresponding to this window.
235 * <p>
236 * In case the implementation utilizes a delegation pattern to wrap abstract toolkits,
237 * this method shall return the native {@link AbstractGraphicsConfiguration} via {@link AbstractGraphicsConfiguration#getNativeGraphicsConfiguration()}.
238 * </p>
239 * @see AbstractGraphicsConfiguration#getNativeGraphicsConfiguration()
240 * @see com.jogamp.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
241 */
243
244 /**
245 * Convenience: Get display handle from
246 * AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice
247 */
248 public long getDisplayHandle();
249
250 /**
251 * Convenience: Get display handle from
252 * AbstractGraphicsConfiguration . AbstractGraphicsScreen
253 */
254 public int getScreenIndex();
255
256}
257
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
A marker interface describing a graphics configuration, visual, or pixel format in a toolkit-independ...
Provides low-level information required for hardware-accelerated rendering using a surface in a platf...
int lockSurface()
Lock the surface of this native window.
static final int LOCK_SURFACE_UNLOCKED
Unlocked state, {@value}.
boolean isSurfaceLockedByOtherThread()
Query if surface is locked by another thread, i.e.
Thread getSurfaceLockOwner()
Return the locking owner's Thread, or null if not locked.
int getSurfaceWidth()
Returns the width of the client area excluding insets (window decorations) in pixel units.
static final int LOCK_SURFACE_NOT_READY
Returned by lockSurface() if the surface is not ready to be locked, {@value}.
AbstractGraphicsConfiguration getGraphicsConfiguration()
Returns the graphics configuration corresponding to this window.
long getSurfaceHandle()
Returns the handle to the surface for this NativeSurface.
int[] convertToPixelUnits(final int[] windowUnitsAndResult)
Converts the given window units into pixel units in place.
int[] convertToWindowUnits(final int[] pixelUnitsAndResult)
Converts the given pixel units into window units in place.
static final int LOCK_SURFACE_CHANGED
Returned by lockSurface() if the surface is locked, but has changed, {@value}.
void unlockSurface()
Unlock the surface of this native window.
void addSurfaceUpdatedListener(SurfaceUpdatedListener l)
Appends the given SurfaceUpdatedListener to the end of the list.
RecursiveLock getLock()
Returns the implementation's RecursiveLock synchronizing multithreaded access if used.
int getSurfaceHeight()
Returns the height of the client area excluding insets (window decorations) in pixel units.
boolean surfaceSwap()
Provide a mechanism to utilize custom (pre-) swap surface code.
long getDisplayHandle()
Convenience: Get display handle from AbstractGraphicsConfiguration .
void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
Remove the specified SurfaceUpdatedListener from the list.
int getScreenIndex()
Convenience: Get display handle from AbstractGraphicsConfiguration .
static final int LOCK_SUCCESS
Returned by lockSurface() if the surface is locked, and is unchanged, {@value}.
Clients may add their SurfaceUpdateListener implementation to a com.jogamp.nativewindow....