JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLDrawable.java
Go to the documentation of this file.
1/**
2 * Copyright (c) 2010-2023 JogAmp Community. All rights reserved.
3 * Copyright (c) 2003 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 * You acknowledge that this software is not designed or intended for use
34 * in the design, construction, operation or maintenance of any nuclear
35 * facility.
36 */
37
38package com.jogamp.opengl;
39
40import com.jogamp.nativewindow.AbstractGraphicsConfiguration;
41import com.jogamp.nativewindow.NativeSurface;
42import com.jogamp.nativewindow.NativeSurfaceHolder;
43
44
45/** An abstraction for an OpenGL rendering target. A GLDrawable's
46 primary functionality is to create OpenGL contexts which can be
47 used to perform rendering. A GLDrawable does not automatically
48 create an OpenGL context, but all implementations of {@link
49 GLAutoDrawable} do so upon creation. */
50
51public interface GLDrawable extends NativeSurfaceHolder {
52 /**
53 * Creates a new context for drawing to this drawable that will
54 * optionally share buffer objects, textures and other server-side OpenGL
55 * objects with the specified GLContext.
56 * <p>
57 * The GLContext <code>share</code> need not be associated with this
58 * GLDrawable and may be null if sharing of display lists and other
59 * objects is not desired. See the note in the overview
60 * documentation
61 * <a href="../../../overview-summary.html#SHARING">context sharing</a>
62 * as well as {@link GLSharedContextSetter}.
63 * </p>
64 */
66
67 /**
68 * Indicates to GLDrawable implementations whether the
69 * underlying {@link NativeSurface surface} has been created and can be drawn into.
70 * <p>
71 * If realized, the {@link #getHandle() drawable handle} may become
72 * valid while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
73 * </p>
74 * <p>
75 * End users do not need to call this method; it is not necessary to
76 * call <code>setRealized</code> on a {@link GLAutoDrawable}
77 * as these perform the appropriate calls on their underlying GLDrawables internally.
78 * </p>
79 * <p>
80 * Developers implementing new OpenGL components for various window
81 * toolkits need to call this method against GLDrawables obtained
82 * from the GLDrawableFactory via the
83 * {@link GLDrawableFactory#createGLDrawable(NativeSurface)} method.
84 * It must typically be
85 * called with an argument of <code>true</code> when the component
86 * associated with the GLDrawable is realized and with an argument
87 * of <code>false</code> just before the component is unrealized.
88 * For the AWT, this means calling <code>setRealized(true)</code> in
89 * the <code>addNotify</code> method and with an argument of
90 * <code>false</code> in the <code>removeNotify</code> method.
91 * </p>
92 * <p>
93 * <code>GLDrawable</code> implementations should handle multiple
94 * cycles of <code>setRealized(true)</code> /
95 * <code>setRealized(false)</code> calls. Most, if not all, Java
96 * window toolkits have a persistent object associated with a given
97 * component, regardless of whether that component is currently
98 * realized. The <CODE>GLDrawable</CODE> object associated with a
99 * particular component is intended to be similarly persistent. A
100 * <CODE>GLDrawable</CODE> is intended to be created for a given
101 * component when it is constructed and live as long as that
102 * component. <code>setRealized</code> allows the
103 * <code>GLDrawable</code> to re-initialize and destroy any
104 * associated resources as the component becomes realized and
105 * unrealized, respectively.
106 * </p>
107 * <p>
108 * With an argument of <code>true</code>,
109 * the minimum implementation shall call
110 * {@link NativeSurface#lockSurface() NativeSurface's lockSurface()} and if successful:
111 * <ul>
112 * <li> Update the {@link GLCapabilities}, which are associated with
113 * the attached {@link NativeSurface}'s {@link AbstractGraphicsConfiguration}.</li>
114 * <li> Release the lock with {@link NativeSurface#unlockSurface() NativeSurface's unlockSurface()}.</li>
115 * </ul><br>
116 * This is important since {@link NativeSurface#lockSurface() NativeSurface's lockSurface()}
117 * ensures resolving the window/surface handles, and the drawable's {@link GLCapabilities}
118 * might have changed.
119 * </p>
120 * <p>
121 * Calling this method has no other effects. For example, if
122 * <code>removeNotify</code> is called on a Canvas implementation
123 * for which a GLDrawable has been created, it is also necessary to
124 * destroy all OpenGL contexts associated with that GLDrawable. This
125 * is not done automatically by the implementation.
126 * </p>
127 * @see #isRealized()
128 * @see #getHandle()
129 * @see NativeSurface#lockSurface()
130 */
131 public void setRealized(boolean realized);
132
133 /**
134 * Returns <code>true</code> if this drawable is realized, otherwise <code>false</code>.
135 * <p>
136 * A drawable can be realized and unrealized via {@link #setRealized(boolean)}.
137 * </p>
138 * @see #setRealized(boolean)
139 */
140 public boolean isRealized();
141
142 /**
143 * Returns the width of this {@link GLDrawable}'s {@link #getNativeSurface() surface} client area in pixel units.
144 * @see NativeSurface#getSurfaceWidth()
145 */
146 public int getSurfaceWidth();
147
148 /**
149 * Returns the height of this {@link GLDrawable}'s {@link #getNativeSurface() surface} client area in pixel units.
150 * @see NativeSurface#getSurfaceHeight()
151 */
152 public int getSurfaceHeight();
153
154 /**
155 * Returns <code>true</code> if the drawable is rendered in
156 * OpenGL's coordinate system, <i>origin at bottom left</i>.
157 * Otherwise returns <code>false</code>, i.e. <i>origin at top left</i>.
158 * <p>
159 * Default impl. is <code>true</code>, i.e. OpenGL coordinate system.
160 * </p>
161 * <p>
162 * Currently only MS-Windows bitmap offscreen drawable uses a non OpenGL orientation and hence returns <code>false</code>.<br/>
163 * This removes the need of a vertical flip when used in AWT or Windows applications.
164 * </p>
165 */
166 public boolean isGLOriented();
167
168 /** Swaps the front and back buffers of this drawable. For {@link
169 GLAutoDrawable} implementations, when automatic buffer swapping
170 is enabled (as is the default), this method is called
171 automatically and should not be called by the end user. */
172 public void swapBuffers() throws GLException;
173
174 /** Fetches the {@link GLCapabilitiesImmutable} corresponding to the chosen
175 OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
176 <p>
177 This query only returns the chosen capabilities if {@link #isRealized()}.
178 </p>
179 <p>
180 On some platforms, the pixel format is not directly associated
181 with the drawable; a best attempt is made to return a reasonable
182 value in this case.
183 </p>
184 <p>
185 This object shall be directly associated to the attached {@link NativeSurface}'s
186 {@link AbstractGraphicsConfiguration}, and if changes are necessary,
187 they should reflect those as well.
188 </p>
189 @return The immutable queried instance.
190 @see #getRequestedGLCapabilities()
191 */
193
194 /** Fetches the {@link GLCapabilitiesImmutable} corresponding to the user requested
195 OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
196 <p>
197 If {@link #isRealized() realized}, {@link #getChosenGLCapabilities() the chosen capabilities}
198 reflect the actual selected OpenGL capabilities.
199 </p>
200 @return The immutable queried instance.
201 @see #getChosenGLCapabilities()
202 @since 2.2
203 */
205
206 /** Fetches the {@link GLProfile} for this drawable.
207 Returns the GLProfile object, no copy.
208 */
210
211 /**
212 * {@inheritDoc}
213 * <p>
214 * Returns the underlying {@link NativeSurface} which {@link NativeSurface#getSurfaceHandle() native handle}
215 * represents this OpenGL drawable's native resource.
216 * </p>
217 *
218 * @see #getHandle()
219 */
220 @Override
222
223 /**
224 * Returns the GL drawable handle,
225 * guaranteed to be valid after {@link #setRealized(boolean) realization}
226 * <i>and</i> while it's {@link NativeSurface surface} is being {@link NativeSurface#lockSurface() locked}.
227 * <p>
228 * It is usually identical to the underlying windowing toolkit {@link NativeSurface surface}'s
229 * {@link com.jogamp.nativewindow.NativeSurface#getSurfaceHandle() handle}
230 * or an intermediate layer to suite GL, e.g. an EGL surface.
231 * </p>
232 * <p>
233 * On EGL it is represented by the EGLSurface.<br>
234 * On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.<br>
235 * On Windows it is represented by the HDC, which may change with each {@link NativeSurface#lockSurface()}.<br>
236 * </p>
237 * @see #setRealized(boolean)
238 * @see NativeSurface#lockSurface()
239 * @see NativeSurface#unlockSurface()
240 */
241 public long getHandle();
242
243 /** Return the {@link GLDrawableFactory} being used to create this instance. */
245
246 @Override
247 public String toString();
248}
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...
Specifies the the OpenGL profile.
Definition: GLProfile.java:77
Accessor interface for implementing classes with ownership of a NativeSurface via an is-a or has-a re...
Provides low-level information required for hardware-accelerated rendering using a surface in a platf...
Specifies an immutable set of OpenGL capabilities.
An abstraction for an OpenGL rendering target.
Definition: GLDrawable.java:51
GLCapabilitiesImmutable getChosenGLCapabilities()
Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / v...
int getSurfaceWidth()
Returns the width of this GLDrawable's surface client area in pixel units.
GLCapabilitiesImmutable getRequestedGLCapabilities()
Fetches the GLCapabilitiesImmutable corresponding to the user requested OpenGL capabilities (pixel fo...
long getHandle()
Returns the GL drawable handle, guaranteed to be valid after realization and while it's surface is be...
boolean isRealized()
Returns true if this drawable is realized, otherwise false.
boolean isGLOriented()
Returns true if the drawable is rendered in OpenGL's coordinate system, origin at bottom left.
NativeSurface getNativeSurface()
Returns the associated NativeSurface of this NativeSurfaceHolder.
GLDrawableFactory getFactory()
Return the GLDrawableFactory being used to create this instance.
void setRealized(boolean realized)
Indicates to GLDrawable implementations whether the underlying surface has been created and can be dr...
int getSurfaceHeight()
Returns the height of this GLDrawable's surface client area in pixel units.
void swapBuffers()
Swaps the front and back buffers of this drawable.
GLContext createContext(GLContext shareWith)
Creates a new context for drawing to this drawable that will optionally share buffer objects,...
GLProfile getGLProfile()
Fetches the GLProfile for this drawable.