Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.media.nativewindow
Interface NativeWindow

All Known Implementing Classes:
  GLWindow, Window

    public interface NativeWindow

Provides the low-level information required for hardware-accelerated rendering in a platform-independent manner. A window toolkit such as the AWT may either implement this interface directly with one of its components, or provide and register an implementation of `NativeWindowFactory` which can create NativeWindow objects for its components.

A NativeWindow created for a particular on-screen component is expected to have the same lifetime as that component. As long as the component is alive, the NativeWindow must be able to control it, and any time it is visible and locked, provide information such as the window handle.

Field Summary
`static int` | `LOCK_SUCCESS` Returned by `lockSurface()` if the surface is locked, and is unchanged.
`static int` | `LOCK_SURFACE_CHANGED` Returned by `lockSurface()` if the surface is locked, but has changed.
`static int` | `LOCK_SURFACE_NOT_READY` Returned by `lockSurface()` if the surface is not ready to be locked.

Method Summary
`void` | `destroy()` destroys the window and releases windowing related resources.
`long` | `getDisplayHandle()` Convenience: Get display handle from AbstractGraphicsConfiguration .
`AbstractGraphicsConfiguration` | `getGraphicsConfiguration()` Returns the graphics configuration corresponding to this window.
`int` | `getHeight()` Returns the current height of this window.
`Exception` | `getLockedStack()` Return the lock-exception, or null if not locked.
`int` | `getScreenIndex()` Convenience: Get display handle from AbstractGraphicsConfiguration .
`long` | `getSurfaceHandle()` Returns the handle to the surface for this NativeWindow.
`int` | `getWidth()` Returns the current width of this window.
`long` | `getWindowHandle()` Returns the window handle for this NativeWindow.
`void` | `invalidate()` render all native window information invalid, as if the native window was destroyed
`boolean` | `isSurfaceLocked()` Return if surface is locked
`int` | `lockSurface()` Lock the surface of this native window
`boolean` | `surfaceSwap()` Provide a mechanism to utilize custom (pre-) swap surface code.
`void` | `surfaceUpdated()` Method invoked after the render toolkit (e.g.
`void` | `unlockSurface()` Unlock the surface of this native window Shall not modify the window handle, see `getWindowHandle()`, or the surface handle, see `lockSurface()`

Field Detail

### LOCK_SURFACE_NOT_READY

    static final int LOCK_SURFACE_NOT_READY

  Returned by `lockSurface()` if the surface is not ready to be locked.

  See Also:
    Constant Field Values

### LOCK_SURFACE_CHANGED

    static final int LOCK_SURFACE_CHANGED

  Returned by `lockSurface()` if the surface is locked, but has changed.

  See Also:
    Constant Field Values

### LOCK_SUCCESS

    static final int LOCK_SUCCESS

  Returned by `lockSurface()` if the surface is locked, and is unchanged.

  See Also:
    Constant Field Values

Method Detail

### lockSurface

    int lockSurface()
                    throws NativeWindowException

  Lock the surface of this native window

  The window handle, see `getWindowHandle()`, and the surface handle, see `lockSurface()`,
  shall be set and be valid after a successfull call, ie a return value other than `LOCK_SURFACE_NOT_READY`.

  The semantics of the underlying native locked resource may be related to the `ToolkitLock` one. Hence it is important that implementation of both harmonize well.
  The implementation may want to aquire the `ToolkitLock` first to become it's owner before proceeding with it's actual surface lock.

  Returns:
    `LOCK_SUCCESS`, `LOCK_SURFACE_CHANGED` or `LOCK_SURFACE_NOT_READY`.
  Throws:
    `NativeWindowException` - if surface is already locked
  See Also:
    `ToolkitLock`

### unlockSurface

    void unlockSurface()
                       throws NativeWindowException

  Unlock the surface of this native window Shall not modify the window handle, see `getWindowHandle()`, or the surface handle, see `lockSurface()`

  Throws:
    `NativeWindowException` - if surface is not locked
  See Also:
    `lockSurface()`, `ToolkitLock`

### isSurfaceLocked

    boolean isSurfaceLocked()

  Return if surface is locked

### getLockedStack

    Exception getLockedStack()

  Return the lock-exception, or null if not locked. The lock-exception is created at `lockSurface()` and hence holds the locker's call stack.

### surfaceSwap

    boolean surfaceSwap()

  Provide a mechanism to utilize custom (pre-) swap surface code. This method is called before the render toolkit (e.g. JOGL) swaps the buffer/surface. The implementation may itself apply the swapping, in which case true shall be returned.

  Returns:
    true if this method completed swapping the surface, otherwise false, in which case eg the GLDrawable implementation has to swap the code.

### surfaceUpdated

    void surfaceUpdated()

  Method invoked after the render toolkit (e.g. JOGL) swapped/changed the buffer/surface.

### invalidate

    void invalidate()

  render all native window information invalid, as if the native window was destroyed

  See Also:
    `destroy()`

### destroy

    void destroy()

  destroys the window and releases windowing related resources.

### getWindowHandle

    long getWindowHandle()

  Returns the window handle for this NativeWindow.

  The window handle should be set/update by `lockSurface()`, where `unlockSurface()` is not allowed to modify it.
  After `unlockSurface()` it is no more guaranteed that the window handle is still valid.

  The window handle shall reflect the platform one for all window related operations, e.g. open, close, resize.

  On X11 this returns an entity of type Window.
  On Microsoft Windows this returns an entity of type HWND.

### getSurfaceHandle

    long getSurfaceHandle()

  Returns the handle to the surface for this NativeWindow.

  The surface handle should be set/update by `lockSurface()`, where `unlockSurface()` is not allowed to modify it. After `unlockSurface()` it is no more guaranteed that the surface handle is still valid. The surface handle shall reflect the platform one for all drawable surface operations, e.g. opengl, swap-buffer.

  On X11 this returns an entity of type Window, since there is no differentiation of surface and window there.
  On Microsoft Windows this returns an entity of type HDC.

### getWidth

    int getWidth()

  Returns the current width of this window.

### getHeight

    int getHeight()

  Returns the current height of this window.

### getGraphicsConfiguration

    AbstractGraphicsConfiguration getGraphicsConfiguration()

  Returns the graphics configuration corresponding to this window.

  See Also:
    `GraphicsConfigurationFactory.chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)`

### getDisplayHandle

    long getDisplayHandle()

  Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice

### getScreenIndex

    int getScreenIndex()

  Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.