Package 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: with
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.
- The com.jogamp.nativewindow.awt package
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 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 givenCapabilities
.CapabilitiesImmutable Specifies an immutable set of capabilities that a window's rendering context must support, such as color depth per channel.MutableSurface 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 aNativeSurface
via an is-a or has-a relation.NativeWindow Extend theNativeSurface
interface with windowing information such aswindow-handle
,window-size
andwindow-position
.OffscreenLayerOption Handling requests for using anOffscreenLayerSurface
within the implementation.OffscreenLayerSurface Interface specifying the offscreen layer surface protocol.ProxySurface Provides a mutableNativeSurface
, i.e.ScalableSurface Adding mutable surface pixel scale property to implementing class, usually to aNativeSurface
implementation, seeScalableSurface.setSurfaceScale(float[])
.SurfaceUpdatedListener Clients may add their SurfaceUpdateListener implementation to aNativeSurface
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 aProxySurface
instance.UpstreamSurfaceHook.MutableSize UpstreamSurfaceHook
w/ mutable size, allowing it'sProxySurface
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 theCapabilitiesChooser
interface, which provides consistent visual selection behavior across platforms.DefaultGraphicsConfiguration DefaultGraphicsDevice DefaultGraphicsScreen DelegatedUpstreamSurfaceHookMutableSize DelegatedUpstreamSurfaceHookWithSurfaceSize GenericUpstreamSurfacelessHook GraphicsConfigurationFactory Provides the mechanism by which the graphics configuration for a window can be chosen before the window is created.MutableGraphicsConfiguration NativeWindowFactory Provides a pluggable mechanism for arbitrary window toolkits to adapt their components to theNativeWindow
interface, which provides a platform-independent mechanism of accessing the information required to perform operations like hardware-accelerated rendering using the OpenGL API.NativeWindowVersion UpstreamSurfaceHookMutableSize UpstreamWindowHookMutableSizePos VisualIDHolder.VIDComparator ComparingVisualIDHolder.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 forRuntimeException
.