JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLFBODrawable.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.NativeWindowException;
32
33import com.jogamp.opengl.FBObject;
34import com.jogamp.opengl.FBObject.Colorbuffer;
35import com.jogamp.opengl.FBObject.ColorAttachment;
36import com.jogamp.opengl.FBObject.TextureAttachment;
37import com.jogamp.opengl.GLRendererQuirks;
38
39/**
40 * Platform-independent {@link GLDrawable} specialization,
41 * exposing {@link FBObject} functionality.
42 *
43 * <p>
44 * A {@link GLFBODrawable} is uninitialized until a {@link GLContext} is bound
45 * and made current the first time, hence only then it's capabilities <i>fully</i> reflect expectations,
46 * i.e. color, depth, stencil and MSAA bits will be <i>valid</i> only after the first {@link GLContext#makeCurrent() makeCurrent()} call.
47 * On-/offscreen bits are <i>valid</i> after {@link #setRealized(boolean) setRealized(true)}.
48 * </p>
49 *
50 * <p>
51 * MSAA is used if {@link GLCapabilitiesImmutable#getNumSamples() requested}.
52 * </p>
53 * <p>
54 * Double buffering is used if {@link GLCapabilitiesImmutable#getDoubleBuffered() requested}.
55 * </p>
56 * <p>
57 * In MSAA mode, it always uses the implicit 2nd {@link FBObject framebuffer} {@link FBObject#getSamplingSinkFBO() sink}.
58 * Hence double buffering is always the case w/ MSAA.
59 * </p>
60 * <p>
61 * In non MSAA a second explicit {@link FBObject framebuffer} is being used.
62 * This method allows compliance w/ the spec, i.e. read and draw framebuffer selection
63 * and double buffer usage for e.g. {@link GL#glReadPixels(int, int, int, int, int, int, java.nio.Buffer) glReadPixels(..)}.
64 * This method also allows usage of both textures seperately.
65 * </p>
66 * <p>
67 * It would be possible to implement double buffering simply using
68 * {@link Colorbuffer}s with one {@link FBObject framebuffer}.
69 * This would require mode selection and hence complicate the API. Besides, it would
70 * not support differentiation of read and write framebuffer and hence not be spec compliant.
71 * </p>
72 * <p>
73 * Actual swapping of the {@link Colorbuffer}s and/or {@link FBObject framebuffer}
74 * is performed either in the {@link jogamp.opengl.GLContextImpl#contextMadeCurrent(boolean) context current hook}
75 * or when {@link jogamp.opengl.GLDrawableImpl#swapBuffersImpl(boolean) swapping buffers}, whatever comes first.
76 * </p>
77 */
78public interface GLFBODrawable extends GLDrawable {
79 // public enum DoubleBufferMode { NONE, TEXTURE, FBO }; // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
80
81 /** FBO Mode Bit: Use a {@link TextureAttachment} for the {@link #getColorbuffer(int) render colorbuffer}, see {@link #setFBOMode(int)}. */
82 public static final int FBOMODE_USE_TEXTURE = 1 << 0;
83
84 /**
85 * @return <code>true</code> if initialized, i.e. a {@link GLContext} is bound and made current once, otherwise <code>false</code>.
86 */
87 public boolean isInitialized();
88
89 /**
90 * Set the FBO mode bits used for FBO creation.
91 * <p>
92 * Default value is: {@link #FBOMODE_USE_TEXTURE}.
93 * </p>
94 * <p>
95 * If {@link GLRendererQuirks#BuggyColorRenderbuffer} is set,
96 * {@link #FBOMODE_USE_TEXTURE} is always added at initialization.
97 * </p>
98 *
99 * @param modeBits custom FBO mode bits like {@link #FBOMODE_USE_TEXTURE}.
100 * @throws IllegalStateException if already initialized, see {@link #isInitialized()}.
101 */
102 void setFBOMode(final int modeBits) throws IllegalStateException;
103
104 /**
105 * @return the used FBO mode bits, mutable via {@link #setFBOMode(int)}
106 */
108
109 /**
110 * Notify this instance about upstream size change
111 * to reconfigure the {@link FBObject}.
112 * @param gl GL context object bound to this drawable, will be made current during operation.
113 * A prev. current context will be make current after operation.
114 * @throws GLException if resize operation failed
115 */
116 void resetSize(final GL gl) throws GLException;
117
118 /**
119 * @return the used texture unit
120 */
122
123 /**
124 *
125 * @param unit the texture unit to be used
126 */
127 void setTextureUnit(final int unit);
128
129 /**
130 * Set the number of sample buffers if using MSAA
131 *
132 * @param gl GL context object bound to this drawable, will be made current during operation.
133 * A prev. current context will be make current after operation.
134 * @param newSamples new sample size
135 * @throws GLException if resetting the FBO failed
136 */
137 void setNumSamples(final GL gl, final int newSamples) throws GLException;
138
139 /**
140 * @return the number of sample buffers if using MSAA, otherwise 0
141 */
143
144 /**
145 * Sets the number of buffers (FBO) being used if using {@link GLCapabilities#getDoubleBuffered() double buffering}.
146 * <p>
147 * If {@link GLCapabilities#getDoubleBuffered() double buffering} is not chosen, this is a NOP.
148 * </p>
149 * <p>
150 * Must be called before {@link #isInitialized() initialization}, otherwise an exception is thrown.
151 * </p>
152 * @return the new number of buffers (FBO) used, maybe different than the requested <code>bufferCount</code> (see above)
153 * @throws IllegalStateException if already initialized, see {@link #isInitialized()}.
154 */
155 int setNumBuffers(final int bufferCount) throws IllegalStateException, GLException;
156
157 /**
158 * @return the number of buffers (FBO) being used. 1 if not using {@link GLCapabilities#getDoubleBuffered() double buffering},
159 * otherwise &ge; 2, depending on {@link #setNumBuffers(int)}.
160 */
162
163 /**
164 * @return the used {@link DoubleBufferMode}
165 */
166 // DoubleBufferMode getDoubleBufferMode(); // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
167
168 /**
169 * Sets the {@link DoubleBufferMode}. Must be called before {@link #isInitialized() initialization},
170 * otherwise an exception is thrown.
171 * <p>
172 * This call has no effect is MSAA is selected, since MSAA always forces the mode to {@link DoubleBufferMode#FBO FBO}.
173 * Also setting the mode to {@link DoubleBufferMode#NONE NONE} where double buffering is {@link GLCapabilitiesImmutable#getDoubleBuffered() requested}
174 * or setting a double buffering mode w/o {@link GLCapabilitiesImmutable#getDoubleBuffered() request} will be ignored.
175 * </p>
176 * <p>
177 * Since {@link DoubleBufferMode#TEXTURE TEXTURE} mode is currently not implemented, this method has no effect.
178 * </p>
179 * @throws GLException if already initialized, see {@link #isInitialized()}.
180 */
181 // void setDoubleBufferMode(DoubleBufferMode mode) throws GLException; // TODO: Add or remove TEXTURE (only) DoubleBufferMode support
182
183 /**
184 * If MSAA is being used and {@link GL#GL_FRONT} is requested,
185 * the internal {@link FBObject} {@link FBObject#getSamplingSinkFBO() sample sink} is being returned.
186 *
187 * @param bufferName {@link GL#GL_FRONT} and {@link GL#GL_BACK} are valid buffer names
188 * @return the named {@link FBObject}
189 * @throws IllegalArgumentException if an illegal buffer name is being used
190 */
191 FBObject getFBObject(final int bufferName) throws IllegalArgumentException;
192
193 /**
194 * Returns the named {@link Colorbuffer} instance.
195 * <p>
196 * If MSAA is being used, only the {@link GL#GL_FRONT} buffer is accessible
197 * and an exception is being thrown if {@link GL#GL_BACK} is being requested.
198 * </p>
199 * <p>
200 * Depending on the {@link #setFBOMode(int) fbo mode} the resulting {@link Colorbuffer}
201 * is either a {@link TextureAttachment} if {@link #FBOMODE_USE_TEXTURE} is set,
202 * otherwise a {@link ColorAttachment}.
203 * See {@link Colorbuffer#isTextureAttachment()}.
204 * </p>
205 * @param bufferName {@link GL#GL_FRONT} and {@link GL#GL_BACK} are valid buffer names
206 * @return the named {@link Colorbuffer}
207 * @throws IllegalArgumentException if using MSAA and {@link GL#GL_BACK} is requested or an illegal buffer name is being used
208 */
209 Colorbuffer getColorbuffer(final int bufferName) throws IllegalArgumentException;
210
211 /** Resizeable {@link GLFBODrawable} specialization */
212 public interface Resizeable extends GLFBODrawable {
213 /**
214 * Resize this {@link GLFBODrawable}'s surface.
215 * <p>
216 * This drawable is being locked during operation.
217 * </p>
218 * @param context the {@link GLContext} bound to this drawable, will be made current during operation
219 * A prev. current context will be make current after operation.
220 * @param newWidth new width in pixel units
221 * @param newHeight new width in pixel units
222 * @throws NativeWindowException in case the surface could no be locked
223 * @throws GLException in case an error during the resize operation occurred
224 */
225 void setSurfaceSize(GLContext context, int newWidth, int newHeight) throws NativeWindowException, GLException;
226 }
227}
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Core utility class simplifying usage of framebuffer objects (FBO) with all GLProfiles.
Definition: FBObject.java:53
Abstraction for an OpenGL rendering context.
Definition: GLContext.java:74
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Generic color buffer FBO attachment, either of type ColorAttachment or TextureAttachment.
Definition: FBObject.java:70
An abstraction for an OpenGL rendering target.
Definition: GLDrawable.java:51
Resizeable GLFBODrawable specialization.
void setSurfaceSize(GLContext context, int newWidth, int newHeight)
Resize this GLFBODrawable's surface.
Platform-independent GLDrawable specialization, exposing FBObject functionality.
static final int FBOMODE_USE_TEXTURE
FBO Mode Bit: Use a TextureAttachment for the render colorbuffer, see setFBOMode(int).
int setNumBuffers(final int bufferCount)
Sets the number of buffers (FBO) being used if using double buffering.
void setNumSamples(final GL gl, final int newSamples)
Set the number of sample buffers if using MSAA.
void setFBOMode(final int modeBits)
Set the FBO mode bits used for FBO creation.
FBObject getFBObject(final int bufferName)
Sets the DoubleBufferMode.
void resetSize(final GL gl)
Notify this instance about upstream size change to reconfigure the FBObject.
Colorbuffer getColorbuffer(final int bufferName)
Returns the named Colorbuffer instance.
void setTextureUnit(final int unit)