javax.media.nativewindow

## Class DefaultGraphicsDevice

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

- All Implemented Interfaces:
    Cloneable, AbstractGraphicsDevice

      public class DefaultGraphicsDevice
      extends Object
      implements Cloneable, AbstractGraphicsDevice

- - ### Field Summary

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

      `DEBUG, DEFAULT_CONNECTION, DEFAULT_UNIT, EXTERNAL_CONNECTION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultGraphicsDevice(String type, String connection, int unitID)` Create an instance with the system default `ToolkitLock`, gathered via `NativeWindowFactory.getDefaultToolkitLock(String)`.
    `DefaultGraphicsDevice(String type, String connection, int unitID, long handle)` Create an instance with the system default `ToolkitLock`.
    `DefaultGraphicsDevice(String type, String connection, int unitID, long handle, ToolkitLock locker)` Create an instance with the given `ToolkitLock` instance, or null `ToolkitLock` if null.

  - ### 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 `AbstractGraphicsDevice.getUnitID()`.
    `long` | `getHandle()` Returns the native handle of the underlying native device, if such thing exist.
    `ToolkitLock` | `getToolkitLock()`
    `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 `AbstractGraphicsDevice.getConnection()`.
    `boolean` | `isHandleOwner()`
    `void` | `lock()` Optionally locking the device, utilizing eg `ToolkitLock.lock()`.
    `boolean` | `open()` Optionally [re]opening the device if handle is `null`.
    `static void` | `swapDeviceHandleAndOwnership(DefaultGraphicsDevice aDevice1, DefaultGraphicsDevice aDevice2)`
    `String` | `toString()`
    `void` | `unlock()` Optionally unlocking the device, utilizing eg `ToolkitLock.unlock()`.
    `void` | `validateLocked()`

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

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

- - ### Constructor Detail

    - #### DefaultGraphicsDevice

          public DefaultGraphicsDevice(String type,
                               String connection,
                               int unitID)

      Create an instance with the system default `ToolkitLock`, gathered via `NativeWindowFactory.getDefaultToolkitLock(String)`.
      Parameters:
        `type` -

    - #### DefaultGraphicsDevice

          public DefaultGraphicsDevice(String type,
                               String connection,
                               int unitID,
                               long handle)

      Create an instance with the system default `ToolkitLock`. gathered via `NativeWindowFactory.getDefaultToolkitLock(String, long)`.
      Parameters:
        `type` -
        `handle` -

    - #### DefaultGraphicsDevice

          public DefaultGraphicsDevice(String type,
                               String connection,
                               int unitID,
                               long handle,
                               ToolkitLock locker)

      Create an instance with the given `ToolkitLock` instance, or null `ToolkitLock` if null.
      Parameters:
        `type` -
        `handle` -
        `locker` - if null, a non blocking null lock is used.

  - ### Method Detail

    - #### clone

          public Object clone()

      Specified by:
        `clone` in interface `AbstractGraphicsDevice`
      Overrides:
        `clone` in class `Object`

    - #### getType

          public final String getType()

      Description copied from interface: `AbstractGraphicsDevice`
      Returns the type of the underlying subsystem, ie NativeWindowFactory.TYPE_KD, NativeWindowFactory.TYPE_X11, ..
      Specified by:
        `getType` in interface `AbstractGraphicsDevice`

    - #### getConnection

          public final String getConnection()

      Description copied from interface: `AbstractGraphicsDevice`
      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 `AbstractGraphicsDevice.getUnitID()`.
      Specified by:
        `getConnection` in interface `AbstractGraphicsDevice`

    - #### getUnitID

          public final int getUnitID()

      Description copied from interface: `AbstractGraphicsDevice`
      Returns the graphics device `unit ID`.
      The `unit ID` support multiple graphics device configurations on a local machine.
      To support remote device, see `AbstractGraphicsDevice.getConnection()`.
      Specified by:
        `getUnitID` in interface `AbstractGraphicsDevice`
      Returns:

    - #### getUniqueID

          public final String getUniqueID()

      Description copied from interface: `AbstractGraphicsDevice`
      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.

      Specified by:
        `getUniqueID` in interface `AbstractGraphicsDevice`

    - #### getHandle

          public final long getHandle()

      Description copied from interface: `AbstractGraphicsDevice`
      Returns the native handle of the underlying native device, if such thing exist.
      Specified by:
        `getHandle` in interface `AbstractGraphicsDevice`

    - #### lock

          public final void lock()

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

      Locking is perfomed via delegation to `ToolkitLock.lock()`, `ToolkitLock.unlock()`.

      Specified by:
        `lock` in interface `AbstractGraphicsDevice`
      See Also:
        `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)`, `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, javax.media.nativewindow.ToolkitLock)`

    - #### validateLocked

          public final void validateLocked()
                                    throws RuntimeException

      Specified by:
        `validateLocked` in interface `AbstractGraphicsDevice`
      Throws:
        `RuntimeException` - if current thread does not hold the lock

    - #### unlock

          public final void unlock()

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

      Locking is perfomed via delegation to `ToolkitLock.lock()`, `ToolkitLock.unlock()`.

      Specified by:
        `unlock` in interface `AbstractGraphicsDevice`
      See Also:
        `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)`, `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, javax.media.nativewindow.ToolkitLock)`

    - #### open

          public boolean open()

      Description copied from interface: `AbstractGraphicsDevice`
      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`.

      Specified by:
        `open` in interface `AbstractGraphicsDevice`
      Returns:
        true if the handle was `null` and opening was successful, otherwise false.

    - #### close

          public boolean close()

      Description copied from interface: `AbstractGraphicsDevice`
      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`.

      Specified by:
        `close` in interface `AbstractGraphicsDevice`
      Returns:
        true if the handle was not `null` and closing was successful, otherwise false.

    - #### isHandleOwner

          public boolean isHandleOwner()

      Specified by:
        `isHandleOwner` in interface `AbstractGraphicsDevice`
      Returns:
        `true` if instance owns the handle to issue `AbstractGraphicsDevice.close()`, otherwise `false`.

    - #### clearHandleOwner

          public void clearHandleOwner()

      Specified by:
        `clearHandleOwner` in interface `AbstractGraphicsDevice`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### swapDeviceHandleAndOwnership

          public static final void swapDeviceHandleAndOwnership(DefaultGraphicsDevice aDevice1,
                                          DefaultGraphicsDevice aDevice2)

    - #### getToolkitLock

          public final ToolkitLock getToolkitLock()

      Returns:
        the used ToolkitLock
      See Also:
        `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long)`, `DefaultGraphicsDevice#DefaultGraphicsDevice(java.lang.String, long, javax.media.nativewindow.ToolkitLock)`

Copyright 2010 JogAmp Community.