javax.media.nativewindow

## Class Capabilities

- java.lang.Object
- - javax.media.nativewindow.Capabilities

- All Implemented Interfaces:
    WriteCloneable, Cloneable, Comparable<CapabilitiesImmutable>, CapabilitiesImmutable, VisualIDHolder
  Direct Known Subclasses:
    GLCapabilities

      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 javax.media.nativewindow.VisualIDHolder

      `VisualIDHolder.VIDComparator, VisualIDHolder.VIDType`

  - ### Field Summary

    - ### Fields inherited from interface javax.media.nativewindow.VisualIDHolder

      `VID_UNDEFINED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Capabilities()` Creates a Capabilities object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `clone()`
    `Object` | `cloneMutable()`
    `int` | `compareTo(CapabilitiesImmutable caps)` Comparing RGBA values only
    `Capabilities` | `copyFrom(CapabilitiesImmutable other)` Copies all `Capabilities` values from `source` into this instance.
    `boolean` | `equals(Object obj)` Equality over the immutable attributes of both objects
    `int` | `getAlphaBits()` Returns the number of bits for the color buffer's alpha component.
    `int` | `getBlueBits()` Returns the number of bits for the color buffer's blue component.
    `int` | `getGreenBits()` Returns the number of bits for the color buffer's green component.
    `int` | `getRedBits()` Returns the number of bits for the color buffer's red component.
    `int` | `getTransparentAlphaValue()` Gets the transparent alpha value for the frame buffer configuration.
    `int` | `getTransparentBlueValue()` Gets the transparent blue value for the frame buffer configuration.
    `int` | `getTransparentGreenValue()` Gets the transparent green value for the frame buffer configuration.
    `int` | `getTransparentRedValue()` Gets the transparent red value for the frame buffer configuration.
    `int` | `getVisualID(VisualIDHolder.VIDType type)` Returns the native visual ID of the given `type` if supported, or `VisualIDHolder.VID_UNDEFINED` if not supported.
    `int` | `hashCode()` hash code over the immutable attributes of both objects
    `boolean` | `isBackgroundOpaque()` Returns whether an opaque or translucent surface is requested, supported or chosen.
    `boolean` | `isBitmap()` Returns whether bitmap offscreen mode is requested, available or chosen.
    `boolean` | `isOnscreen()` 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.
    `String` | `toString()` Returns a textual representation of this Capabilities object.
    `StringBuilder` | `toString(StringBuilder sink)` Return a textual representation of this object.

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Capabilities

          public Capabilities()

      Creates a Capabilities object. All attributes are in a default state.

  - ### Method Detail

    - #### cloneMutable

          public Object cloneMutable()

      Specified by:
        `cloneMutable` in interface `WriteCloneable`

    - #### clone

          public Object clone()

      Overrides:
        `clone` in class `Object`

    - #### 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`

Copyright 2010 JogAmp Community.