Class Capabilities

java.lang.Object
com.jogamp.nativewindow.Capabilities
All Implemented Interfaces:
com.jogamp.common.type.WriteCloneable, CapabilitiesImmutable, VisualIDHolder, Cloneable, Comparable<CapabilitiesImmutable>

public class Capabilities extends Object implements CapabilitiesImmutable, Cloneable
Specifies a set of capabilities that a window's rendering context must support, such as color depth per channel. It currently contains the minimal number of routines which allow configuration on all supported window systems.
  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.jogamp.nativewindow.VisualIDHolder

    VisualIDHolder.VIDComparator, VisualIDHolder.VIDType
  • Field Summary

    Fields inherited from interface com.jogamp.nativewindow.VisualIDHolder

    VID_UNDEFINED
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a Capabilities object.
  • Method Summary

    Modifier and Type
    Method
    Description
     
     
    int
    Comparing RGBA values only
    Copies all Capabilities values from source into this instance.
    boolean
    Equality over the immutable attributes of both objects
    final int
    Returns the number of bits for the color buffer's alpha component.
    final int
    Returns the number of bits for the color buffer's blue component.
    final int
    Returns the number of bits for the color buffer's green component.
    final int
    Returns the number of bits for the color buffer's red component.
    final int
    Gets the transparent alpha value for the frame buffer configuration.
    final int
    Gets the transparent blue value for the frame buffer configuration.
    final int
    Gets the transparent green value for the frame buffer configuration.
    final int
    Gets the transparent red value for the frame buffer configuration.
    int
    Returns the native visual ID of the given type if supported, or VisualIDHolder.VID_UNDEFINED if not supported.
    int
    hash code over the immutable attributes of both objects
    final boolean
    Returns whether an opaque or translucent surface is requested, supported or chosen.
    boolean
    Returns whether bitmap offscreen mode is requested, available or chosen.
    final boolean
    Returns whether an on- or offscreen surface is requested, available or chosen.
    void
    setAlphaBits(int alphaBits)
    Sets the number of bits requested for the color buffer's alpha component.
    void
    setBackgroundOpaque(boolean opaque)
    Sets whether the surface shall be opaque or translucent.
    void
    setBitmap(boolean enable)
    Requesting offscreen bitmap mode.
    void
    setBlueBits(int blueBits)
    Sets the number of bits requested for the color buffer's blue component.
    void
    setGreenBits(int greenBits)
    Sets the number of bits requested for the color buffer's green component.
    void
    setOnscreen(boolean onscreen)
    Sets whether the surface shall be on- or offscreen.
    void
    setRedBits(int redBits)
    Sets the number of bits requested for the color buffer's red component.
    void
    setTransparentAlphaValue(int transValueAlpha)
    Sets the transparent alpha value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for alpha.
    void
    setTransparentBlueValue(int transValueBlue)
    Sets the transparent blue value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for blue.
    void
    setTransparentGreenValue(int transValueGreen)
    Sets the transparent green value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for green.
    void
    setTransparentRedValue(int transValueRed)
    Sets the transparent red value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for red.
    Returns a textual representation of this Capabilities object.
    Return a textual representation of this object.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • Capabilities

      public Capabilities()
      Creates a Capabilities object. All attributes are in a default state.
  • Method Details

    • cloneMutable

      public Object cloneMutable()
      Specified by:
      cloneMutable in interface com.jogamp.common.type.WriteCloneable
    • clone

      public Object clone()
    • copyFrom

      public Capabilities copyFrom(CapabilitiesImmutable other)
      Copies all Capabilities values from source into this instance.
      Returns:
      this instance
    • hashCode

      public int hashCode()
      Description copied from interface: CapabilitiesImmutable
      hash code over the immutable attributes of both objects
      Specified by:
      hashCode in interface CapabilitiesImmutable
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Description copied from interface: CapabilitiesImmutable
      Equality over the immutable attributes of both objects
      Specified by:
      equals in interface CapabilitiesImmutable
      Overrides:
      equals in class Object
    • compareTo

      public int compareTo(CapabilitiesImmutable caps)
      Comparing RGBA values only
      Specified by:
      compareTo in interface Comparable<CapabilitiesImmutable>
    • getVisualID

      public int getVisualID(VisualIDHolder.VIDType type) throws NativeWindowException
      Description copied from interface: VisualIDHolder
      Returns the native visual ID of the given type if supported, or VisualIDHolder.VID_UNDEFINED if not supported.

      Depending on the native windowing system, type is handled as follows:

      • X11 throws NativeWindowException on EGL_CONFIG, WIN32_PFD
        • INTRINSIC: X11 XVisual ID
        • NATIVE: X11 XVisual ID
        • X11_XVISUAL: X11 XVisual ID
        • X11_FBCONFIG: VID_UNDEFINED
      • X11/GL throws NativeWindowException on EGL_CONFIG, WIN32_PFD
        • INTRINSIC: X11 XVisual ID
        • NATIVE: X11 XVisual ID
        • X11_XVISUAL: X11 XVisual ID
        • X11_FBCONFIG: X11 FBConfig ID or VID_UNDEFINED
      • Windows/GL throws NativeWindowException on EGL_CONFIG, X11_XVISUAL, X11_FBCONFIG
        • INTRINSIC: Win32 PIXELFORMATDESCRIPTOR ID
        • NATIVE: Win32 PIXELFORMATDESCRIPTOR ID
        • WIN32_PFD: Win32 PIXELFORMATDESCRIPTOR ID
      • EGL/GL throws NativeWindowException on X11_XVISUAL, X11_FBCONFIG, WIN32_PFD
        • INTRINSIC: EGL Config ID
        • NATIVE: EGL NativeVisual ID (X11 XVisual ID, Win32 PIXELFORMATDESCRIPTOR ID, ...)
        • EGL_CONFIG: EGL Config ID

      Note: INTRINSIC and NATIVE are always handled, but may result in VisualIDHolder.VID_UNDEFINED. The latter is true if the native value are actually undefined or the corresponding object is not mapped to a native visual object.
      Specified by:
      getVisualID in interface VisualIDHolder
      Throws:
      NativeWindowException - if type is neither INTRINSIC nor NATIVE and does not match the native implementation.
    • getRedBits

      public final int getRedBits()
      Description copied from interface: CapabilitiesImmutable
      Returns the number of bits for the color buffer's red component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
      Specified by:
      getRedBits in interface CapabilitiesImmutable
    • setRedBits

      public void setRedBits(int redBits)
      Sets the number of bits requested for the color buffer's red component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
    • getGreenBits

      public final int getGreenBits()
      Description copied from interface: CapabilitiesImmutable
      Returns the number of bits for the color buffer's green component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
      Specified by:
      getGreenBits in interface CapabilitiesImmutable
    • setGreenBits

      public void setGreenBits(int greenBits)
      Sets the number of bits requested for the color buffer's green component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
    • getBlueBits

      public final int getBlueBits()
      Description copied from interface: CapabilitiesImmutable
      Returns the number of bits for the color buffer's blue component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
      Specified by:
      getBlueBits in interface CapabilitiesImmutable
    • setBlueBits

      public void setBlueBits(int blueBits)
      Sets the number of bits requested for the color buffer's blue component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
    • getAlphaBits

      public final int getAlphaBits()
      Description copied from interface: CapabilitiesImmutable
      Returns the number of bits for the color buffer's alpha component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.
      Specified by:
      getAlphaBits in interface CapabilitiesImmutable
    • setAlphaBits

      public void setAlphaBits(int alphaBits)
      Sets the number of bits requested for the color buffer's alpha component. On some systems only the color depth, which is the sum of the red, green, and blue bits, is considered.

      Note: If alpha bits are zero, they are set to one by setBackgroundOpaque(boolean) and it's OpenGL specialization GLCapabilities::setSampleBuffers(boolean).
      Ensure to call this method after the above to ensure a zero value.
      The above automated settings takes into account, that the user calls this method to request alpha bits, not to reflect a current state. Nevertheless if this is the case - call it at last.

    • setBackgroundOpaque

      public void setBackgroundOpaque(boolean opaque)
      Sets whether the surface shall be opaque or translucent.

      Platform implementations may need an alpha component in the surface (eg. Windows), or expect pre-multiplied alpha values (eg. X11/XRender).
      To unify the experience, this method also invokes setAlphaBits(1) if getAlphaBits() == 0.
      Please note that in case alpha is required on the platform the clear color shall have an alpha lower than 1.0 to allow anything shining through.

      Mind that translucency may cause a performance penalty due to the composite work required by the window manager.

    • isBackgroundOpaque

      public final boolean isBackgroundOpaque()
      Description copied from interface: CapabilitiesImmutable
      Returns whether an opaque or translucent surface is requested, supported or chosen.

      Default is true, i.e. opaque.

      Specified by:
      isBackgroundOpaque in interface CapabilitiesImmutable
    • setOnscreen

      public void setOnscreen(boolean onscreen)
      Sets whether the surface shall be on- or offscreen.

      Defaults to true.

      If requesting an offscreen surface without further selection of it's mode, e.g. FBO, Pbuffer or bitmap, the implementation will choose the best available offscreen mode.

      Parameters:
      onscreen -
    • isOnscreen

      public final boolean isOnscreen()
      Description copied from interface: CapabilitiesImmutable
      Returns whether an on- or offscreen surface is requested, available or chosen.

      Default is true, i.e. onscreen.

      Mind that an capabilities intance w/ available semantics may show onscreen, but also the offscreen modes FBO, Pbuffer or bitmap. This is valid, since one native configuration maybe used for either functionality.

      Specified by:
      isOnscreen in interface CapabilitiesImmutable
    • setBitmap

      public void setBitmap(boolean enable)
      Requesting offscreen bitmap mode.

      If enabled this method also invokes setOnscreen(false).

      Defaults to false.

      Requesting offscreen bitmap mode disables the offscreen auto selection.

    • isBitmap

      public boolean isBitmap()
      Description copied from interface: CapabilitiesImmutable
      Returns whether bitmap offscreen mode is requested, available or chosen.

      Default is false.

      For chosen capabilities, only the selected offscreen surface is set to true.

      Specified by:
      isBitmap in interface CapabilitiesImmutable
    • getTransparentRedValue

      public final int getTransparentRedValue()
      Description copied from interface: CapabilitiesImmutable
      Gets the transparent red value for the frame buffer configuration. This value is undefined if; equals true.
      Specified by:
      getTransparentRedValue in interface CapabilitiesImmutable
    • getTransparentGreenValue

      public final int getTransparentGreenValue()
      Description copied from interface: CapabilitiesImmutable
      Gets the transparent green value for the frame buffer configuration. This value is undefined if; equals true.
      Specified by:
      getTransparentGreenValue in interface CapabilitiesImmutable
    • getTransparentBlueValue

      public final int getTransparentBlueValue()
      Description copied from interface: CapabilitiesImmutable
      Gets the transparent blue value for the frame buffer configuration. This value is undefined if; equals true.
      Specified by:
      getTransparentBlueValue in interface CapabilitiesImmutable
    • getTransparentAlphaValue

      public final int getTransparentAlphaValue()
      Description copied from interface: CapabilitiesImmutable
      Gets the transparent alpha value for the frame buffer configuration. This value is undefined if; equals true.
      Specified by:
      getTransparentAlphaValue in interface CapabilitiesImmutable
    • setTransparentRedValue

      public void setTransparentRedValue(int transValueRed)
      Sets the transparent red value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for red. This value is ignored if isBackgroundOpaque() equals true.
      It defaults to half of the frambuffer value for red.
      A value of -1 is interpreted as any value.
    • setTransparentGreenValue

      public void setTransparentGreenValue(int transValueGreen)
      Sets the transparent green value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for green. This value is ignored if isBackgroundOpaque() equals true.
      It defaults to half of the frambuffer value for green.
      A value of -1 is interpreted as any value.
    • setTransparentBlueValue

      public void setTransparentBlueValue(int transValueBlue)
      Sets the transparent blue value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for blue. This value is ignored if isBackgroundOpaque() equals true.
      It defaults to half of the frambuffer value for blue.
      A value of -1 is interpreted as any value.
    • setTransparentAlphaValue

      public void setTransparentAlphaValue(int transValueAlpha)
      Sets the transparent alpha value for the frame buffer configuration, ranging from 0 to the maximum frame buffer value for alpha. This value is ignored if isBackgroundOpaque() equals true.
      It defaults to half of the frambuffer value for alpha.
      A value of -1 is interpreted as any value.
    • toString

      public StringBuilder toString(StringBuilder sink)
      Description copied from interface: CapabilitiesImmutable
      Return a textual representation of this object. Use the given StringBuilder [optional].
      Specified by:
      toString in interface CapabilitiesImmutable
    • toString

      public String toString()
      Returns a textual representation of this Capabilities object.
      Specified by:
      toString in interface CapabilitiesImmutable
      Overrides:
      toString in class Object