JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLSharedContextSetter.java
Go to the documentation of this file.
1/**
2 * Copyright 2013 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.opengl.GLRendererQuirks;
32
33/**
34 * Adds capabilities to set a shared {@link GLContext} directly or via an {@link GLAutoDrawable}.
35 * <p>
36 * Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs,
37 * and textures among OpenGL contexts is supported with this interface.
38 * </p>
39 * <p>
40 * A <i>master</i> {@link GLContext} is the {@link GLContext} which is created first.
41 * Subsequent shared {@link GLContext} w/ the <i>master</i> are referred as <i>slave</i> {@link GLContext}.
42 * </p>
43 * <p>
44 * Implementations of this interface control the <i>slave's</i> {@link GLContext} and {@link GLAutoDrawable} realization,
45 * i.e. the <i>slave</i> {@link GLAutoDrawable} will not be realized before their associated <i>master</i>.
46 * </p>
47 * <p>
48 * Using the nearest or same {@link GLCapabilitiesImmutable#getVisualID(com.jogamp.nativewindow.VisualIDHolder.VIDType) visual ID}
49 * or {@link GLCapabilitiesImmutable caps} across the shared {@link GLDrawable}s will yield best compatibility.
50 * </p>
51 * <h5><a name="lifecycle">Lifecycle Considerations</a></h5>
52 * <p>
53 * After shared objects are created on the <i>master</i>, the OpenGL pipeline
54 * might need to be synchronized w/ the <i>slaves</i>, e.g. via {@link GL#glFinish()}.
55 * At least this has been experienced w/ OSX 10.9.
56 * </p>
57 * <p>
58 * In general, destroying a <i>master</i> {@link GLContext} before their shared <i>slaves</i>
59 * shall be permissible, i.e. the OpenGL driver needs to handle pending destruction of shared resources.
60 * This is confirmed to work properly on most platform/driver combinations,
61 * see unit test <code>com.jogamp.opengl.test.junit.jogl.acore.TestSharedContextVBOES2NEWT3</code> and similar.
62 * </p>
63 * <p>
64 * However, to avoid scenarios with buggy drivers, users <i>may not</i> destroy the
65 * <i>master</i> {@link GLContext} before its shared <i>slave</i> {@link GLContext} instances
66 * <i>as long as they are using them</i>.<br>
67 * Otherwise the OpenGL driver may crash w/ SIGSEGV, due to using already destroyed shared resources,
68 * if not handling the pending destruction of the latter!<br>
69 * Either proper lifecycle synchronization is implemented, e.g. by notifying the <i>slaves</i> about the loss of the shared resources,
70 * <i>or</i> the <i>slaves</i> validate whether the resources are still valid.
71 * </p>
72 * <p>
73 * To simplify above lifecycle issues, one may use a {@link GLDrawableFactory#createDummyDrawable(com.jogamp.nativewindow.AbstractGraphicsDevice, boolean, GLCapabilitiesImmutable, GLCapabilitiesChooser) dummy}
74 * {@link GLDrawable} and it's {@link GLContext} as the <i>master</i> of all shared <i>slave</i> {@link GLContext}.
75 * Since this <i>dummy instance</i> does not depend on any native windowing system, it can be controlled easily w/o being <i>in sight</i>.<br>
76 * Below code creates a {@link GLAutoDrawable} based on a <i>dummy GLDrawable</i>:
77 * <pre>
78 // GLProfile and GLCapabilities should be equal across all shared GL drawable/context.
79 final GLCapabilitiesImmutable caps = ... ;
80 final GLProfile glp = caps.getGLProfile();
81 ..
82 final boolean createNewDevice = true; // use 'own' display device!
83 final GLAutoDrawable sharedDrawable = GLDrawableFactory.getFactory(glp).createDummyAutoDrawable(null, createNewDevice, caps, null);
84 sharedDrawable.display(); // triggers GLContext object creation and native realization.
85 ...
86 // Later a shared 'slave' can be created e.g.:
87 GLWindow glad = GLWindow.create(caps); // or any other GLAutoDrawable supporting GLSharedContextSetter
88 glad.setSharedAutoDrawable(sharedDrawable);
89 glad.addGLEventListener(..);
90 glad.setVisible(true); // GLWindow creation ..
91 * </pre>
92 * </p>
93 * <h5><a name="synchronization">GL Object Synchronization</a></h5>
94 * <p>
95 * Usually synchronization of shared GL objects should not be required, if the shared GL objects
96 * are created and immutable before concurrent usage.
97 * </p>
98 * <p>
99 * However, using drivers exposing {@link GLRendererQuirks#NeedSharedObjectSync} always
100 * require the user to synchronize access of shared GL objects.
101 * </p>
102 * <p>
103 * Synchronization can be avoided if accessing the shared GL objects
104 * exclusively via a queue or {@link com.jogamp.common.util.Ringbuffer Ringbuffer}, see GLMediaPlayerImpl as an example.
105 * </p>
106 * </p>
107 * <h5><a name="driverissues">Known Driver Issues</a></h5>
108 * <h7><a name="intelmesa">Intel's Mesa >= 9.1.2 Backend for [Sandybridge/Ivybridge] on GNU/Linux</a></h7>
109 * <p>
110 * <pre>
111 * Error: 'intel_do_flush_locked: No such file or directory'
112 * JogAmp: https://jogamp.org/bugzilla/show_bug.cgi?id=873
113 * freedesktop.org: https://bugs.freedesktop.org/show_bug.cgi?id=41736#c8
114 * </pre>
115 * Shared context seems not to be supported w/ lock-free bound X11 display connections
116 * per OpenGL drawable/context. The error message above is thrown in this case.
117 * Hence the driver bug renders shared context use w/ JOGL impossible.
118 * </p>
119 * <h7><a name="hisilicon">Hisilicon's Immersion.16 on Android</a></h7>
120 * <p>
121 * We failed to create a shared ES2 context on another thread.
122 * </p>
123 */
124public interface GLSharedContextSetter extends GLAutoDrawable {
125 /**
126 * Specifies an {@link GLContext OpenGL context}, which shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
127 * <p>
128 * Since the {@link GLDrawable drawable} and {@link GLContext context} is created
129 * at {@link GLAutoDrawable#initialization GLAutoDrawable initialization}
130 * this method shall be called beforehand to have any effect.
131 * </p>
132 * <p>
133 * A set <i>sharedContext</i> will block context creation, i.e. {@link GLAutoDrawable#initialization GLAutoDrawable initialization},
134 * as long it is not {@link GLContext#isCreated() created natively}.
135 * </p>
136 * <p>
137 * The <i>preferred method</i> of assigning a <i>shared context</i> is
138 * to {@link #setSharedAutoDrawable(GLAutoDrawable) set the shared GLAutoDrawable},
139 * since this method also takes the {@link GLEventListener}
140 * {@link GLAutoDrawable#areAllGLEventListenerInitialized() initialization into account}.
141 * </p>
142 * <p>
143 * See <a href="#lifecycle">Lifecycle Considerations</a>.
144 * </p>
145 *
146 * @param sharedContext The OpenGL context to be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
147 * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
148 * or {@link #setSharedAutoDrawable(GLAutoDrawable) shared GLAutoDrawable} is already set,
149 * the given sharedContext is null or equal to this {@link GLAutoDrawable}'s context.
150 * @see #setSharedAutoDrawable(GLAutoDrawable)
151 */
152 void setSharedContext(GLContext sharedContext) throws IllegalStateException;
153
154 /**
155 * Specifies an {@link GLAutoDrawable}, which {@link GLContext OpenGL context} shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
156 * <p>
157 * Since the {@link GLDrawable drawable} and {@link GLContext context} is created
158 * at {@link GLAutoDrawable#initialization GLAutoDrawable initialization}
159 * this method shall be called beforehand to have any effect.
160 * </p>
161 * <p>
162 * A set <i>sharedAutoDrawable</i> will block context creation, i.e. <a href="GLAutoDrawable.html#initialization">initialization</a>
163 * as long it's
164 * <ul>
165 * <li>{@link GLContext} is <code>null</code>, or</li>
166 * <li>{@link GLContext} has not been {@link GLContext#isCreated() created natively}, or</li>
167 * <li>{@link GLEventListener} are <i>not</i> {@link GLAutoDrawable#areAllGLEventListenerInitialized() completely initialized}</li>
168 * </ul>
169 * </p>
170 * <p>
171 * See <a href="#lifecycle">Lifecycle Considerations</a>.
172 * </p>
173 *
174 * @param sharedContext The GLAutoDrawable, which OpenGL context shall be shared by this {@link GLAutoDrawable}'s {@link GLContext}.
175 * @throws IllegalStateException if a {@link #setSharedContext(GLContext) shared GLContext}
176 * or {@link #setSharedAutoDrawable(GLAutoDrawable) shared GLAutoDrawable} is already set,
177 * the given sharedAutoDrawable is null or equal to this GLAutoDrawable.
178 * @see #setSharedContext(GLContext)
179 */
180 void setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable) throws IllegalStateException;
181}
Abstraction for an OpenGL rendering context.
Definition: GLContext.java:74
A higher-level abstraction than GLDrawable which supplies an event based mechanism (GLEventListener) ...
Adds capabilities to set a shared GLContext directly or via an GLAutoDrawable.
void setSharedAutoDrawable(GLAutoDrawable sharedAutoDrawable)
Specifies an GLAutoDrawable, which OpenGL context shall be shared by this GLAutoDrawable's GLContext.
void setSharedContext(GLContext sharedContext)
Specifies an OpenGL context, which shall be shared by this GLAutoDrawable's GLContext.