JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
Capabilities.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 * 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.nativewindow;
42
43/** Specifies a set of capabilities that a window's rendering context
44 must support, such as color depth per channel. It currently
45 contains the minimal number of routines which allow configuration
46 on all supported window systems. */
47public class Capabilities implements CapabilitiesImmutable, Cloneable {
48 protected final static String na_str = "----" ;
49
50 private int redBits = 8;
51 private int greenBits = 8;
52 private int blueBits = 8;
53 private int alphaBits = 0;
54
55 // Support for transparent windows containing OpenGL content
56 private boolean backgroundOpaque = true;
57 private int transparentValueRed = 0;
58 private int transparentValueGreen = 0;
59 private int transparentValueBlue = 0;
60 private int transparentValueAlpha = 0;
61
62 // Switch for on- or offscreen
63 private boolean onscreen = true;
64
65 // offscreen bitmap mode
66 private boolean isBitmap = false;
67
68 /** Creates a Capabilities object. All attributes are in a default
69 state.
70 */
71 public Capabilities() {}
72
73 @Override
74 public Object cloneMutable() {
75 return clone();
76 }
77
78 @Override
79 public Object clone() {
80 try {
81 return super.clone();
82 } catch (final CloneNotSupportedException e) {
83 throw new NativeWindowException(e);
84 }
85 }
86
87 /**
88 * Copies all {@link Capabilities} values
89 * from <code>source</code> into this instance.
90 * @return this instance
91 */
93 redBits = other.getRedBits();
94 greenBits = other.getGreenBits();
95 blueBits = other.getBlueBits();
96 alphaBits = other.getAlphaBits();
97 backgroundOpaque = other.isBackgroundOpaque();
98 onscreen = other.isOnscreen();
99 isBitmap = other.isBitmap();
100 transparentValueRed = other.getTransparentRedValue();
101 transparentValueGreen = other.getTransparentGreenValue();
102 transparentValueBlue = other.getTransparentBlueValue();
103 transparentValueAlpha = other.getTransparentAlphaValue();
104 return this;
105 }
106
107 @Override
108 public int hashCode() {
109 // 31 * x == (x << 5) - x
110 int hash = 31 + this.redBits;
111 hash = ((hash << 5) - hash) + ( this.onscreen ? 1 : 0 );
112 hash = ((hash << 5) - hash) + ( this.isBitmap ? 1 : 0 );
113 hash = ((hash << 5) - hash) + this.greenBits;
114 hash = ((hash << 5) - hash) + this.blueBits;
115 hash = ((hash << 5) - hash) + this.alphaBits;
116 hash = ((hash << 5) - hash) + ( this.backgroundOpaque ? 1 : 0 );
117 hash = ((hash << 5) - hash) + this.transparentValueRed;
118 hash = ((hash << 5) - hash) + this.transparentValueGreen;
119 hash = ((hash << 5) - hash) + this.transparentValueBlue;
120 hash = ((hash << 5) - hash) + this.transparentValueAlpha;
121 return hash;
122 }
123
124 private static boolean checkSameSuppSameValue(final VIDType type, final VisualIDHolder a, final VisualIDHolder b) {
125 final boolean has_a = a.isVisualIDSupported(type);
126 if( has_a != b.isVisualIDSupported(type) ) {
127 // both should either support or not support the extra X11_FBCONFIG
128 return false;
129 }
130 return !has_a || a.getVisualID(type) == b.getVisualID(type);
131 }
132 private static boolean checkSameValueIfBothSupp(final VIDType type, final VisualIDHolder a, final VisualIDHolder b) {
133 final boolean has_a = a.isVisualIDSupported(type);
134 if( has_a && has_a == b.isVisualIDSupported(type) ) {
135 return a.getVisualID(type) == b.getVisualID(type);
136 }
137 return true;
138 }
139
140 @Override
141 public boolean equals(final Object obj) {
142 if(this == obj) { return true; }
143 if(!(obj instanceof CapabilitiesImmutable)) {
144 return false;
145 }
147 {
148 // first check whether the VID is compatible
149 final int id_t = this.getVisualID(VIDType.NATIVE);
150 final int id_o = other.getVisualID(VIDType.NATIVE);
151 if( id_t != id_o ) {
152 return false;
153 }
154 if( !checkSameSuppSameValue(VIDType.X11_FBCONFIG, this, other) ) {
155 return false;
156 }
157 if( !checkSameValueIfBothSupp(VIDType.EGL_CONFIG, this, other) ) {
158 return false;
159 }
160 }
161 boolean res = other.getRedBits()==redBits &&
162 other.getGreenBits()==greenBits &&
163 other.getBlueBits()==blueBits &&
164 other.getAlphaBits()==alphaBits &&
165 other.isBackgroundOpaque()==backgroundOpaque &&
166 other.isOnscreen()==onscreen &&
167 other.isBitmap()==isBitmap;
168 if(res && !backgroundOpaque) {
169 res = other.getTransparentRedValue()==transparentValueRed &&
170 other.getTransparentGreenValue()==transparentValueGreen &&
171 other.getTransparentBlueValue()==transparentValueBlue &&
172 other.getTransparentAlphaValue()==transparentValueAlpha;
173 }
174
175 return res;
176 }
177
178 /**
179 * Comparing RGBA values only
180 **/
181 @Override
182 public int compareTo(final CapabilitiesImmutable caps) {
183 /**
184 if ( ! ( o instanceof CapabilitiesImmutable ) ) {
185 Class<?> c = (null != o) ? o.getClass() : null ;
186 throw new ClassCastException("Not a CapabilitiesImmutable object, but " + c);
187 }
188 final CapabilitiesImmutable caps = (CapabilitiesImmutable) o; */
189
190 final int rgba = redBits * greenBits * blueBits * ( alphaBits + 1 );
191
192 final int xrgba = caps.getRedBits() * caps.getGreenBits() * caps.getBlueBits() * ( caps.getAlphaBits() + 1 );
193
194 if(rgba > xrgba) {
195 return 1;
196 } else if(rgba < xrgba) {
197 return -1;
198 }
199
200 return 0; // they are equal: RGBA
201 }
202
203 @Override
204 public int getVisualID(final VIDType type) throws NativeWindowException {
205 switch(type) {
206 case INTRINSIC:
207 case NATIVE:
209 default:
210 throw new NativeWindowException("Invalid type <"+type+">");
211 }
212 }
213
214 @Override
215 public boolean isVisualIDSupported(final VIDType type) {
216 switch(type) {
217 case INTRINSIC:
218 case NATIVE:
219 return true;
220 default:
221 return false;
222 }
223 }
224
225 @Override
226 public final int getRedBits() {
227 return redBits;
228 }
229
230 /** Sets the number of bits requested for the color buffer's red
231 component. On some systems only the color depth, which is the
232 sum of the red, green, and blue bits, is considered. */
233 public void setRedBits(final int redBits) {
234 this.redBits = redBits;
235 }
236
237 @Override
238 public final int getGreenBits() {
239 return greenBits;
240 }
241
242 /** Sets the number of bits requested for the color buffer's green
243 component. On some systems only the color depth, which is the
244 sum of the red, green, and blue bits, is considered. */
245 public void setGreenBits(final int greenBits) {
246 this.greenBits = greenBits;
247 }
248
249 @Override
250 public final int getBlueBits() {
251 return blueBits;
252 }
253
254 /** Sets the number of bits requested for the color buffer's blue
255 component. On some systems only the color depth, which is the
256 sum of the red, green, and blue bits, is considered. */
257 public void setBlueBits(final int blueBits) {
258 this.blueBits = blueBits;
259 }
260
261 @Override
262 public final int getAlphaBits() {
263 return alphaBits;
264 }
265
266 /**
267 * Sets the number of bits requested for the color buffer's alpha
268 * component. On some systems only the color depth, which is the
269 * sum of the red, green, and blue bits, is considered.
270 * <p>
271 * <b>Note:</b> If alpha bits are <code>zero</code>, they are set to <code>one</code>
272 * by {@link #setBackgroundOpaque(boolean)} and it's OpenGL specialization <code>GLCapabilities::setSampleBuffers(boolean)</code>.<br/>
273 * Ensure to call this method after the above to ensure a <code>zero</code> value.</br>
274 * The above automated settings takes into account, that the user calls this method to <i>request</i> alpha bits,
275 * not to <i>reflect</i> a current state. Nevertheless if this is the case - call it at last.
276 * </p>
277 */
278 public void setAlphaBits(final int alphaBits) {
279 this.alphaBits = alphaBits;
280 }
281
282 /**
283 * Sets whether the surface shall be opaque or translucent.
284 * <p>
285 * Platform implementations may need an alpha component in the surface (eg. Windows),
286 * or expect pre-multiplied alpha values (eg. X11/XRender).<br>
287 * To unify the experience, this method also invokes {@link #setAlphaBits(int) setAlphaBits(1)}
288 * if {@link #getAlphaBits()} == 0.<br>
289 * Please note that in case alpha is required on the platform the
290 * clear color shall have an alpha lower than 1.0 to allow anything shining through.
291 * </p>
292 * <p>
293 * Mind that translucency may cause a performance penalty
294 * due to the composite work required by the window manager.
295 * </p>
296 */
297 public void setBackgroundOpaque(final boolean opaque) {
298 backgroundOpaque = opaque;
299 if(!opaque && getAlphaBits()==0) {
300 setAlphaBits(1);
301 }
302 }
303
304 @Override
305 public final boolean isBackgroundOpaque() {
306 return backgroundOpaque;
307 }
308
309 /**
310 * Sets whether the surface shall be on- or offscreen.
311 * <p>
312 * Defaults to true.
313 * </p>
314 * <p>
315 * If requesting an offscreen surface without further selection of it's mode,
316 * e.g. FBO, Pbuffer or {@link #setBitmap(boolean) bitmap},
317 * the implementation will choose the best available offscreen mode.
318 * </p>
319 * @param onscreen
320 */
321 public void setOnscreen(final boolean onscreen) {
322 this.onscreen=onscreen;
323 }
324
325 @Override
326 public final boolean isOnscreen() {
327 return onscreen;
328 }
329
330 /**
331 * Requesting offscreen bitmap mode.
332 * <p>
333 * If enabled this method also invokes {@link #setOnscreen(int) setOnscreen(false)}.
334 * </p>
335 * <p>
336 * Defaults to false.
337 * </p>
338 * <p>
339 * Requesting offscreen bitmap mode disables the offscreen auto selection.
340 * </p>
341 */
342 public void setBitmap(final boolean enable) {
343 if(enable) {
344 setOnscreen(false);
345 }
346 isBitmap = enable;
347 }
348
349 @Override
350 public boolean isBitmap() {
351 return isBitmap;
352 }
353
354 @Override
355 public final int getTransparentRedValue() { return transparentValueRed; }
356
357 @Override
358 public final int getTransparentGreenValue() { return transparentValueGreen; }
359
360 @Override
361 public final int getTransparentBlueValue() { return transparentValueBlue; }
362
363 @Override
364 public final int getTransparentAlphaValue() { return transparentValueAlpha; }
365
366 /** Sets the transparent red value for the frame buffer configuration,
367 ranging from 0 to the maximum frame buffer value for red.
368 This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
369 It defaults to half of the frambuffer value for red. <br>
370 A value of -1 is interpreted as any value. */
371 public void setTransparentRedValue(final int transValueRed) { transparentValueRed=transValueRed; }
372
373 /** Sets the transparent green value for the frame buffer configuration,
374 ranging from 0 to the maximum frame buffer value for green.
375 This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
376 It defaults to half of the frambuffer value for green.<br>
377 A value of -1 is interpreted as any value. */
378 public void setTransparentGreenValue(final int transValueGreen) { transparentValueGreen=transValueGreen; }
379
380 /** Sets the transparent blue value for the frame buffer configuration,
381 ranging from 0 to the maximum frame buffer value for blue.
382 This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
383 It defaults to half of the frambuffer value for blue.<br>
384 A value of -1 is interpreted as any value. */
385 public void setTransparentBlueValue(final int transValueBlue) { transparentValueBlue=transValueBlue; }
386
387 /** Sets the transparent alpha value for the frame buffer configuration,
388 ranging from 0 to the maximum frame buffer value for alpha.
389 This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
390 It defaults to half of the frambuffer value for alpha.<br>
391 A value of -1 is interpreted as any value. */
392 public void setTransparentAlphaValue(final int transValueAlpha) { transparentValueAlpha=transValueAlpha; }
393
394 @Override
395 public StringBuilder toString(final StringBuilder sink) {
396 return toString(sink, true);
397 }
398
399 /** Returns a textual representation of this Capabilities
400 object. */
401 @Override
402 public String toString() {
403 final StringBuilder msg = new StringBuilder();
404 msg.append("Caps[");
405 toString(msg);
406 msg.append("]");
407 return msg.toString();
408 }
409
410 /** Return a textual representation of this object's on/off screen state. Use the given StringBuilder [optional]. */
411 protected StringBuilder onoffScreenToString(StringBuilder sink) {
412 if(null == sink) {
413 sink = new StringBuilder();
414 }
415 if(onscreen) {
416 sink.append("on-scr");
417 } else {
418 sink.append("offscr[");
419 }
420 if(isBitmap) {
421 sink.append("bitmap");
422 } else if(onscreen) {
423 sink.append("."); // no additional off-screen modes besides on-screen
424 } else {
425 sink.append("auto-cfg"); // auto-config off-screen mode
426 }
427 sink.append("]");
428
429 return sink;
430 }
431
432 /** Element separator */
433 protected static final String ESEP = "/";
434 /** Component separator */
435 protected static final String CSEP = ", ";
436
437 protected StringBuilder toString(StringBuilder sink, final boolean withOnOffScreen) {
438 if(null == sink) {
439 sink = new StringBuilder();
440 }
441 sink.append("rgba ").append(redBits).append(ESEP).append(greenBits).append(ESEP).append(blueBits).append(ESEP).append(alphaBits);
442 if(backgroundOpaque) {
443 sink.append(", opaque");
444 } else {
445 sink.append(", trans-rgba 0x").append(toHexString(transparentValueRed)).append(ESEP).append(toHexString(transparentValueGreen)).append(ESEP).append(toHexString(transparentValueBlue)).append(ESEP).append(toHexString(transparentValueAlpha));
446 }
447 if(withOnOffScreen) {
448 sink.append(CSEP);
450 }
451 return sink;
452 }
453
454 protected final String toHexString(final int val) { return Integer.toHexString(val); }
455}
Specifies a set of capabilities that a window's rendering context must support, such as color depth p...
final int getTransparentAlphaValue()
Gets the transparent alpha value for the frame buffer configuration.
int compareTo(final CapabilitiesImmutable caps)
Comparing RGBA values only.
final String toHexString(final int val)
static final String CSEP
Component separator.
final int getAlphaBits()
Returns the number of bits for the color buffer's alpha component.
final int getGreenBits()
Returns the number of bits for the color buffer's green component.
void setTransparentBlueValue(final int transValueBlue)
Sets the transparent blue value for the frame buffer configuration, ranging from 0 to the maximum fra...
StringBuilder onoffScreenToString(StringBuilder sink)
Return a textual representation of this object's on/off screen state.
boolean equals(final Object obj)
Equality over the immutable attributes of both objects.
void setRedBits(final int redBits)
Sets the number of bits requested for the color buffer's red component.
final boolean isBackgroundOpaque()
Returns whether an opaque or translucent surface is requested, supported or chosen.
final int getTransparentGreenValue()
Gets the transparent green value for the frame buffer configuration.
int getVisualID(final VIDType type)
Returns the native visual ID of the given type if supported, or VID_UNDEFINED if not supported.
final boolean isOnscreen()
Returns whether an on- or offscreen surface is requested, available or chosen.
void setBitmap(final boolean enable)
Requesting offscreen bitmap mode.
void setGreenBits(final int greenBits)
Sets the number of bits requested for the color buffer's green component.
boolean isBitmap()
Returns whether bitmap offscreen mode is requested, available or chosen.
static final String ESEP
Element separator.
final int getBlueBits()
Returns the number of bits for the color buffer's blue component.
int hashCode()
Hash code over the immutable attributes.
void setTransparentGreenValue(final int transValueGreen)
Sets the transparent green value for the frame buffer configuration, ranging from 0 to the maximum fr...
void setBackgroundOpaque(final boolean opaque)
Sets whether the surface shall be opaque or translucent.
void setBlueBits(final int blueBits)
Sets the number of bits requested for the color buffer's blue component.
final int getRedBits()
Returns the number of bits for the color buffer's red component.
final int getTransparentRedValue()
Gets the transparent red value for the frame buffer configuration.
String toString()
Returns a textual representation of this Capabilities object.
void setTransparentAlphaValue(final int transValueAlpha)
Sets the transparent alpha value for the frame buffer configuration, ranging from 0 to the maximum fr...
void setAlphaBits(final int alphaBits)
Sets the number of bits requested for the color buffer's alpha component.
StringBuilder toString(StringBuilder sink, final boolean withOnOffScreen)
void setOnscreen(final boolean onscreen)
Sets whether the surface shall be on- or offscreen.
Capabilities()
Creates a Capabilities object.
boolean isVisualIDSupported(final VIDType type)
Returns true if the given VIDType is supported, otherwise false.
Capabilities copyFrom(final CapabilitiesImmutable other)
Copies all Capabilities values from source into this instance.
final int getTransparentBlueValue()
Gets the transparent blue value for the frame buffer configuration.
void setTransparentRedValue(final int transValueRed)
Sets the transparent red value for the frame buffer configuration, ranging from 0 to the maximum fram...
StringBuilder toString(final StringBuilder sink)
Return a textual representation of this object.
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Specifies an immutable set of capabilities that a window's rendering context must support,...
int getAlphaBits()
Returns the number of bits for the color buffer's alpha component.
int getBlueBits()
Returns the number of bits for the color buffer's blue component.
int getTransparentAlphaValue()
Gets the transparent alpha value for the frame buffer configuration.
boolean isBitmap()
Returns whether bitmap offscreen mode is requested, available or chosen.
int getRedBits()
Returns the number of bits for the color buffer's red component.
int getGreenBits()
Returns the number of bits for the color buffer's green component.
boolean isOnscreen()
Returns whether an on- or offscreen surface is requested, available or chosen.
int getTransparentGreenValue()
Gets the transparent green value for the frame buffer configuration.
int getTransparentRedValue()
Gets the transparent red value for the frame buffer configuration.
boolean isBackgroundOpaque()
Returns whether an opaque or translucent surface is requested, supported or chosen.
int getTransparentBlueValue()
Gets the transparent blue value for the frame buffer configuration.
static final int VID_UNDEFINED
getVisualID(VIDType) result indicating an undefined value, which could be cause by an unsupported que...
int getVisualID(VIDType type)
Returns the native visual ID of the given type if supported, or VID_UNDEFINED if not supported.
boolean isVisualIDSupported(VIDType type)
Returns true if the given VIDType is supported, otherwise false.