JOGL 2.3.2 · com.jogamp.nativewindow

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 com.jogamp.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 com.jogamp.nativewindow.awt package
  This sub package contains classes to cover the native characteristics of the AWT windowing system.
- The com.jogamp.nativewindow.x11 package
  This sub package contains classes to cover the native characteristics of the X11 windowing system.
- The com.jogamp.nativewindow.windows package
  This sub package contains classes to cover the native characteristics of the Windows windowing system.
- The com.jogamp.nativewindow.macosx package
  This sub package contains classes to cover the native characteristics of the MacOSX windowing system.
- The com.jogamp.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

Interface Summary

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

Class Summary

Modifier and Type	Class and Description
public class	Capabilities Specifies a set of capabilities that a window's rendering context must support, such as color depth per channel.
public class	DefaultCapabilitiesChooser The default implementation of the `CapabilitiesChooser` interface, which provides consistent visual selection behavior across platforms.
public class	DefaultGraphicsConfiguration
public class	DefaultGraphicsDevice
public class	DefaultGraphicsScreen
public class	DelegatedUpstreamSurfaceHookMutableSize
public class	DelegatedUpstreamSurfaceHookWithSurfaceSize
public class	GenericUpstreamSurfacelessHook
public abstract class	GraphicsConfigurationFactory Provides the mechanism by which the graphics configuration for a window can be chosen before the window is created.
public class	MutableGraphicsConfiguration
public class	NativeWindowException A generic exception for OpenGL errors used throughout the binding as a substitute for `RuntimeException`.
public abstract class	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.
public class	NativeWindowVersion
public class	UpstreamSurfaceHookMutableSize
public class	UpstreamWindowHookMutableSizePos

Package com.jogamp.nativewindow