com.jogamp.opengl

## Class GLRendererQuirks

- java.lang.Object
- - com.jogamp.opengl.GLRendererQuirks

-     public class GLRendererQuirks
      extends Object

  GLRendererQuirks contains information of known bugs of various GL renderer. This information allows us to workaround them.

  Using centralized quirk identifier enables us to locate code dealing w/ it and hence eases it's maintenance.

  Some `GL_VENDOR` and `GL_RENDERER` strings are listed here .

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `COUNT` Number of quirks known.
    `static int` | `DontCloseX11Display` Closing X11 displays may cause JVM crashes or X11 errors with some buggy drivers while being used in concert w/ OpenGL.
    `static int` | `GL4NeedsGL3Request` GL4 context needs to be requested via GL3 profile attribute OSX >= 10.9.0 - kCGLOGLPVersion_GL4_Core may not produce hw-accel context.
    `static int` | `GLES3ViaEGLES2Config` Bug 925 - Accept an ES3 Context, if reported via GL-Version-String w/o `EGLExt.EGL_OPENGL_ES3_BIT_KHR`.
    `static int` | `GLFlushBeforeRelease` The OpenGL Context needs a `glFlush()` before releasing it, otherwise driver may freeze: OSX < 10.7.3 - NVidia Driver.
    `static int` | `GLNonCompliant` Non compliant GL context due to a buggy implementation not suitable for use.
    `static int` | `GLSharedContextBuggy` Buggy shared OpenGL context support within a multithreaded use-case, not suitable for stable usage.
    `static int` | `GLSLBuggyDiscard` GLSL `discard` command leads to undefined behavior or won't get compiled if being used.
    `static int` | `GLSLNonCompliant` GLSL is not compliant or even not stable (crash) OSX < 10.7.0 (?) - NVidia Driver.
    `static int` | `NeedCurrCtx4ARBCreateContext` Need current GL Context when calling new ARB CreateContext function, otherwise driver crashes the VM.
    `static int` | `NeedCurrCtx4ARBPixFmtQueries` Need current GL Context when calling new ARB pixel format query functions, otherwise driver crashes the VM.
    `static int` | `NoDoubleBufferedBitmap` On Windows no double buffered bitmaps are guaranteed to be available.
    `static int` | `NoDoubleBufferedPBuffer` Crashes XServer when using double buffered PBuffer with GL_RENDERER: Mesa DRI Intel(R) Sandybridge Desktop Mesa DRI Intel(R) Ivybridge Mobile - 3.0 Mesa 8.0.4 Gallium 0.4 on AMD CYPRESS For now, it is safe to disable it w/ hw-acceleration.
    `static int` | `NoFullFBOSupport` No full FBO support, i.e.
    `static int` | `NoMultiSamplingBuffers` With certain drivers no reliable MSAA / FSAA `multi` `sampling` is available, read a crash may occur.
    `static int` | `NoOffscreenBitmap` No offscreen bitmap available, currently true for JOGL's OSX implementation.
    `static int` | `NoSetSwapInterval` Crashes application when trying to set EGL swap interval on Android 4.0.3 / Pandaboard ES / PowerVR SGX 540
    `static int` | `NoSetSwapIntervalPostRetarget` SIGSEGV on setSwapInterval() after changing the context's drawable w/ 'Mesa 8.0.4' dri2SetSwapInterval/DRI2 (soft & intel)
    `static int` | `SingletonEGLDisplayOnly` Bug 948 - NVIDIA 331.38 (Linux X11) EGL impl.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLRendererQuirks()`
    `GLRendererQuirks(int[] quirks, int offset, int len)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addQuirks(GLRendererQuirks quirks)`
    `void` | `addQuirks(int[] quirks, int offset, int len)`
    `static void` | `addStickyDeviceQuirks(AbstractGraphicsDevice device, GLRendererQuirks quirks)` `Adding given quirks` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.
    `static void` | `addStickyDeviceQuirks(AbstractGraphicsDevice device, int[] quirks, int offset, int len)` `Adding given quirks` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.
    `static boolean` | `areSameStickyDevice(AbstractGraphicsDevice device1, AbstractGraphicsDevice device2)` Returns true if both devices have the same `AbstractGraphicsDevice.getUniqueID()`, otherwise false.
    `boolean` | `exist(int quirk)`
    `static boolean` | `existStickyDeviceQuirk(AbstractGraphicsDevice device, int quirk)` `Query` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.
    `static GLRendererQuirks` | `getStickyDeviceQuirks(AbstractGraphicsDevice device)` Retrieval of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.
    `static void` | `pushStickyDeviceQuirks(AbstractGraphicsDevice device, GLRendererQuirks dest)` `Pushing` the sticky `AbstractGraphicsDevice`'s `GLRendererQuirks` to the given `destination`.
    `String` | `toString()`
    `static String` | `toString(int quirk)`
    `StringBuilder` | `toString(StringBuilder sb)`
    `static void` | `validateQuirk(int quirk)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### NoDoubleBufferedPBuffer

          public static final int NoDoubleBufferedPBuffer

      Crashes XServer when using double buffered PBuffer with GL_RENDERER:
      - Mesa DRI Intel(R) Sandybridge Desktop
      - Mesa DRI Intel(R) Ivybridge Mobile - 3.0 Mesa 8.0.4
      - Gallium 0.4 on AMD CYPRESS
      For now, it is safe to disable it w/ hw-acceleration.
      See Also:
        Constant Field Values

    - #### NoDoubleBufferedBitmap

          public static final int NoDoubleBufferedBitmap

      On Windows no double buffered bitmaps are guaranteed to be available.
      See Also:
        Constant Field Values

    - #### NoSetSwapInterval

          public static final int NoSetSwapInterval

      Crashes application when trying to set EGL swap interval on Android 4.0.3 / Pandaboard ES / PowerVR SGX 540
      See Also:
        Constant Field Values

    - #### NoOffscreenBitmap

          public static final int NoOffscreenBitmap

      No offscreen bitmap available, currently true for JOGL's OSX implementation.
      See Also:
        Constant Field Values

    - #### NoSetSwapIntervalPostRetarget

          public static final int NoSetSwapIntervalPostRetarget

      SIGSEGV on setSwapInterval() after changing the context's drawable w/ 'Mesa 8.0.4' dri2SetSwapInterval/DRI2 (soft & intel)
      See Also:
        Constant Field Values

    - #### GLSLBuggyDiscard

          public static final int GLSLBuggyDiscard

      GLSL `discard` command leads to undefined behavior or won't get compiled if being used.

      Appears to have happened on Nvidia Tegra2, but seems to be fine now.
      FIXME: Constrain version.

      See Also:
        Constant Field Values

    - #### GLNonCompliant

          public static final int GLNonCompliant

      Non compliant GL context due to a buggy implementation not suitable for use.

      Currently, Mesa >= 9.1.3 (may extend back as far as 9.0) OpenGL 3.1 compatibility context is not compliant. Most programs will give completely broken output (or no output at all. For now, this context is not trusted.

      The above has been confirmed for the following Mesa 9.* GL_RENDERER strings:
      - Mesa .* Intel(R) Sandybridge Desktop
      - Gallium 0.4 on AMD RS880

      It still has to be verified whether the AMD OpenGL 3.1 core driver is compliant enought.

      See Also:
        Constant Field Values

    - #### GLFlushBeforeRelease

          public static final int GLFlushBeforeRelease

      The OpenGL Context needs a `glFlush()` before releasing it, otherwise driver may freeze:
      - OSX < 10.7.3 - NVidia Driver. Bug 533 and Bug 548 @ https://jogamp.org/bugzilla/.
      See Also:
        Constant Field Values

    - #### DontCloseX11Display

          public static final int DontCloseX11Display

      Closing X11 displays may cause JVM crashes or X11 errors with some buggy drivers while being used in concert w/ OpenGL.

      Some drivers may require X11 displays to be closed in the same order as they were created, some may not allow them to be closed at all while resources are being used somehow.

      Drivers known exposing such bug:

      - Mesa < 8.0 _with_ X11 software renderer `Mesa X11`, not with GLX/DRI renderer.
      - ATI proprietary Catalyst X11 driver versions:
        - 8.78.6
        - 8.881
        - 8.911
        - 9.01.8

      See Bug 515 - https://jogamp.org/bugzilla/show_bug.cgi?id=515 and `X11Util.ATI_HAS_XCLOSEDISPLAY_BUG`.

      See Bug 705 - https://jogamp.org/bugzilla/show_bug.cgi?id=705

      See Also:
        Constant Field Values

    - #### NeedCurrCtx4ARBPixFmtQueries

          public static final int NeedCurrCtx4ARBPixFmtQueries

      Need current GL Context when calling new ARB pixel format query functions, otherwise driver crashes the VM.

      Drivers known exposing such bug:

      - ATI proprietary Catalyst driver on Windows version ≤ XP. TODO: Validate if bug actually relates to 'old' ATI Windows drivers for old GPU's like X300 regardless of the Windows version.

      See Bug 480 - https://jogamp.org/bugzilla/show_bug.cgi?id=480

      See Also:
        Constant Field Values

    - #### NeedCurrCtx4ARBCreateContext

          public static final int NeedCurrCtx4ARBCreateContext

      Need current GL Context when calling new ARB CreateContext function, otherwise driver crashes the VM.

      Drivers known exposing such bug:

      - ATI proprietary Catalyst Windows driver on laptops with a driver version as reported in GL_VERSION:
        - null
        - < `12.102.3.0` ( amd_catalyst_13.5_mobility_beta2 )

      See Bug 706 - https://jogamp.org/bugzilla/show_bug.cgi?id=706
      See Bug 520 - https://jogamp.org/bugzilla/show_bug.cgi?id=520

      See Also:
        Constant Field Values

    - #### NoFullFBOSupport

          public static final int NoFullFBOSupport

      No full FBO support, i.e. not compliant w/
      - GL_ARB_framebuffer_object
      - EXT_framebuffer_object
      - EXT_framebuffer_multisample
      - EXT_framebuffer_blit
      - EXT_packed_depth_stencil
      . Drivers known exposing such bug:
      - Mesa 7.12-devel on Windows with VMware SVGA3D renderer:
        - GL_VERSION: 2.1 Mesa 7.12-devel (git-d6c318e)
        - GL_RENDERER: Gallium 0.4 on SVGA3D; build: RELEASE;
      Quirk can also be enabled via property: `jogl.fbo.force.min`.
      See Also:
        Constant Field Values

    - #### GLSLNonCompliant

          public static final int GLSLNonCompliant

      GLSL is not compliant or even not stable (crash)
      - OSX < 10.7.0 (?) - NVidia Driver. Bug 818 @ https://jogamp.org/bugzilla/.
      See Also:
        Constant Field Values

    - #### GL4NeedsGL3Request

          public static final int GL4NeedsGL3Request

      GL4 context needs to be requested via GL3 profile attribute
      - OSX >= 10.9.0 - kCGLOGLPVersion_GL4_Core may not produce hw-accel context. Bug 867 @ https://jogamp.org/bugzilla/.
      See Also:
        Constant Field Values

    - #### GLSharedContextBuggy

          public static final int GLSharedContextBuggy

      Buggy shared OpenGL context support within a multithreaded use-case, not suitable for stable usage.

      X11 Mesa DRI Intel(R) driver >= 9.2.1 cannot handle multithreaded shared GLContext usage with non-blocking exclusive X11 display connections. References:

      - Bug 873: https://jogamp.org/bugzilla/show_bug.cgi?id=873
      - https://bugs.freedesktop.org/show_bug.cgi?id=41736#c8

      However, not all multithreaded use-cases are broken, e.g. our GLMediaPlayer does work.

      The above has been confirmed for the following Mesa 9.* strings:
      - GL_VENDOR Intel Open Source Technology Center
      - GL_RENDERER Mesa DRI Intel(R) Sandybridge Desktop
      - GL_RENDERER Mesa DRI Intel(R) Ivybridge Mobile
      - GL_VERSION 3.1 (Core Profile) Mesa 9.2.1

      On Android 4.*, Huawei's Ascend G615 w/ Immersion.16 could not make a shared context current, which uses a pbuffer drawable:

      - Android 4.*
      - GL_VENDOR Hisilicon Technologies
      - GL_RENDERER Immersion.16
      - GL_VERSION OpenGL ES 2.0

      See Also:
        Constant Field Values

    - #### GLES3ViaEGLES2Config

          public static final int GLES3ViaEGLES2Config

      Bug 925 - Accept an ES3 Context, if reported via GL-Version-String w/o `EGLExt.EGL_OPENGL_ES3_BIT_KHR`.

      The ES3 Context can be used via `EGL.EGL_OPENGL_ES2_BIT`.

      The ES3 Context `must be created` with version attributes:

            EGL.EGL_CONTEXT_CLIENT_VERSION, 2, ..

      - Mesa/AMD >= 9.2.1
      - Some Android ES3 drivers ..
      See Also:
        Constant Field Values

    - #### SingletonEGLDisplayOnly

          public static final int SingletonEGLDisplayOnly

      Bug 948 - NVIDIA 331.38 (Linux X11) EGL impl. only supports _one_ EGL Device via `EGL.eglGetDisplay(long)`.

      Subsequent calls to `EGL.eglGetDisplay(long)` fail.

      Reusing global EGL display works.

      The quirk is autodetected within EGLDrawableFactory's initial default device setup!

      Appears on:

      - EGL_VENDOR NVIDIA
      - EGL_VERSION 1.4
      - GL_VENDOR NVIDIA Corporation
      - GL_VERSION OpenGL ES 3.0 331.38 (probably w/ 1st NV EGL lib on x86)
      - Platform X11
      - CPU Family `Platform.CPUFamily#X86`
      See Also:
        Constant Field Values

    - #### NoMultiSamplingBuffers

          public static final int NoMultiSamplingBuffers

      With certain drivers no reliable MSAA / FSAA `multi` `sampling` is available, read a crash may occur.

      Appears on:

      - GL_VENDOR nouveau
      - GL_RENDERER Gallium 0.4 on NV34
      TODO: We have to determine the exact version range, i.e. not adding the quirk with fixed driver version! TODO: Since we currently don't handle this quirk internally, a user may need to do the following:

           final AbstractGraphicsDevice adevice = GLDrawableFactory.getDesktopFactory(); // or similar
           if( GLRendererQuirks.existStickyDeviceQuirk(adevice, GLRendererQuirks.NoMultiSamplingBuffers) ) {
              // don't use MSAA
           }

      See Also:
        Constant Field Values

    - #### COUNT

          public static final int COUNT

      Number of quirks known.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### GLRendererQuirks

          public GLRendererQuirks()

    - #### GLRendererQuirks

          public GLRendererQuirks(int[] quirks,
                          int offset,
                          int len)
                           throws IllegalArgumentException

      Parameters:
        `quirks` - an array of valid quirks
        `offset` - offset in quirks array to start reading
        `len` - number of quirks to read from offset within quirks array
      Throws:
        `IllegalArgumentException` - if one of the quirks is out of range

  - ### Method Detail

    - #### getStickyDeviceQuirks

          public static GLRendererQuirks getStickyDeviceQuirks(AbstractGraphicsDevice device)

      Retrieval of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.

      The `AbstractGraphicsDevice`s are mapped via their `AbstractGraphicsDevice.getUniqueID()`.

      Not thread safe.

      See Also:
        `areSameStickyDevice(AbstractGraphicsDevice, AbstractGraphicsDevice)`

    - #### areSameStickyDevice

          public static boolean areSameStickyDevice(AbstractGraphicsDevice device1,
                                    AbstractGraphicsDevice device2)

      Returns true if both devices have the same `AbstractGraphicsDevice.getUniqueID()`, otherwise false.

    - #### addStickyDeviceQuirks

          public static void addStickyDeviceQuirks(AbstractGraphicsDevice device,
                                   int[] quirks,
                                   int offset,
                                   int len)
                                            throws IllegalArgumentException

      `Adding given quirks` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.

      Not thread safe.

      Throws:
        `IllegalArgumentException`
      See Also:
        `getStickyDeviceQuirks(AbstractGraphicsDevice)`

    - #### addStickyDeviceQuirks

          public static void addStickyDeviceQuirks(AbstractGraphicsDevice device,
                                   GLRendererQuirks quirks)
                                            throws IllegalArgumentException

      `Adding given quirks` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.

      Not thread safe.

      Throws:
        `IllegalArgumentException`
      See Also:
        `getStickyDeviceQuirks(AbstractGraphicsDevice)`

    - #### existStickyDeviceQuirk

          public static boolean existStickyDeviceQuirk(AbstractGraphicsDevice device,
                                       int quirk)

      `Query` of sticky `AbstractGraphicsDevice`'s `GLRendererQuirks`.

      Not thread safe. However, use after changing the sticky quirks is safe.

      See Also:
        `getStickyDeviceQuirks(AbstractGraphicsDevice)`

    - #### pushStickyDeviceQuirks

          public static void pushStickyDeviceQuirks(AbstractGraphicsDevice device,
                                    GLRendererQuirks dest)

      `Pushing` the sticky `AbstractGraphicsDevice`'s `GLRendererQuirks` to the given `destination`.

      Not thread safe. However, use after changing the sticky quirks is safe.

      See Also:
        `getStickyDeviceQuirks(AbstractGraphicsDevice)`

    - #### addQuirks

          public final void addQuirks(int[] quirks,
                       int offset,
                       int len)
                               throws IllegalArgumentException

      Parameters:
        `quirks` - an array of valid quirks to be added
        `offset` - offset in quirks array to start reading
        `len` - number of quirks to read from offset within quirks array
      Throws:
        `IllegalArgumentException` - if one of the quirks is out of range

    - #### addQuirks

          public final void addQuirks(GLRendererQuirks quirks)

      Parameters:
        `quirks` - valid GLRendererQuirks to be added

    - #### exist

          public final boolean exist(int quirk)
                              throws IllegalArgumentException

      Parameters:
        `quirk` - the quirk to be tested
      Returns:
        true if quirk exist, otherwise false
      Throws:
        `IllegalArgumentException` - if quirk is out of range

    - #### toString

          public final StringBuilder toString(StringBuilder sb)

    - #### toString

          public final String toString()

      Overrides:
        `toString` in class `Object`

    - #### validateQuirk

          public static void validateQuirk(int quirk)
                                    throws IllegalArgumentException

      Parameters:
        `quirk` - the quirk to be validated, i.e. whether it is out of range
      Throws:
        `IllegalArgumentException` - if quirk is out of range

    - #### toString

          public static final String toString(int quirk)
                                       throws IllegalArgumentException

      Parameters:
        `quirk` - the quirk to be converted to String
      Returns:
        the String equivalent of this quirk
      Throws:
        `IllegalArgumentException` - if quirk is out of range

Copyright 2010 JogAmp Community.