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:
    • 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

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.
CapabilitiesFilter.Test<C extends CapabilitiesImmutable>	Generic filter criteria
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.
NativeWindowHolder	Accessor interface for implementing classes with ownership of a NativeWindow via an is-a or has-a relation.
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(float[]).
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.
CapabilitiesFilter	Diverse reusable CapabilitiesImmutable list filter
CapabilitiesFilter.TestLessColorCompBits<C extends CapabilitiesImmutable>
CapabilitiesFilter.TestMoreColorCompBits<C extends CapabilitiesImmutable>
CapabilitiesFilter.TestUnmatchedNativeVisualID<C extends CapabilitiesImmutable>
DefaultCapabilitiesChooser	The default implementation of the CapabilitiesChooser 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 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.
NativeWindowVersion
UpstreamSurfaceHookMutableSize
UpstreamWindowHookMutableSizePos
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.