com.jogamp.opengl.util.stereo

## Interface StereoDeviceRenderer

-     public interface StereoDeviceRenderer

  Stereoscopic device rendering interface.

  The following pseudo-code describes how to implement a renderer using a `StereoDeviceRenderer`. See `StereoClientRenderer` which implements the following:

  - device.`beginFrame(GL)`
  - For both eyes:
    - device.`updateEyePose(int)`
    - if device.`ppAvailable()`: Set the render target, e.g. FBO
    - Set the viewport using `StereoDeviceRenderer.Eye.getViewport()`
    - `upstream.reshapeEye(..)`
    - `upstream.display(..)`.
  - Reset the viewport
  - If device.`ppAvailable()`:
    - device.`ppBegin(GL)`
    - Use render target, e.g. FBO's texture
    - device.`#ppBothEyes(GL)` or device.`ppOneEye(GL, int)` for both eyes
    - device.`ppEnd(GL)`
  - device.`endFrame(GL)`

  ##### Correct `Asymmetric FOV` Rendering

  The `StereoClientRenderer` shall render both images for each eye correctly Off-axis utilizing an asymmetric camera frustum, i.e. by using `StereoDevice`'s `default` `FovHVHalves`.
  Some references:

  - Wiki: Binocular Vision
  - Paul Burke: Stereo Graphics - Stereo Renderer
  - Wiki: Distortion (Optics)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `StereoDeviceRenderer.Eye` Interface describing one eye of the stereoscopic device, see `getEye(int)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DISTORTION_BARREL` Distortion Bit: Barrel distortion compensating lens pincushion distortion
    `static int` | `DISTORTION_CHROMATIC` Distortion Bit: Chromatic distortion compensating lens chromatic aberration.
    `static int` | `DISTORTION_TIMEWARP` Distortion Bit: Timewarp distortion technique to predict `EyePose` movement to reduce latency.
    `static int` | `DISTORTION_VIGNETTE` Distortion Bit: Vignette distortion compensating lens chromatic aberration.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beginFrame(GL gl)` Notifying that a new frame is about to start.
    `void` | `dispose(GL gl)` Release all OpenGL related resources
    `void` | `endFrame(GL gl)` Notifying that the frame has been rendered completely.
    `StereoDevice` | `getDevice()` Returns the `StereoDevice` of this `StereoDeviceRenderer` instance.
    `int` | `getDistortionBits()` Returns used distortion compensation bits, e.g.
    `StereoDeviceRenderer.Eye` | `getEye(int eyeNum)` Returns the `StereoDeviceRenderer.Eye` instance for the denoted `eyeNum`.
    `DimensionImmutable` | `getSingleSurfaceSize()` Returns the unified surface size of one eye's a single image in pixel units.
    `int` | `getTextureCount()` Returns the used texture-image count for post-processing, see `ppAvailable()`.
    `int` | `getTextureUnit()` Returns the desired texture-image unit for post-processing, see `ppAvailable()`.
    `DimensionImmutable` | `getTotalSurfaceSize()` Returns the total surface size required for the complete images in pixel units.
    `void` | `init(GL gl)` Initialize OpenGL related resources
    `boolean` | `ppAvailable()` Returns `true` if stereoscopic post-processing is required and available, otherwise `false`.
    `void` | `ppBegin(GL gl)` Begin stereoscopic post-processing, see `ppAvailable()`.
    `void` | `ppEnd(GL gl)` End stereoscopic post-processing, see `ppAvailable()`.
    `void` | `ppOneEye(GL gl, int eyeNum)` Performs stereoscopic post-processing for one eye, see `ppAvailable()`.
    `EyePose` | `updateEyePose(int eyeNum)` Updates the `StereoDeviceRenderer.Eye.getLastEyePose()` for the denoted `eyeNum`.
    `boolean` | `usesSideBySideStereo()` Method returns `true` if using side-by-side (SBS) stereoscopic images, otherwise `false`.

- - ### Field Detail

    - #### DISTORTION_BARREL

          static final int DISTORTION_BARREL

      Distortion Bit: Barrel distortion compensating lens pincushion distortion
      See Also:
        Constant Field Values

    - #### DISTORTION_CHROMATIC

          static final int DISTORTION_CHROMATIC

      Distortion Bit: Chromatic distortion compensating lens chromatic aberration.
      See Also:
        Constant Field Values

    - #### DISTORTION_VIGNETTE

          static final int DISTORTION_VIGNETTE

      Distortion Bit: Vignette distortion compensating lens chromatic aberration.
      See Also:
        Constant Field Values

    - #### DISTORTION_TIMEWARP

          static final int DISTORTION_TIMEWARP

      Distortion Bit: Timewarp distortion technique to predict `EyePose` movement to reduce latency.

      FIXME: Explanation needs refinement!

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getDevice

          StereoDevice getDevice()

      Returns the `StereoDevice` of this `StereoDeviceRenderer` instance.

    - #### getEye

          StereoDeviceRenderer.Eye getEye(int eyeNum)

      Returns the `StereoDeviceRenderer.Eye` instance for the denoted `eyeNum`.

    - #### updateEyePose

          EyePose updateEyePose(int eyeNum)

      Updates the `StereoDeviceRenderer.Eye.getLastEyePose()` for the denoted `eyeNum`.

    - #### getDistortionBits

          int getDistortionBits()

      Returns used distortion compensation bits, e.g. `DISTORTION_BARREL`, in case the stereoscopic display requires such, i.e. in case lenses are utilized.

      Distortion requires `post-processing`.

    - #### usesSideBySideStereo

          boolean usesSideBySideStereo()

      Method returns `true` if using side-by-side (SBS) stereoscopic images, otherwise `false`.

      SBS requires that both eye's images are presented side-by-side in the final framebuffer.

      Either the renderer presents the images side-by-side according to the `eye's viewport`, or `post-processing` is utilized to merge `textures` to a side-by-side configuration.

    - #### getSingleSurfaceSize

          DimensionImmutable getSingleSurfaceSize()

      Returns the unified surface size of one eye's a single image in pixel units.

    - #### getTotalSurfaceSize

          DimensionImmutable getTotalSurfaceSize()

      Returns the total surface size required for the complete images in pixel units.

      If `usesSideBySideStereo()` the total size spans over both `getSingleSurfaceSize()`, side-by-side.

      Otherwise the size is equal to `getSingleSurfaceSize()`.

    - #### getTextureCount

          int getTextureCount()

      Returns the used texture-image count for post-processing, see `ppAvailable()`.

      In case the renderer does not support multiple textures for post-processing, or no post-processing at all, method returns zero despite the request from `StereoDevice#createRenderer(int, int, float[], com.jogamp.opengl.math.FovHVHalves[], float)`.

    - #### getTextureUnit

          int getTextureUnit()

      Returns the desired texture-image unit for post-processing, see `ppAvailable()`.

    - #### init

          void init(GL gl)

      Initialize OpenGL related resources

    - #### dispose

          void dispose(GL gl)

      Release all OpenGL related resources

    - #### beginFrame

          void beginFrame(GL gl)

      Notifying that a new frame is about to start.

    - #### endFrame

          void endFrame(GL gl)

      Notifying that the frame has been rendered completely.

    - #### ppAvailable

          boolean ppAvailable()

      Returns `true` if stereoscopic post-processing is required and available, otherwise `false`.

      Stereoscopic post-processing is available if:

      - one of the distortion bits are set, see `getDistortionBits()`

      If stereoscopic post-processing is used the following post-processing methods must be called to before `#endFrame()`:

      - `ppBegin(GL)`
      - `ppOneEye(GL, int)` for both eyes
      - `ppEnd(GL)`

    - #### ppBegin

          void ppBegin(GL gl)

      Begin stereoscopic post-processing, see `ppAvailable()`.

      `updateEyePose(int)` for both eyes must be called upfront when rendering upstream `StereoGLEventListener`.

      Parameters:
        `gl` -

    - #### ppOneEye

          void ppOneEye(GL gl,
                      int eyeNum)

      Performs stereoscopic post-processing for one eye, see `ppAvailable()`.
      Parameters:
        `gl` -
        `eyeNum` -

    - #### ppEnd

          void ppEnd(GL gl)

      End stereoscopic post-processing, see `ppAvailable()`.
      Parameters:
        `gl` -

Copyright 2010 JogAmp Community.