javax.media.nativewindow

## Interface AbstractGraphicsDevice

- All Superinterfaces:
    Cloneable
  All Known Implementing Classes:
    DefaultGraphicsDevice

      public interface AbstractGraphicsDevice
      extends Cloneable

  A interface describing a graphics device in a toolkit-independent manner.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`
    `static String` | `DEFAULT_CONNECTION` Dummy connection value for a default connection where no native support for multiple devices is available
    `static int` | `DEFAULT_UNIT` Default unit id for the 1st device: 0
    `static String` | `EXTERNAL_CONNECTION` Dummy connection value for an external connection where no native support for multiple devices is available

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearHandleOwner()`
    `Object` | `clone()`
    `boolean` | `close()` Optionally closing the device if handle is not `null`.
    `String` | `getConnection()` Returns the semantic GraphicsDevice connection. On platforms supporting remote devices, eg via tcp/ip network, the implementation shall return a unique name for each remote address. On X11 for example, the connection string should be as the following example. `:0.0` for a local connection `remote.host.net:0.0` for a remote connection To support multiple local device, see `getUnitID()`.
    `long` | `getHandle()` Returns the native handle of the underlying native device, if such thing exist.
    `String` | `getType()` Returns the type of the underlying subsystem, ie NativeWindowFactory.TYPE_KD, NativeWindowFactory.TYPE_X11, ..
    `String` | `getUniqueID()` Returns a unique ID object of this device using `type`, `connection` and `unitID` as it's key components.
    `int` | `getUnitID()` Returns the graphics device `unit ID`. The `unit ID` support multiple graphics device configurations on a local machine. To support remote device, see `getConnection()`.
    `boolean` | `isHandleOwner()`
    `void` | `lock()` Optionally locking the device, utilizing eg `ToolkitLock.lock()`.
    `boolean` | `open()` Optionally [re]opening the device if handle is `null`.
    `void` | `unlock()` Optionally unlocking the device, utilizing eg `ToolkitLock.unlock()`.
    `void` | `validateLocked()`

- - ### Field Detail

    - #### DEBUG

          static final boolean DEBUG

    - #### DEFAULT_CONNECTION

          static final String DEFAULT_CONNECTION

      Dummy connection value for a default connection where no native support for multiple devices is available
      See Also:
        Constant Field Values

    - #### EXTERNAL_CONNECTION

          static final String EXTERNAL_CONNECTION

      Dummy connection value for an external connection where no native support for multiple devices is available
      See Also:
        Constant Field Values

    - #### DEFAULT_UNIT

          static final int DEFAULT_UNIT

      Default unit id for the 1st device: 0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### clone

          Object clone()

    - #### getType

          String getType()

      Returns the type of the underlying subsystem, ie NativeWindowFactory.TYPE_KD, NativeWindowFactory.TYPE_X11, ..

    - #### getConnection

          String getConnection()

      Returns the semantic GraphicsDevice connection.
      On platforms supporting remote devices, eg via tcp/ip network, the implementation shall return a unique name for each remote address.
      On X11 for example, the connection string should be as the following example.
      - `:0.0` for a local connection
      - `remote.host.net:0.0` for a remote connection
      To support multiple local device, see `getUnitID()`.

    - #### getUnitID

          int getUnitID()

      Returns the graphics device `unit ID`.
      The `unit ID` support multiple graphics device configurations on a local machine.
      To support remote device, see `getConnection()`.
      Returns:

    - #### getUniqueID

          String getUniqueID()

      Returns a unique ID object of this device using `type`, `connection` and `unitID` as it's key components.

      The unique ID does not reflect the instance of the device, hence the handle is not included. The unique ID may be used as a key for semantic device mapping.

      The returned string object reference is unique using `String.intern()` and hence can be used as a key itself.

    - #### getHandle

          long getHandle()

      Returns the native handle of the underlying native device, if such thing exist.

    - #### lock

          void lock()

      Optionally locking the device, utilizing eg `ToolkitLock.lock()`. The lock implementation must be recursive.

    - #### unlock

          void unlock()

      Optionally unlocking the device, utilizing eg `ToolkitLock.unlock()`. The lock implementation must be recursive.
      Throws:
        `RuntimeException` - in case the lock is not acquired by this thread.

    - #### validateLocked

          void validateLocked()
                              throws RuntimeException

      Throws:
        `RuntimeException` - if current thread does not hold the lock

    - #### open

          boolean open()

      Optionally [re]opening the device if handle is `null`.

      The default implementation is a `NOP`.

      Example implementations like `X11GraphicsDevice` or `com.jogamp.nativewindow.egl.EGLGraphicsDevice` issue the native open operation in case handle is `null`.

      Returns:
        true if the handle was `null` and opening was successful, otherwise false.

    - #### close

          boolean close()

      Optionally closing the device if handle is not `null`.

      The default implementation `dispose` it's `ToolkitLock` and sets the handle to `null`.

      Example implementations like `X11GraphicsDevice` or `com.jogamp.nativewindow.egl.EGLGraphicsDevice` issue the native close operation or skip it depending on the `handles's ownership`.

      Returns:
        true if the handle was not `null` and closing was successful, otherwise false.

    - #### isHandleOwner

          boolean isHandleOwner()

      Returns:
        `true` if instance owns the handle to issue `close()`, otherwise `false`.

    - #### clearHandleOwner

          void clearHandleOwner()

Copyright 2010 JogAmp Community.