JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLAutoDrawableDelegate.java
Go to the documentation of this file.
1/**
2 * Copyright 2012 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.opengl;
30
31import com.jogamp.nativewindow.AbstractGraphicsDevice;
32import com.jogamp.nativewindow.NativeSurface;
33import com.jogamp.nativewindow.WindowClosingProtocol;
34import com.jogamp.nativewindow.WindowClosingProtocol.WindowClosingMode;
35import com.jogamp.opengl.GLAutoDrawable;
36import com.jogamp.opengl.GLContext;
37import com.jogamp.opengl.GLDrawable;
38import com.jogamp.opengl.GLDrawableFactory;
39import com.jogamp.opengl.GLEventListener;
40import com.jogamp.opengl.GLException;
41import com.jogamp.opengl.GLSharedContextSetter;
42
43import com.jogamp.common.util.locks.LockFactory;
44import com.jogamp.common.util.locks.RecursiveLock;
45
46import jogamp.opengl.GLAutoDrawableBase;
47import jogamp.opengl.GLContextImpl;
48import jogamp.opengl.GLDrawableImpl;
49
50
51/**
52 * Fully functional {@link GLAutoDrawable} implementation
53 * utilizing already created {@link GLDrawable} and {@link GLContext} instances.
54 * <p>
55 * Since no native windowing system events are being processed, it is recommended
56 * to handle at least the {@link com.jogamp.newt.event.WindowEvent window events}:
57 * <ul>
58 * <li>{@link com.jogamp.newt.event.WindowListener#windowRepaint(com.jogamp.newt.event.WindowUpdateEvent) repaint} using {@link #windowRepaintOp()}</li>
59 * <li>{@link com.jogamp.newt.event.WindowListener#windowResized(com.jogamp.newt.event.WindowEvent) resize} using {@link #windowResizedOp()}</li>
60 * </ul>
61 * and setup a {@link com.jogamp.newt.Window#setWindowDestroyNotifyAction(Runnable) custom toolkit destruction} issuing {@link #windowDestroyNotifyOp()}.
62 * </p>
63 * <p>
64 * See example {@link com.jogamp.opengl.test.junit.jogl.acore.TestGLAutoDrawableDelegateNEWT TestGLAutoDrawableDelegateNEWT}.
65 * </p>
66 * <p>
67 * <a name="contextSharing"><h5>OpenGL Context Sharing</h5></a>
68 * To share a {@link GLContext} see the following note in the documentation overview:
69 * <a href="../../../overview-summary.html#SHARING">context sharing</a>
70 * as well as {@link GLSharedContextSetter}.
71 * </p>
72 */
73public class GLAutoDrawableDelegate extends GLAutoDrawableBase implements GLAutoDrawable {
74 /**
75 * <p>
76 * The {@link GLContext} can be assigned later manually via {@link GLAutoDrawable#setContext(GLContext, boolean) setContext(ctx)}
77 * <i>or</i> it will be created <i>lazily</i> at the 1st {@link GLAutoDrawable#display() display()} method call.<br>
78 * <i>Lazy</i> {@link GLContext} creation will take a shared {@link GLContext} into account
79 * which has been set {@link #setSharedContext(GLContext) directly}
80 * or {@link #setSharedAutoDrawable(GLAutoDrawable) via another GLAutoDrawable}.
81 * </p>
82 * @param drawable a valid {@link GLDrawable}, may not be {@link GLDrawable#isRealized() realized} yet.
83 * @param context a valid {@link GLContext},
84 * may not have been made current (created) yet,
85 * may not be associated w/ <code>drawable<code> yet,
86 * may be <code>null</code> for lazy initialization at 1st {@link #display()}.
87 * @param upstreamWidget optional UI element holding this instance, see {@link #getUpstreamWidget()}.
88 * @param ownDevice pass <code>true</code> if {@link AbstractGraphicsDevice#close()} shall be issued,
89 * otherwise pass <code>false</code>. Closing the device is required in case
90 * the drawable is created w/ it's own new instance, e.g. offscreen drawables,
91 * and no further lifecycle handling is applied.
92 * @param lock optional custom {@link RecursiveLock}.
93 */
94 public GLAutoDrawableDelegate(final GLDrawable drawable, final GLContext context, final Object upstreamWidget, final boolean ownDevice, final RecursiveLock lock) {
95 super((GLDrawableImpl)drawable, (GLContextImpl)context, ownDevice);
96 if(null == drawable) {
97 throw new IllegalArgumentException("null drawable");
98 }
99 this.upstreamWidget = upstreamWidget;
100 this.lock = ( null != lock ) ? lock : LockFactory.createRecursiveLock() ;
101 }
102
103 //
104 // expose default methods
105 //
106
107 /** Default implementation to handle repaint events from the windowing system */
108 public final void windowRepaintOp() {
109 super.defaultWindowRepaintOp();
110 }
111
112 /**
113 * Handling resize events from the windowing system.
114 * <p>
115 * Implementation:
116 * <ul>
117 * <li>resizes {@link #getDelegatedDrawable() the GLDrawable}, if offscreen,</li>
118 * <li>triggers a pending {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape events}, and</li>
119 * <li>issues a {@link #display()} call, if no animator is present.</li>
120 * </ul>
121 * </p>
122 * <p>
123 * All required locks are being claimed.
124 * </p>
125 * @param newWidth new width in pixel units
126 * @param newWidth new height in pixel units
127 */
128 public final void windowResizedOp(final int newWidth, final int newHeight) {
129 super.defaultWindowResizedOp(newWidth, newHeight);
130 }
131
132 /**
133 * Implementation to handle destroy notifications from the windowing system.
134 *
135 * <p>
136 * If the {@link NativeSurface} does not implement {@link WindowClosingProtocol}
137 * or {@link WindowClosingMode#DISPOSE_ON_CLOSE} is enabled (default),
138 * a thread safe destruction is being induced.
139 * </p>
140 */
141 public final void windowDestroyNotifyOp() {
142 super.defaultWindowDestroyNotifyOp();
143 }
144
145 //
146 // Complete GLAutoDrawable
147 //
148
149 private Object upstreamWidget;
150 private final RecursiveLock lock;
151
152 @Override
153 public final RecursiveLock getUpstreamLock() { return lock; }
154
155 @Override
156 public final Object getUpstreamWidget() {
157 return upstreamWidget;
158 }
159
160 /**
161 * Set the upstream UI toolkit object.
162 * @see #getUpstreamWidget()
163 */
164 public final void setUpstreamWidget(final Object newUpstreamWidget) {
165 upstreamWidget = newUpstreamWidget;
166 }
167
168 /**
169 * {@inheritDoc}
170 * <p>
171 * This implementation calls {@link #defaultDestroy()}.
172 * </p>
173 * <p>
174 * User still needs to destroy the upstream window, which details are hidden from this aspect.
175 * This can be performed by overriding {@link #destroyImplInLock()}.
176 * </p>
177 */
178 @Override
179 public final void destroy() {
180 defaultDestroy();
181 }
182
183 @Override
184 protected void destroyImplInLock() {
185 super.destroyImplInLock();
186 }
187
188 @Override
189 public void display() {
190 defaultDisplay();
191 }
192
193 //
194 // GLDrawable delegation
195 //
196
197 @Override
199 return drawable.getFactory();
200 }
201
202 @Override
203 public final void swapBuffers() throws GLException {
204 defaultSwapBuffers();
205 }
206
207 @Override
208 public String toString() {
209 return getClass().getSimpleName()+"[ \n\tHelper: " + helper + ", \n\tDrawable: " + drawable +
210 ", \n\tContext: " + context + ", \n\tUpstreamWidget: "+upstreamWidget+ /** ", \n\tFactory: "+factory+ */ "]";
211 }
212}
Fully functional GLAutoDrawable implementation utilizing already created GLDrawable and GLContext ins...
final void swapBuffers()
Swaps the front and back buffers of this drawable.
final GLDrawableFactory getFactory()
Return the GLDrawableFactory being used to create this instance.
final Object getUpstreamWidget()
Method may return the upstream UI toolkit object holding this GLAutoDrawable instance,...
final void windowResizedOp(final int newWidth, final int newHeight)
Handling resize events from the windowing system.
final void windowDestroyNotifyOp()
Implementation to handle destroy notifications from the windowing system.
GLAutoDrawableDelegate(final GLDrawable drawable, final GLContext context, final Object upstreamWidget, final boolean ownDevice, final RecursiveLock lock)
final void windowRepaintOp()
Default implementation to handle repaint events from the windowing system.
final void setUpstreamWidget(final Object newUpstreamWidget)
Set the upstream UI toolkit object.
final RecursiveLock getUpstreamLock()
Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top o...
final void destroy()
Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext....
Abstraction for an OpenGL rendering context.
Definition: GLContext.java:74
static GLDrawableFactory getFactory(final GLProfile glProfile)
Returns the sole GLDrawableFactory instance.
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
A higher-level abstraction than GLDrawable which supplies an event based mechanism (GLEventListener) ...
An abstraction for an OpenGL rendering target.
Definition: GLDrawable.java:51