JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
VisualIDHolder.java
Go to the documentation of this file.
1/**
2 * Copyright 2012-2023 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.nativewindow;
30
31import java.util.Comparator;
32
33/**
34 * Visual ID holder interface.
35 * <p>
36 * Allows queries of different types of native visual IDs,
37 * see {@link #getVisualID(int)}.
38 * </p>
39 */
40public interface VisualIDHolder {
41
42 public enum VIDType {
43 /** Generic Values */
44 INTRINSIC(0), NATIVE(1),
45 /** EGL Values */
47 /** X11 Values */
48 X11_XVISUAL(20), X11_FBCONFIG(21),
49 /** Windows Values */
51
52 public final int id;
53
54 VIDType(final int id){
55 this.id = id;
56 }
57 }
58
59 /**
60 * Returns the native visual ID of the given <code>type</code>
61 * if supported, or {@link #VID_UNDEFINED} if not supported.
62 * <p>
63 * Depending on the native windowing system, <code>type</code> is handled as follows:
64 * <ul>
65 * <li>X11 throws NativeWindowException on <code>EGL_CONFIG</code>, <code>WIN32_PFD</code>
66 * <ul>
67 * <li><code>INTRINSIC</code>: <i>X11 XVisual ID</i></li>
68 * <li><code>NATIVE</code>: <i>X11 XVisual ID</i></li>
69 * <li><code>X11_XVISUAL</code>: <i>X11 XVisual ID</i></li>
70 * <li><code>X11_FBCONFIG</code>: <code>VID_UNDEFINED</code></li>
71 * </ul></li>
72 * <li>X11/GL throws NativeWindowException on <code>EGL_CONFIG</code>, <code>WIN32_PFD</code>
73 * <ul>
74 * <li><code>INTRINSIC</code>: <i>X11 XVisual ID</i></li>
75 * <li><code>NATIVE</code>: <i>X11 XVisual ID</i></li>
76 * <li><code>X11_XVISUAL</code>: <i>X11 XVisual ID</i></li>
77 * <li><code>X11_FBCONFIG</code>: <i>X11 FBConfig ID</i> or <code>VID_UNDEFINED</code></li>
78 * </ul></li>
79 * <li>Windows/GL throws NativeWindowException on <code>EGL_CONFIG</code>, <code>X11_XVISUAL</code>, <code>X11_FBCONFIG</code>
80 * <ul>
81 * <li><code>INTRINSIC</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
82 * <li><code>NATIVE</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
83 * <li><code>WIN32_PFD</code>: <i>Win32 PIXELFORMATDESCRIPTOR ID</i></li>
84 * </ul></li>
85 * <li>EGL/GL throws NativeWindowException on <code>X11_XVISUAL</code>, <code>X11_FBCONFIG</code>, <code>WIN32_PFD</code>
86 * <ul>
87 * <li><code>INTRINSIC</code>: <i>EGL Config ID</i></li>
88 * <li><code>NATIVE</code>: <i>EGL NativeVisual ID</i> (<i>X11 XVisual ID</i>, <i>Win32 PIXELFORMATDESCRIPTOR ID</i>, ...)</li>
89 * <li><code>EGL_CONFIG</code>: <i>EGL Config ID</i></li>
90 * </ul></li>
91 * </ul>
92 * </p>
93 * <p>
94 * One may use {@link #isVisualIDSupported(VIDType)} to test upfront whether a {@link VIDType} is supported,
95 * e.g. to avoid an exception or query or compare all available.
96 * </p>
97 * Note: <code>INTRINSIC</code> and <code>NATIVE</code> are always handled,
98 * but may result in {@link #VID_UNDEFINED}. The latter is true if
99 * the native value are actually undefined or the corresponding object is not
100 * mapped to a native visual object.
101 *
102 * @throws NativeWindowException if <code>type</code> is neither
103 * <code>INTRINSIC</code> nor <code>NATIVE</code>
104 * and does not match the native implementation.
105 *
106 * @see #isVisualIDSupported(VIDType)
107 */
109
110 /**
111 * Returns true if the given {@link VIDType} is supported, otherwise false.
112 * <p>
113 * Note: <code>INTRINSIC</code> and <code>NATIVE</code> are always handled,
114 * but may result in {@link #VID_UNDEFINED}. The latter is true if
115 * the native value are actually undefined or the corresponding object is not
116 * mapped to a native visual object.
117 * </p>
118 * @see #getVisualID(VIDType)
119 */
121
122 /**
123 * {@link #getVisualID(VIDType)} result indicating an undefined value,
124 * which could be cause by an unsupported query.
125 * <p>
126 * We assume the const value <code>0</code> doesn't reflect a valid native visual ID
127 * and is interpreted as <i>no value</i> on all platforms.
128 * This is currently true for Android, X11 and Windows.
129 * </p>
130 */
131 static final int VID_UNDEFINED = 0;
132
133 /** Comparing {@link VIDType#NATIVE} */
134 public static class VIDComparator implements Comparator<VisualIDHolder> {
135 private final VIDType type;
136
137 public VIDComparator(final VIDType type) {
138 this.type = type;
139 }
140
141 @Override
142 public int compare(final VisualIDHolder vid1, final VisualIDHolder vid2) {
143 final int id1 = vid1.getVisualID(type);
144 final int id2 = vid2.getVisualID(type);
145
146 if(id1 > id2) {
147 return 1;
148 } else if(id1 < id2) {
149 return -1;
150 }
151 return 0;
152 }
153 }
154}
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
int compare(final VisualIDHolder vid1, final VisualIDHolder vid2)
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.