JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
StereoDevice.java
Go to the documentation of this file.
1/**
2 * Copyright 2014-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 */
28package com.jogamp.opengl.util.stereo;
29
30import com.jogamp.math.FovHVHalves;
31import com.jogamp.math.Vec3f;
32import com.jogamp.nativewindow.util.DimensionImmutable;
33import com.jogamp.nativewindow.util.PointImmutable;
34
35import jogamp.opengl.Debug;
36
37/**
38 * Interface describing a native stereoscopic device
39 */
40public interface StereoDevice {
41 public static final boolean DEBUG = Debug.debug("StereoDevice");
42 public static final boolean DUMP_DATA = Debug.isPropertyDefined("jogl.debug.StereoDevice.DumpData", true);
43
44 /**
45 * Sensor Bit: Orientation tracking
46 */
47 public static final int SENSOR_ORIENTATION = 1 << 0;
48
49 /**
50 * Sensor Bit: Yaw correction
51 */
52 public static final int SENSOR_YAW_CORRECTION = 1 << 1;
53
54 /**
55 * Sensor Bit: Positional tracking
56 */
57 public static final int SENSOR_POSITION = 1 << 2;
58
59 /** Return the factory used to create this device. */
61
62 /**
63 * Disposes this {@link StereoDevice}, if {@link #isValid() valid}.
64 * <p>
65 * Implementation shall {@link #stopSensors() stop sensors} and free all resources.
66 * </p>
67 */
68 public void dispose();
69
70 /**
71 * Returns {@code true}, if instance is created and not {@link #dispose() disposed},
72 * otherwise returns {@code false}.
73 */
74 public boolean isValid();
75
76 /**
77 * If operation within a device spanning virtual desktop,
78 * returns the device position.
79 * <p>
80 * Otherwise simply 0/0.
81 * </p>
82 */
84
85 /**
86 * Returns the required surface size in pixel
87 * in target space.
88 */
90
91 /**
92 * Returns the CCW rotation as required by this display device.
93 */
94 public int getRequiredRotation();
95
96 /**
97 * Return the device default eye position offset for {@link #createRenderer(int, int, Vec3f, FovHVHalves[], float)}.
98 * <p>
99 * Result is an array of float values for
100 * <ul>
101 * <li><i>right</i> (positive)</li>
102 * <li><i>up</i> (positive)</li>
103 * <li><i>forward</i> (negative)</li>
104 * </ul>
105 * </p>
106 * @return
107 */
109
110 /**
111 * Returns the device default {@link FovHVHalves} for all supported eyes
112 * in natural order, i.e. left and right if supported.
113 * <p>
114 * Monoscopic devices return an array length of one, without the value for the right-eye!
115 * </p>
116 */
118
119 /**
120 * Returns the {@link LocationSensorParameter} of the device
121 * if {@link #SENSOR_POSITION} is {@link #getSupportedSensorBits() supported},
122 * otherwise returns {@code null}.
123 */
125
126
127 /**
128 * Sets the location sensor's origin of this device to the current position.
129 * <p>
130 * In case {@link #SENSOR_POSITION} is not {@link #getSupportedSensorBits() supported},
131 * this method is a no-op.
132 * </p>
133 */
135
136 /**
137 * Start desired and required sensors. Returns true if action was successful, otherwise false.
138 * <p>
139 * Method fails if required sensors are not {@link #getSupportedSensorBits() supported}.
140 * </p>
141 * @param desiredSensorBits the desired optional sensors
142 * @param requiredSensorBits the required sensors
143 * @see #stopSensors()
144 * @see #getSensorsStarted()
145 * @see #getSupportedSensorBits()
146 * @see #getEnabledSensorBits()
147 */
148 public boolean startSensors(int desiredSensorBits, int requiredSensorBits);
149
150 /**
151 * Stop sensors. Returns true if action was successful, otherwise false.
152 * @see #startSensors(int, int)
153 * @see #getSensorsStarted()
154 * @see #getSupportedSensorBits()
155 * @see #getEnabledSensorBits()
156 */
157 public boolean stopSensors();
158
159 /**
160 * Return true if sensors have been started, false otherwise.
161 * @see #startSensors(int, int)
162 * @see #stopSensors()
163 * @see #getSupportedSensorBits()
164 * @see #getEnabledSensorBits()
165 */
166 public boolean getSensorsStarted();
167
168 /**
169 * Returns the supported sensor capability bits, e.g. {@link #SENSOR_ORIENTATION}, {@link #SENSOR_POSITION}
170 * of the {@link StereoDevice}.
171 * @see #startSensors(int, int)
172 * @see #stopSensors()
173 * @see #getSensorsStarted()
174 * @see #getEnabledSensorBits()
175 */
177
178 /**
179 * Returns the actual used sensor capability bits, e.g. {@link #SENSOR_ORIENTATION}, {@link #SENSOR_POSITION}
180 * in case the {@link #getSupportedSensorBits() device supports} them and if they are enabled.
181 * @see #startSensors(int, int)
182 * @see #stopSensors()
183 * @see #getSensorsStarted()
184 * @see #getSupportedSensorBits()
185 */
187
188 /**
189 * Returns an array of the preferred eye rendering order.
190 * The array length reflects the supported eye count.
191 * <p>
192 * Monoscopic devices only support one eye, where stereoscopic device two eyes.
193 * </p>
194 */
195 public int[] getEyeRenderOrder();
196
197 /**
198 * Returns the supported distortion compensation of the {@link StereoDeviceRenderer},
199 * e.g. {@link StereoDeviceRenderer#DISTORTION_BARREL}, {@link StereoDeviceRenderer#DISTORTION_CHROMATIC}, etc.
200 * @see StereoDeviceRenderer#getDistortionBits()
201 * @see #createRenderer(int, int, Vec3f, FovHVHalves[], float, int)
202 * @see #getRecommendedDistortionBits()
203 * @see #getMinimumDistortionBits()
204 */
206
207 /**
208 * Returns the recommended distortion compensation bits for the {@link StereoDeviceRenderer},
209 * e.g. {@link StereoDeviceRenderer#DISTORTION_BARREL}, {@link StereoDeviceRenderer#DISTORTION_CHROMATIC}
210 * {@link StereoDeviceRenderer#DISTORTION_VIGNETTE}.
211 * <p>
212 * User shall use the recommended distortion compensation to achieve a distortion free view.
213 * </p>
214 * @see StereoDeviceRenderer#getDistortionBits()
215 * @see #createRenderer(int, int, Vec3f, FovHVHalves[], float, int)
216 * @see #getSupportedDistortionBits()
217 * @see #getMinimumDistortionBits()
218 */
220
221 /**
222 * Returns the minimum distortion compensation bits as required by the {@link StereoDeviceRenderer},
223 * e.g. {@link StereoDeviceRenderer#DISTORTION_BARREL} in case the stereoscopic display uses [a]spherical lenses.
224 * <p>
225 * Minimum distortion compensation bits are being enforced by the {@link StereoDeviceRenderer}.
226 * </p>
227 * @see #getSupportedDistortionBits()
228 * @see #getRecommendedDistortionBits()
229 * @see StereoDeviceRenderer#getDistortionBits()
230 * @see #createRenderer(int, int, Vec3f, FovHVHalves[], float, int)
231 */
233
234 /**
235 * Create a new {@link StereoDeviceRenderer} instance.
236 *
237 * @param distortionBits {@link StereoDeviceRenderer} distortion bits, e.g. {@link StereoDeviceRenderer#DISTORTION_BARREL}, etc,
238 * see {@link #getRecommendedDistortionBits()}.
239 * @param textureCount desired texture count for post-processing, see {@link StereoDeviceRenderer#getTextureCount()} and {@link StereoDeviceRenderer#ppAvailable()}
240 * @param eyePositionOffset eye position offset, e.g. {@link #getDefaultEyePositionOffset()}.
241 * @param eyeFov FovHVHalves[] field-of-view per eye, e.g. {@link #getDefaultFOV()}. May contain only one value for monoscopic devices,
242 * see {@link #getEyeRenderOrder()}.
243 * @param pixelsPerDisplayPixel
244 * @param textureUnit
245 * @return
246 */
247 public StereoDeviceRenderer createRenderer(final int distortionBits,
248 final int textureCount, final Vec3f eyePositionOffset,
249 final FovHVHalves[] eyeFov, final float pixelsPerDisplayPixel, final int textureUnit);
250}
Horizontal and vertical field of view (FOV) halves, allowing a non-centered projection.
3D Vector based upon three float components.
Definition: Vec3f.java:37
Constant parameter of the positioning sensor to locate the ViewerPose.
Platform agnostic StereoDevice factory.
Immutable Dimension Interface, consisting of it's read only components:
Stereoscopic device rendering interface.
Interface describing a native stereoscopic device.
DimensionImmutable getSurfaceSize()
Returns the required surface size in pixel in target space.
Vec3f getDefaultEyePositionOffset()
Return the device default eye position offset for createRenderer(int, int, Vec3f, FovHVHalves[],...
int getMinimumDistortionBits()
Returns the minimum distortion compensation bits as required by the StereoDeviceRenderer,...
int getSupportedDistortionBits()
Returns the supported distortion compensation of the StereoDeviceRenderer, e.g.
boolean startSensors(int desiredSensorBits, int requiredSensorBits)
Start desired and required sensors.
PointImmutable getPosition()
If operation within a device spanning virtual desktop, returns the device position.
static final int SENSOR_POSITION
Sensor Bit: Positional tracking.
int getRecommendedDistortionBits()
Returns the recommended distortion compensation bits for the StereoDeviceRenderer,...
boolean getSensorsStarted()
Return true if sensors have been started, false otherwise.
StereoDeviceRenderer createRenderer(final int distortionBits, final int textureCount, final Vec3f eyePositionOffset, final FovHVHalves[] eyeFov, final float pixelsPerDisplayPixel, final int textureUnit)
Create a new StereoDeviceRenderer instance.
FovHVHalves[] getDefaultFOV()
Returns the device default FovHVHalves for all supported eyes in natural order, i....
void resetLocationSensorOrigin()
Sets the location sensor's origin of this device to the current position.
static final int SENSOR_YAW_CORRECTION
Sensor Bit: Yaw correction.
static final int SENSOR_ORIENTATION
Sensor Bit: Orientation tracking.
int getSupportedSensorBits()
Returns the supported sensor capability bits, e.g.
int[] getEyeRenderOrder()
Returns an array of the preferred eye rendering order.
boolean isValid()
Returns true, if instance is created and not disposed, otherwise returns false.
void dispose()
Disposes this StereoDevice, if valid.
int getEnabledSensorBits()
Returns the actual used sensor capability bits, e.g.
LocationSensorParameter getLocationSensorParams()
Returns the LocationSensorParameter of the device if SENSOR_POSITION is supported,...
StereoDeviceFactory getFactory()
Return the factory used to create this device.
int getRequiredRotation()
Returns the CCW rotation as required by this display device.