JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLCapabilities.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2003-2009 Sun Microsystems, Inc. All Rights Reserved.
3 * Copyright (c) 2010 JogAmp Community. 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 * Sun gratefully acknowledges that this software was originally authored
38 * and developed by Kenneth Bradley Russell and Christopher John Kline.
39 */
40
41package com.jogamp.opengl;
42
43import com.jogamp.nativewindow.Capabilities;
44import com.jogamp.nativewindow.CapabilitiesImmutable;
45
46/** Specifies a set of OpenGL capabilities.<br>
47 At creation time of a {@link GLDrawable} using {@link GLDrawableFactory},
48 an instance of this class is passed,
49 describing the desired capabilities that a rendering context
50 must support, such as the OpenGL profile, color depth and whether stereo is enabled.<br>
51
52 The actual capabilites of created {@link GLDrawable}s are then reflected by their own
53 GLCapabilites instance, which can be queried with {@link GLDrawable#getChosenGLCapabilities()}.
54 <br>
55
56 It currently contains the minimal number of routines which allow
57 configuration on all supported window systems. */
58public class GLCapabilities extends Capabilities implements Cloneable, GLCapabilitiesImmutable {
59 private GLProfile glProfile = null;
60 private boolean isPBuffer = false;
61 private boolean isFBO = false;
62 private boolean doubleBuffered = true;
63 private boolean stereo = false;
64 private boolean hardwareAccelerated = true;
65 private int depthBits = 16;
66 private int stencilBits = 0;
67 private int accumRedBits = 0;
68 private int accumGreenBits = 0;
69 private int accumBlueBits = 0;
70 private int accumAlphaBits = 0;
71 // Shift bits from PIXELFORMATDESCRIPTOR not present because they
72 // are unlikely to be supported on Windows anyway
73
74 // Support for full-scene antialiasing (FSAA)
75 private String sampleExtension = DEFAULT_SAMPLE_EXTENSION;
76 private boolean sampleBuffers = false;
77 private int numSamples = 2;
78
79 /** Creates a GLCapabilities object. All attributes are in a default state.
80 * @param glp GLProfile, or null for the default GLProfile
81 * @throws GLException if no profile is given and no default profile is available for the default device.
82 */
83 public GLCapabilities(final GLProfile glp) throws GLException {
84 glProfile = (null!=glp)?glp:GLProfile.getDefault(GLProfile.getDefaultDevice());
85 }
86
87 @Override
88 public Object cloneMutable() {
89 return clone();
90 }
91
92 @Override
93 public Object clone() {
94 try {
95 return super.clone();
96 } catch (final RuntimeException e) {
97 throw new GLException(e);
98 }
99 }
100
101 /**
102 * Copies all {@link CapabilitiesImmutable} values
103 * from <code>source</code> into this instance.
104 * @return this instance
105 */
107 super.copyFrom(source);
108 return this;
109 }
110
111 /**
112 * Copies all {@link GLCapabilitiesImmutable} values
113 * from <code>source</code> into this instance.
114 * @return this instance
115 */
117 super.copyFrom(source);
118 glProfile = source.getGLProfile();
119 isPBuffer = source.isPBuffer();
120 isFBO = source.isFBO();
121 doubleBuffered = source.getDoubleBuffered();
122 stereo = source.getStereo();
123 hardwareAccelerated = source.getHardwareAccelerated();
124 depthBits = source.getDepthBits();
125 stencilBits = source.getStencilBits();
126 accumRedBits = source.getAccumRedBits();
127 accumGreenBits = source.getAccumGreenBits();
128 accumBlueBits = source.getAccumBlueBits();
129 accumAlphaBits = source.getAccumAlphaBits();
130 sampleBuffers = source.getSampleBuffers();
131 numSamples = source.getNumSamples();
132 sampleExtension = source.getSampleExtension();
133 return this;
134 }
135
136 @Override
137 public int hashCode() {
138 // 31 * x == (x << 5) - x
139 int hash = super.hashCode();
140 hash = ((hash << 5) - hash) + this.glProfile.hashCode() ;
141 hash = ((hash << 5) - hash) + ( this.hardwareAccelerated ? 1 : 0 );
142 hash = ((hash << 5) - hash) + ( this.stereo ? 1 : 0 );
143 hash = ((hash << 5) - hash) + ( this.isFBO ? 1 : 0 );
144 hash = ((hash << 5) - hash) + ( this.isPBuffer ? 1 : 0 );
145 hash = ((hash << 5) - hash) + ( this.sampleBuffers ? 1 : 0 );
146 hash = ((hash << 5) - hash) + this.getNumSamples();
147 hash = ((hash << 5) - hash) + this.sampleExtension.hashCode();
148 hash = ((hash << 5) - hash) + this.depthBits;
149 hash = ((hash << 5) - hash) + this.stencilBits;
150 hash = ((hash << 5) - hash) + this.accumRedBits;
151 hash = ((hash << 5) - hash) + this.accumGreenBits;
152 hash = ((hash << 5) - hash) + this.accumBlueBits;
153 hash = ((hash << 5) - hash) + this.accumAlphaBits;
154 return hash;
155 }
156
157 @Override
158 public boolean equals(final Object obj) {
159 if(this == obj) { return true; }
160 if(!(obj instanceof GLCapabilitiesImmutable)) {
161 return false;
162 }
164 boolean res = super.equals(obj) &&
165 other.getGLProfile()==glProfile &&
166 other.isPBuffer()==isPBuffer &&
167 other.isFBO()==isFBO &&
168 other.getDoubleBuffered() == doubleBuffered &&
169 other.getStereo()==stereo &&
170 other.getHardwareAccelerated()==hardwareAccelerated &&
171 other.getDepthBits()==depthBits &&
172 other.getStencilBits()==stencilBits &&
173 other.getAccumRedBits()==accumRedBits &&
174 other.getAccumGreenBits()==accumGreenBits &&
175 other.getAccumBlueBits()==accumBlueBits &&
176 other.getAccumAlphaBits()==accumAlphaBits &&
177 other.getSampleBuffers()==sampleBuffers;
178 if(res && sampleBuffers) {
179 res = other.getNumSamples()==getNumSamples() &&
180 other.getSampleExtension().equals(sampleExtension) ;
181 }
182 return res;
183 }
184
185 /** comparing hw/sw, stereo, multisample, stencil, RGBA and depth only */
186 @Override
187 public int compareTo(final CapabilitiesImmutable o) {
188 if ( ! ( o instanceof GLCapabilitiesImmutable ) ) {
189 final Class<?> c = (null != o) ? o.getClass() : null ;
190 throw new ClassCastException("Not a GLCapabilitiesImmutable object, but " + c);
191 }
193
194 if(hardwareAccelerated && !caps.getHardwareAccelerated()) {
195 return 1;
196 } else if(!hardwareAccelerated && caps.getHardwareAccelerated()) {
197 return -1;
198 }
199
200 if(stereo && !caps.getStereo()) {
201 return 1;
202 } else if(!stereo && caps.getStereo()) {
203 return -1;
204 }
205
206 if(doubleBuffered && !caps.getDoubleBuffered()) {
207 return 1;
208 } else if(!doubleBuffered && caps.getDoubleBuffered()) {
209 return -1;
210 }
211
212 final int ms = getNumSamples();
213 final int xms = caps.getNumSamples() ;
214
215 if(ms > xms) {
216 return 1;
217 } else if( ms < xms ) {
218 return -1;
219 }
220 // ignore the sample extension
221
222 if(stencilBits > caps.getStencilBits()) {
223 return 1;
224 } else if(stencilBits < caps.getStencilBits()) {
225 return -1;
226 }
227
228 final int sc = super.compareTo(caps); // RGBA
229 if(0 != sc) {
230 return sc;
231 }
232
233 if(depthBits > caps.getDepthBits()) {
234 return 1;
235 } else if(depthBits < caps.getDepthBits()) {
236 return -1;
237 }
238
239 return 0; // they are equal: hw/sw, stereo, multisample, stencil, RGBA and depth
240 }
241
242 @Override
243 public final GLProfile getGLProfile() {
244 return glProfile;
245 }
246
247 /** Sets the GL profile you desire */
248 public void setGLProfile(final GLProfile profile) {
249 glProfile=profile;
250 }
251
252 @Override
253 public final boolean isPBuffer() {
254 return isPBuffer;
255 }
256
257 /**
258 * Requesting offscreen pbuffer mode.
259 * <p>
260 * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}.
261 * </p>
262 * <p>
263 * Defaults to false.
264 * </p>
265 * <p>
266 * Requesting offscreen pbuffer mode disables the offscreen auto selection.
267 * </p>
268 */
269 public void setPBuffer(final boolean enable) {
270 if(enable) {
271 setOnscreen(false);
272 }
273 isPBuffer = enable;
274 }
275
276 @Override
277 public final boolean isFBO() {
278 return isFBO;
279 }
280
281 /**
282 * Requesting offscreen FBO mode.
283 * <p>
284 * If enabled this method also invokes {@link #setOnscreen(boolean) setOnscreen(false)}.
285 * </p>
286 * <p>
287 * Defaults to false.
288 * </p>
289 * <p>
290 * Requesting offscreen FBO mode disables the offscreen auto selection.
291 * </p>
292 */
293 public void setFBO(final boolean enable) {
294 if(enable) {
295 setOnscreen(false);
296 }
297 isFBO = enable;
298 }
299
300 @Override
301 public final boolean getDoubleBuffered() {
302 return doubleBuffered;
303 }
304
305 /** Enables or disables double buffering. */
306 public void setDoubleBuffered(final boolean enable) {
307 doubleBuffered = enable;
308 }
309
310 @Override
311 public final boolean getStereo() {
312 return stereo;
313 }
314
315 /** Enables or disables stereo viewing. */
316 public void setStereo(final boolean enable) {
317 stereo = enable;
318 }
319
320 @Override
321 public final boolean getHardwareAccelerated() {
322 return hardwareAccelerated;
323 }
324
325 /** Enables or disables hardware acceleration. */
326 public void setHardwareAccelerated(final boolean enable) {
327 hardwareAccelerated = enable;
328 }
329
330 @Override
331 public final int getDepthBits() {
332 return depthBits;
333 }
334
335 /** Sets the number of bits requested for the depth buffer. */
336 public void setDepthBits(final int depthBits) {
337 this.depthBits = depthBits;
338 }
339
340 @Override
341 public final int getStencilBits() {
342 return stencilBits;
343 }
344
345 /** Sets the number of bits requested for the stencil buffer. */
346 public void setStencilBits(final int stencilBits) {
347 this.stencilBits = stencilBits;
348 }
349
350 @Override
351 public final int getAccumRedBits() {
352 return accumRedBits;
353 }
354
355 /** Sets the number of bits requested for the accumulation buffer's
356 red component. On some systems only the accumulation buffer
357 depth, which is the sum of the red, green, and blue bits, is
358 considered. */
359 public void setAccumRedBits(final int accumRedBits) {
360 this.accumRedBits = accumRedBits;
361 }
362
363 @Override
364 public final int getAccumGreenBits() {
365 return accumGreenBits;
366 }
367
368 /** Sets the number of bits requested for the accumulation buffer's
369 green component. On some systems only the accumulation buffer
370 depth, which is the sum of the red, green, and blue bits, is
371 considered. */
372 public void setAccumGreenBits(final int accumGreenBits) {
373 this.accumGreenBits = accumGreenBits;
374 }
375
376 @Override
377 public final int getAccumBlueBits() {
378 return accumBlueBits;
379 }
380
381 /** Sets the number of bits requested for the accumulation buffer's
382 blue component. On some systems only the accumulation buffer
383 depth, which is the sum of the red, green, and blue bits, is
384 considered. */
385 public void setAccumBlueBits(final int accumBlueBits) {
386 this.accumBlueBits = accumBlueBits;
387 }
388
389 @Override
390 public final int getAccumAlphaBits() {
391 return accumAlphaBits;
392 }
393
394 /** Sets number of bits requested for accumulation buffer's alpha
395 component. On some systems only the accumulation buffer depth,
396 which is the sum of the red, green, and blue bits, is
397 considered. */
398 public void setAccumAlphaBits(final int accumAlphaBits) {
399 this.accumAlphaBits = accumAlphaBits;
400 }
401
402 /**
403 * Sets the desired extension for full-scene antialiasing
404 * (FSAA), default is {@link #DEFAULT_SAMPLE_EXTENSION}.
405 */
406 public void setSampleExtension(final String se) {
407 sampleExtension = se;
408 }
409
410 @Override
411 public final String getSampleExtension() {
412 return sampleExtension;
413 }
414
415 /**
416 * Defaults to false.<br>
417 * Indicates whether sample buffers for full-scene antialiasing
418 * (FSAA) should be allocated for this drawable.<br>
419 * Mind that this requires the alpha component.<br>
420 * If enabled this method also invokes {@link #setAlphaBits(int) setAlphaBits(1)}
421 * if {@link #getAlphaBits()} == 0.<br>
422 */
423 public void setSampleBuffers(final boolean enable) {
424 sampleBuffers = enable;
425 if(sampleBuffers && getAlphaBits()==0) {
426 setAlphaBits(1);
427 }
428 }
429
430 @Override
431 public final boolean getSampleBuffers() {
432 return sampleBuffers;
433 }
434
435 /**
436 * If sample buffers are enabled, indicates the number of buffers
437 * to be allocated. Defaults to 2.
438 * @see #getNumSamples()
439 */
440 public void setNumSamples(final int numSamples) {
441 this.numSamples = numSamples;
442 }
443
444 @Override
445 public final int getNumSamples() {
446 return sampleBuffers ? numSamples : 0;
447 }
448
449 @Override
450 public StringBuilder toString(StringBuilder sink) {
451 if(null == sink) {
452 sink = new StringBuilder();
453 }
454
455 final int samples = sampleBuffers ? numSamples : 0 ;
456
457 super.toString(sink, false);
458
459 sink.append(", accum-rgba ").append(accumRedBits).append(ESEP).append(accumGreenBits).append(ESEP).append(accumBlueBits).append(ESEP).append(accumAlphaBits);
460 sink.append(", dp/st/ms ").append(depthBits).append(ESEP).append(stencilBits).append(ESEP).append(samples);
461 if(samples>0) {
462 sink.append(", sample-ext ").append(sampleExtension);
463 }
464 if(doubleBuffered) {
465 sink.append(", dbl");
466 } else {
467 sink.append(", one");
468 }
469 if(stereo) {
470 sink.append(", stereo");
471 } else {
472 sink.append(", mono ");
473 }
474 if(hardwareAccelerated) {
475 sink.append(", hw, ");
476 } else {
477 sink.append(", sw, ");
478 }
479 sink.append(glProfile);
480 if(isOnscreen()) {
481 sink.append(", on-scr[");
482 } else {
483 sink.append(", offscr[");
484 }
485 boolean ns=false;
486 if(isFBO()) {
487 sink.append("fbo");
488 ns = true;
489 }
490 if(isPBuffer()) {
491 if(ns) { sink.append(CSEP); }
492 sink.append("pbuffer");
493 ns = true;
494 }
495 if(isBitmap()) {
496 if(ns) { sink.append(CSEP); }
497 sink.append("bitmap");
498 ns = true;
499 }
500 if(!ns) { // !FBO !PBuffer !Bitmap
501 if(isOnscreen()) {
502 sink.append("."); // no additional off-screen modes besides on-screen
503 } else {
504 sink.append("auto-cfg"); // auto-config off-screen mode
505 }
506 }
507 sink.append("]");
508
509 return sink;
510 }
511
512 /** Returns a textual representation of this GLCapabilities
513 object. */
514 @Override
515 public String toString() {
516 final StringBuilder msg = new StringBuilder();
517 msg.append("GLCaps[");
518 toString(msg);
519 msg.append("]");
520 return msg.toString();
521 }
522}
Specifies a set of capabilities that a window's rendering context must support, such as color depth p...
static final String CSEP
Component separator.
final int getAlphaBits()
Returns the number of bits for the color buffer's alpha component.
final boolean isOnscreen()
Returns whether an on- or offscreen surface is requested, available or chosen.
boolean isBitmap()
Returns whether bitmap offscreen mode is requested, available or chosen.
static final String ESEP
Element separator.
void setAlphaBits(final int alphaBits)
Sets the number of bits requested for the color buffer's alpha component.
void setOnscreen(final boolean onscreen)
Sets whether the surface shall be on- or offscreen.
Specifies a set of OpenGL capabilities.
GLCapabilities copyFrom(final GLCapabilitiesImmutable source)
Copies all GLCapabilitiesImmutable values from source into this instance.
final boolean isPBuffer()
Returns whether pbuffer offscreen mode is requested, available or chosen.
void setPBuffer(final boolean enable)
Requesting offscreen pbuffer mode.
final boolean getDoubleBuffered()
Returns whether double-buffering is requested, available or chosen.
boolean equals(final Object obj)
Equality over the immutable attributes of both objects.
final boolean isFBO()
Returns whether FBO offscreen mode is requested, available or chosen.
void setAccumRedBits(final int accumRedBits)
Sets the number of bits requested for the accumulation buffer's red component.
final boolean getSampleBuffers()
Returns whether sample buffers for full-scene antialiasing (FSAA) should be allocated for this drawab...
GLCapabilities(final GLProfile glp)
Creates a GLCapabilities object.
void setStencilBits(final int stencilBits)
Sets the number of bits requested for the stencil buffer.
void setDoubleBuffered(final boolean enable)
Enables or disables double buffering.
final boolean getHardwareAccelerated()
Returns whether hardware acceleration is requested, available or chosen.
void setHardwareAccelerated(final boolean enable)
Enables or disables hardware acceleration.
void setAccumGreenBits(final int accumGreenBits)
Sets the number of bits requested for the accumulation buffer's green component.
void setFBO(final boolean enable)
Requesting offscreen FBO mode.
int hashCode()
Hash code over the immutable attributes.
void setNumSamples(final int numSamples)
If sample buffers are enabled, indicates the number of buffers to be allocated.
final int getNumSamples()
Returns the number of sample buffers to be allocated if sample buffers are enabled,...
void setGLProfile(final GLProfile profile)
Sets the GL profile you desire.
final boolean getStereo()
Returns whether stereo is requested, available or chosen.
final int getAccumGreenBits()
Returns the number of bits for the accumulation buffer's green component.
final int getAccumRedBits()
Returns the number of bits for the accumulation buffer's red component.
StringBuilder toString(StringBuilder sink)
Return a textual representation of this object.
String toString()
Returns a textual representation of this GLCapabilities object.
void setAccumBlueBits(final int accumBlueBits)
Sets the number of bits requested for the accumulation buffer's blue component.
void setStereo(final boolean enable)
Enables or disables stereo viewing.
void setSampleExtension(final String se)
Sets the desired extension for full-scene antialiasing (FSAA), default is DEFAULT_SAMPLE_EXTENSION.
final int getAccumBlueBits()
Returns the number of bits for the accumulation buffer's blue component.
int compareTo(final CapabilitiesImmutable o)
comparing hw/sw, stereo, multisample, stencil, RGBA and depth only
final int getDepthBits()
Returns the number of depth buffer bits.
void setAccumAlphaBits(final int accumAlphaBits)
Sets number of bits requested for accumulation buffer's alpha component.
final String getSampleExtension()
Returns the extension for full-scene antialiasing (FSAA).
GLCapabilities copyFrom(final CapabilitiesImmutable source)
Copies all CapabilitiesImmutable values from source into this instance.
final GLProfile getGLProfile()
Returns the GL profile you desire or used by the drawable.
void setSampleBuffers(final boolean enable)
Defaults to false.
void setDepthBits(final int depthBits)
Sets the number of bits requested for the depth buffer.
final int getAccumAlphaBits()
Returns the number of bits for the accumulation buffer's alpha component.
final int getStencilBits()
Returns the number of stencil buffer bits.
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Specifies the the OpenGL profile.
Definition: GLProfile.java:77
static GLProfile getDefault(final AbstractGraphicsDevice device)
Returns a default GLProfile object, reflecting the best for the running platform.
Definition: GLProfile.java:739
static AbstractGraphicsDevice getDefaultDevice()
Specifies an immutable set of capabilities that a window's rendering context must support,...
Specifies an immutable set of OpenGL capabilities.
boolean getSampleBuffers()
Returns whether sample buffers for full-scene antialiasing (FSAA) should be allocated for this drawab...
int getAccumGreenBits()
Returns the number of bits for the accumulation buffer's green component.
String getSampleExtension()
Returns the extension for full-scene antialiasing (FSAA).
int getNumSamples()
Returns the number of sample buffers to be allocated if sample buffers are enabled,...
boolean getHardwareAccelerated()
Returns whether hardware acceleration is requested, available or chosen.
int getDepthBits()
Returns the number of depth buffer bits.
boolean isPBuffer()
Returns whether pbuffer offscreen mode is requested, available or chosen.
GLProfile getGLProfile()
Returns the GL profile you desire or used by the drawable.
int getAccumRedBits()
Returns the number of bits for the accumulation buffer's red component.
int getAccumAlphaBits()
Returns the number of bits for the accumulation buffer's alpha component.
boolean equals(Object obj)
Equality over the immutable attributes of both objects.
boolean getDoubleBuffered()
Returns whether double-buffering is requested, available or chosen.
int getAccumBlueBits()
Returns the number of bits for the accumulation buffer's blue component.
boolean isFBO()
Returns whether FBO offscreen mode is requested, available or chosen.
int getStencilBits()
Returns the number of stencil buffer bits.
static final String DEFAULT_SAMPLE_EXTENSION
One of the platform's default sample extension EGL.EGL_SAMPLES, GLX.GLX_SAMPLES, WGLExt....
boolean getStereo()
Returns whether stereo is requested, available or chosen.