# Package javax.media.nativewindow

NativeWindow Protocol Specification Overview

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AbstractGraphicsConfiguration | A marker interface describing a graphics configuration, visual, or pixel format in a toolkit-independent manner.
  AbstractGraphicsDevice | A interface describing a graphics device in a toolkit-independent manner.
  AbstractGraphicsScreen | A interface describing a graphics screen in a toolkit-independent manner.
  CapabilitiesChooser | Provides a mechanism by which applications can customize the window type selection for a given `Capabilities`.
  CapabilitiesImmutable | Specifies an immutable set of capabilities that a window's rendering context must support, such as color depth per channel.
  MutableSurface | Provides a `NativeSurface` with a mutable `surfaceHandle` via `MutableSurface.setSurfaceHandle(long)`.
  NativeSurface | Provides low-level information required for hardware-accelerated rendering using a surface in a platform-independent manner.
  NativeSurfaceHolder | Accessor interface for implementing classes with ownership of a `NativeSurface` via an is-a or has-a relation.
  NativeWindow | Extend the `NativeSurface` interface with windowing information such as `window-handle`, `window-size` and `window-position`.
  OffscreenLayerOption | Handling requests for using an `OffscreenLayerSurface` within the implementation.
  OffscreenLayerSurface | Interface specifying the offscreen layer surface protocol.
  ProxySurface | Provides a mutable `NativeSurface`, i.e.
  ScalableSurface | Adding mutable surface pixel scale property to implementing class, usually to a `NativeSurface` implementation, see `ScalableSurface.setSurfaceScale(int[])`.
  SurfaceUpdatedListener | Clients may add their SurfaceUpdateListener implementation to a `NativeSurface` allowing to get notified after the surface has been updated, eg.
  ToolkitLock | Marker for a singleton global recursive blocking lock implementation, optionally locking a native windowing toolkit as well.
  UpstreamSurfaceHook | Interface allowing upstream caller to pass lifecycle actions and size info to a `ProxySurface` instance.
  UpstreamSurfaceHook.MutableSize | `UpstreamSurfaceHook` w/ mutable size, allowing it's `ProxySurface` user to resize.
  VisualIDHolder | Visual ID holder interface.
  WindowClosingProtocol | Protocol for handling window closing events.

- Class Summary
  Class | Description
  --- | ---
  Capabilities | Specifies a set of capabilities that a window's rendering context must support, such as color depth per channel.
  DefaultCapabilitiesChooser | The default implementation of the `CapabilitiesChooser` interface, which provides consistent visual selection behavior across platforms.
  DefaultGraphicsConfiguration |
  DefaultGraphicsDevice |
  DefaultGraphicsScreen |
  GraphicsConfigurationFactory | Provides the mechanism by which the graphics configuration for a window can be chosen before the window is created.
  NativeWindowFactory | Provides a pluggable mechanism for arbitrary window toolkits to adapt their components to the `NativeWindow` interface, which provides a platform-independent mechanism of accessing the information required to perform operations like hardware-accelerated rendering using the OpenGL API.
  VisualIDHolder.VIDComparator | Comparing `VisualIDHolder.VIDType.NATIVE`

- Enum Summary
  Enum | Description
  --- | ---
  VisualIDHolder.VIDType |
  WindowClosingProtocol.WindowClosingMode | Window closing mode if triggered by toolkit close operation.

- Exception Summary
  Exception | Description
  --- | ---
  NativeWindowException | A generic exception for OpenGL errors used throughout the binding as a substitute for `RuntimeException`.

## Package javax.media.nativewindow Description

## NativeWindow Protocol Specification Overview

### Preface

This specification, an optional set of packages, describing a protocol for a native windowing interface binding to Java(TM).
Currently specified native windowing systems are:

- EGL/OpenKODE Windowing System
- X11 Windowing System
- Microsoft Windows
- Apple MacOSX
- Java's AWT

However, any other native windowing system may be added to the implementation, using a generic string identifier and an optional specialisation of:

- `AbstractGraphicsDevice`,

  Shall return the new string identifier with `getType()`

- `AbstractGraphicsScreen`
- `AbstractGraphicsConfiguration`

The implementor has to provide the following:

- The specialisation of the abstract class `NativeWindowFactory`

  shall be registered with `NativeWindowFactory.registerFactory(..)`.

- The specialisation of the abstract class `GraphicsConfigurationFactory`

  shall be registered with `GraphicsConfigurationFactory.registerFactory(..)`.

This protocol does not describe how to create native windows, but how to bind a native surface to an implementation of and window to an implementation of `NativeSurface`.

`NativeWindow` specializes the NativeSurface.

However, an implementation of this protocol (e.g. `com.jogamp.newt`) may support the creation.

### Dependencies

This binding has dependencies to the following:

- Either of the following Java implementations:
  - Java SE 1.6 or later
  - A mobile JavaVM with language 1.6 support, ie:
    - Android API Level 9 (Version 2.3)
    - JamVM
    with
    - Java 1.4 java.nio implementation

### Package Structure

The packages defined by this specification include:

- The javax.media.nativewindow package

  This package contains Java bindings for a native windowing system.

  Subsequent packages contain marker type classes, containing native characteristics of the windowing system.

  - The javax.media.nativewindow.awt package

    This sub package contains classes to cover the native characteristics of the AWT windowing system.

  - The javax.media.nativewindow.x11 package

    This sub package contains classes to cover the native characteristics of the X11 windowing system.

  - The javax.media.nativewindow.windows package

    This sub package contains classes to cover the native characteristics of the Windows windowing system.

  - The javax.media.nativewindow.macosx package

    This sub package contains classes to cover the native characteristics of the MacOSX windowing system.

  - The javax.media.nativewindow.egl package

    This sub package contains classes to cover the native characteristics of the EGL/OpenKODE windowing system.

### Factory Model

Running on a platform with a supported windowing system, the factory model shall be used to instantiate a native window, see `NativeWindowFactory`.

### Revision History

- Early Draft Review, June 2009
- 2.0.0 Maintenance Release, February 2011
- 2.0.2 Major Release, July 18th 2013

Copyright 2010 JogAmp Community.