1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../style.css" rel="stylesheet" type="text/css"/>
<title>NEWT - JOGL’s High Performance Native Windowing Toolkit</title>
</head>
<body>
<div id="container">
<div id="header">
<div id="slogan">NEWT & JOGL</div>
<div id="logo"><a href="http://jogamp.org/jogl/">OpenGL & JOGL</a></div>
</div>
<div id="menu">
<ul>
<li><a href="http://jogamp.org/">Home</a></li>
<li><a href="../../gluegen/www/">Gluegen</a></li>
<li><a href="../../joal/www/">JOAL</a></li>
<li><a href="../../jocl/www/">JOCL</a></li>
<li><a href="../../jogl/www/">JOGL</a></li>
<li><a href="../../demos/www/">Demos</a></li>
<li><a href="../../wiki/">Wiki</a></li>
<li><a href="../../deployment/jogl-next/javadoc_public/">JavaDoc</a></li>
<li><a href="../../blog/">Blogs</a></li>
<li><a href="../../forum.html">Forums</a></li>
</ul>
</div>
<div id="main">
<div id="text" class="fill">
<h2>NEWT - JOGL’s High Performance Native Windowing Toolkit</h2>
<h4>NEWT Usage</h4>
<p>
Consider the classic demo code
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsES2.java;hb=HEAD">GearsES2.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/GearsES2.java;h=d92d98894acc4cfe42e77ec316858d16d202b5b8;hb=HEAD">v2.0-rc3</a>],
which implements a
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html">GLEventEventListener</a>.</p>
<p>
The simple application
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/newt/TestGearsES2NEWT.java;hb=HEAD">TestGearsES2NEWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/es2/newt/TestGearsES2NEWT.java;h=df86b83d2c3af9efed44d973aac24e678e85cd4c;hb=HEAD">v2.0-rc3</a>]
creates a NEWT
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/newt/opengl/GLWindow.html">GLWindow</a>,
which implements a
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLAutoDrawable.html">GLAutoDrawable</a>
and hence is able to add the demo code.
NEWT’s GLWindow also implements the NEWT <a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/newt/Window.html">Window</a>,
which gives you full control of the native windowing, as shown in the demo.</p>
<p>
Finally we just add our GLWindow to an
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/util/Animator.html">Animator</a> instance,
which renders our demo in it's own rendering thread independent from user input.</p>
<p>
For NEWT’s AWT integration, please read the dedicated section below.
</p>
<h4>NEWT Threading Overview</h4>
<p>NEWT’s event model is pretty simple.<br />
It spawns one Event Dispatch Thread (EDT) for each unique Display which role is to handle:</p>
<ul>
<li> input events </li>
<li> window lifecycle actions (window visibility, resize, .. etc) </li>
<li> <b>not</b> rendering </li>
</ul>
<p>
High performance rendering is achieved without being blocked by input events or vice versa.<br/>
As demonstrated in the above NEWT example, rendering does not disturb or lag user input.<br/>
This gives you fluent animation even for complex models.</p>
<h4>NEWT’s AWT integration and NEWT Applet’s</h4>
<p>
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/newt/awt/NewtCanvasAWT.html">NewtCanvasAWT</a>,
representing an AWT Canvas, allows you to hook a NEWT Window into it.</p>
Since the NewtCanvasAWT is an AWT heavyweight Component, this gives you the ability hook NEWT into an AWT UI.<br/>
<p>
The implementation uses the AWT native JAWT API to reparent the NEWT Window natively into the AWT one<br/>
and hence is even more compatible with JOGL’s GLCanvas implementation.</p>
<p>
This enables us to use both worlds, AWT/Swing UI and decoupled high performance rendering.</p>
<p>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cAWT.java;hb=HEAD">TestParenting01cAWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cAWT.java;h=4477c3f8e8ebc43c91ea90a82af69a5bb0f38091;hb=HEAD">v2.0-rc3</a>]
shows you how to add an GLWindow to an NewtCanvasAWT, which iself is added to an AWT Frame.<br/>
It also shows how the NewtCanvasAWT can be easily removed from the AWT Frame and placed into another AWT Container.<br/>
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.<br/>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cSwingAWT.java;hb=HEAD">TestParenting01cSwingAWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cSwingAWT.java;h=478e00007b14f2d4d14da3d5ccca0500b441ba96;hb=HEAD">v2.0-rc3</a>]
shows the same example using Swing.<br/>
</p>
<p>
Last but not least, the above mechanism can be used to show NEWT Window’s in an AWT Applet.<br/>
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/newt/awt/applet/JOGLNewtApplet1Run.html">JOGLNewtApplet1Run</a>
is an Applet launcher for any
<a href="/deployment/jogamp-next/javadoc/jogl/javadoc/javax/media/opengl/GLEventListener.html">GLEventEventListener</a>
exposing a default constructor.
See it <a href="/deployment/jogamp-next/jogl-test-applets.html"><i>alive</i> here</a>.
</p>
<!---
<a href="">TestParenting01cSwingAWT.java</a>
[<a href="">v2.0-rc3</a>]
-->
<h4>Native Window Reparenting Details</h4>
NEWT's reparenting algorithm only issues a <i>destroy</i> if:
<ul>
<li>Becomes CHILD-Window
<ul>
<li>new parent window is not realized yet,
i.e. parent's window handle is null</li>
<li>forceRecreate</li>
<li>moving to a new incompatible screen/device</li>
</ul></li>
<li>Becomes TOP-Level-Window
<ul>
<li>forceRecreate</li>
</ul></li>
<li>reparenting failed</li>
</ul>
In case <i>destroy</i> is issued, recreation will follow
as soon as the new parent window handle becomes available
or the instant if becoming a top-level window.
<p>
In case <i>destroy</i> must be issued, the hint <i>REPARENT_HINT_BECOMES_VISIBLE</i>
will preserve the GLState at destroy, see below.
</p>
<p>
To avoid <i>destroy</i> <b>and</b> 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 ..
</p>
<h5>Using GLState Preservation</h5>
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 <i>destroy</i> case.
See: GLStateKeeper, GLEventListenerState
Regularly Used in the following use cases:
<ul>
<li>OSX CALayer/Top-Level NEWT reparenting</li>
<li>Android GLState preservation: 'Home Button', 'Rotation' ..</li>
</ul>
<h4>How to pass user input back to the rendering loop ?</h4>
The following example shows you how to use a fifo to pipe events from the EDT (listener) to the rendering loop.
<ul>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting02NEWT.java;hb=HEAD">TestParenting02NEWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting02NEWT.java;h=13aad0c25873a29f8c5df80e71bb76c96c5d4197;hb=HEAD">v2.0-rc3</a>]
</li>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/KeyAction.java;hb=HEAD">KeyAction.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/KeyAction.java;h=3313ec65c59783c67b01cd6bc387a25df943e60f;hb=HEAD">v2.0-rc3</a>]
</li>
</ul>
<p><b>How to inject some GL action to the rendering loop ?</b><br />
Shows you how to inject GL render actions into a GL fifo from another thread.</p>
<ul>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cSwingAWT.java;hb=HEAD">TestParenting01cSwingAWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/TestParenting01cSwingAWT.java;h=478e00007b14f2d4d14da3d5ccca0500b441ba96;hb=HEAD">v2.0-rc3</a>]
</li>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/GLRunnableDummy.java;hb=HEAD">GLRunnableDummy.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/newt/parenting/GLRunnableDummy.java;h=1ca74774b73963ba4e3b20fc3491b0b2f7bfe454;hb=HEAD">v2.0-rc3</a>]
</li>
</ul>
<p><b>AWT agnostic input event listener</b><br />
We also have a way to write AWT agnostic input event listener:</p>
<ul>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/newt/TestGearsNEWT.java;hb=HEAD">TestGearsNEWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/newt/TestGearsNEWT.java;h=4b6f7999a194bf8515d828124239b0acba81fd49;hb=HEAD">v2.0-rc3</a>]
</li>
<li>
<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/awt/TestGearsAWT.java;hb=HEAD">TestGearsAWT.java</a>
[<a href="http://jogamp.org/git/?p=jogl.git;a=blob;f=src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/awt/TestGearsAWT.java;h=8ab641267c8a4e958ccf1709bc07fd050c8a7213;hb=HEAD">v2.0-rc3</a>]
</li>
</ul>
<p>We provide some utilities to make life a bit easier.<br />
These are not really necessary, ie you could write and use your own, sure.</p>
<p>The NEWT threading requirements are easy – they are just <b>none</b> for rendering,<br />
and the input event listener should better not lock the rendering GL context.<br />
Well, they can using <code>GLContext.setSynchronized(true) etc .. </code>,<br />
but that would be a pity performance wise.</p>
<h3>References</h3>
<ul>
<li><a href="/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/newt/package-summary.html">NEWT API Overview</a></li>
</ul>
</div>
</div>
<div id="footer">
<div id="footer_left">
<span>JogAmp.org</span>
by <a href="http://jogamp.org">http://jogamp.org</a>
is licensed under a <br/>
<a href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 License</a>.
</div>
</div>
</div>
</body>
</html>
|
