NEWT - JOGL’s High Performance Native Windowing Toolkit

NEWT Usage

Consider the classic demo code GearsES2.java [v2.0-rc3], which implements a GLEventEventListener.

The simple application TestGearsES2NEWT.java [v2.0-rc3] creates a NEWT GLWindow, which implements a GLAutoDrawable and hence is able to add the demo code. NEWT’s GLWindow also implements the NEWT Window, which gives you full control of the native windowing, as shown in the demo.

Finally we just add our GLWindow to an Animator instance, which renders our demo in it's own rendering thread independent from user input.

For NEWT’s AWT integration, please read the dedicated section below.

NEWT Threading Overview

NEWT’s event model is pretty simple.
It spawns one Event Dispatch Thread (EDT) for each unique Display which role is to handle:

  • input events
  • window lifecycle actions (window visibility, resize, .. etc)
  • not rendering

High performance rendering is achieved without being blocked by input events or vice versa.
As demonstrated in the above NEWT example, rendering does not disturb or lag user input.
This gives you fluent animation even for complex models.

NEWT’s AWT integration and NEWT Applet’s

NewtCanvasAWT, representing an AWT Canvas, allows you to hook a NEWT Window into it.

Since the NewtCanvasAWT is an AWT heavyweight Component, this gives you the ability hook NEWT into an AWT UI.

The implementation uses the AWT native JAWT API to reparent the NEWT Window natively into the AWT one
and hence is even more compatible with JOGL’s GLCanvas implementation.

This enables us to use both worlds, AWT/Swing UI and decoupled high performance rendering.

TestParenting01cAWT.java [v2.0-rc3] shows you how to add an GLWindow to an NewtCanvasAWT, which iself is added to an AWT Frame.
It also shows how the NewtCanvasAWT can be easily removed from the AWT Frame and placed into another AWT Container.
Since we use native reparenting, the native window resource keeps alive and hence your OpenGL application (GLEventListener) is not being asked to dispose all resources.
TestParenting01cSwingAWT.java [v2.0-rc3] shows the same example using Swing.

Last but not least, the above mechanism can be used to show NEWT Window’s in an AWT Applet.
JOGLNewtApplet1Run is an Applet launcher for any GLEventEventListener exposing a default constructor. See it alive here.

Native Window Reparenting Details

NEWT's reparenting algorithm only issues a destroy if:
  • Becomes CHILD-Window
    • new parent window is not realized yet, i.e. parent's window handle is null
    • forceRecreate
    • moving to a new incompatible screen/device
  • Becomes TOP-Level-Window
    • forceRecreate
  • reparenting failed
In case destroy is issued, recreation will follow as soon as the new parent window handle becomes available or the instant if becoming a top-level window.

In case destroy must be issued, the hint REPARENT_HINT_BECOMES_VISIBLE will preserve the GLState at destroy, see below.

To avoid destroy and the GLState preservation, the NEWT window shall simply be reparented before parent's destruction. This is true for 'window hopping' as well as child->top transition. See TestParenting04AWT for example ..

Using GLState Preservation
A preserved GLState will be recovered when the resource gets recreated, e.g. the parent window becomes visible again. This mechanism exists to sooth the destroy case. See: GLStateKeeper, GLEventListenerState Regularly Used in the following use cases:
  • OSX CALayer/Top-Level NEWT reparenting
  • Android GLState preservation: 'Home Button', 'Rotation' ..

How to pass user input back to the rendering loop ?

The following example shows you how to use a fifo to pipe events from the EDT (listener) to the rendering loop.

How to inject some GL action to the rendering loop ?
Shows you how to inject GL render actions into a GL fifo from another thread.

AWT agnostic input event listener
We also have a way to write AWT agnostic input event listener:

We provide some utilities to make life a bit easier.
These are not really necessary, ie you could write and use your own, sure.

The NEWT threading requirements are easy – they are just none for rendering,
and the input event listener should better not lock the rendering GL context.
Well, they can using GLContext.setSynchronized(true) etc .. ,
but that would be a pity performance wise.

References