You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: core/README.md
+24-24Lines changed: 24 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,10 @@ We've removed `Applet` as the base class for `PApplet` and have redone the entir
6
6
7
7
8
8
#### Why?
9
-
1. The changes improve performance--greatly, in some cases--and reduce flicker and quirkiness in others. Using AWT objects like `Applet` (which subclasses `Component`) cause (sometimes major) performance restrictions or other visual glitches like flicker.
9
+
1. The changes improve performance--greatly, in some cases--and reduce flicker and quirkiness in others. Using AWT objects like `Applet` (which subclasses `Component`) cause (sometimes major) performance restrictions or other visual glitches like flicker.
10
10
2. Without making these changes, the code to mitigate the issues from #1 is very difficult to debug and make work properly across the many platforms we support: Macs, Macs with retina displays, Windows 7, Windows 8, 32- and 64-bit machines, Linux who-knows-what, and so on.
11
11
3. The design of `core` is 13 years old, and the graphics features available (OpenGL, `VolatileImage`, `BufferStrategy`, etc) have changed drastically since then. I've papered over these changes and done my best to keep performance on-pace so that we don't break a lot of old code (or libraries), but now is the time for a clean break.
12
-
4. With the death of applets, keeping the `Applet` base class is anachronistic (in addition to hindering performance). However, we're keeping the name `PApplet` because with any luck, these changes will only require a recompile of any sketch (or library) code.
12
+
4. With the death of applets, keeping the `Applet` base class is anachronistic (in addition to hindering performance). However, we're keeping the name `PApplet` because with any luck, these changes will only require a recompile of any sketch (or library) code.
13
13
14
14
15
15
#### What else?
@@ -20,17 +20,17 @@ We've removed `Applet` as the base class for `PApplet` and have redone the entir
20
20
5. In 3.0a2 we changed the OS X version to use Apple's "official" full screen mode. With this came a dorky animation and the inability to span multiple screens. We've rolled that back because of the latter, though the former was also a consideration.
21
21
22
22
23
-
#### But what about...?
23
+
#### But what about...?
24
24
25
25
We're still determining how much code we're willing to break due to API changes. Stay tuned.
26
26
27
27
28
28
#### Integration with Java applications
29
-
One downside of these changes is that you'll no longer be able to just drop a Processing sketch into other Java code, because `PApplet` will no longer subclass `Applet` (and therefore, `Component`). This is a huge downside for a tiny number of users.
29
+
One downside of these changes is that you'll no longer be able to just drop a Processing sketch into other Java code, because `PApplet` will no longer subclass `Applet` (and therefore, `Component`). This is a huge downside for a tiny number of users.
30
30
31
-
Making it a generic `Component`, however, means that we cannot improve performance, due to the cross-platform mess of Java's outdated (and somewhat unsuspported) AWT.
31
+
Making it a generic `Component`, however, means that we cannot improve performance, due to the cross-platform mess of Java's outdated (and somewhat unsuspported) AWT.
32
32
33
-
In 3.0 alpha 6, the `getCanvas()` method (called`getComponent()` in alpha 7) provided a way to get an object to be embedded, but it looks like we'll have to move in another direction. At the present time, it looks like it'll be necessary to create a separate `PComponent` or `PCanvas` class that can be used, but it's not clear how that will work. We'll have this sorted out by the final release of 3.0.
33
+
In 3.0 alpha 6, the `getCanvas()` method (called`getComponent()` in alpha 7) provided a way to get an object to be embedded, but it looks like we'll have to move in another direction. At the present time, it looks like it'll be necessary to create a separate `PComponent` or `PCanvas` class that can be used, but it's not clear how that will work. We'll have this sorted out by the final release of 3.0.
34
34
35
35
This is one of many unfortunate tradeoffs I'm trying to sort through as we try to remove significant barriers to performance caused by the design of Java's AWT, while also supporting features (like embedding) that we've spent so much time supporting in the past.
36
36
@@ -41,10 +41,10 @@ Prior to Processing 3, dark magic was used to make the `size()` command work. Th
41
41
*`setup()` would run, and if the renderer changed, the sketch would throw an exception causing things to restart (re-calling the `setup()` method)
42
42
* The previous step gave fits to any other variants of Processing (like Python or Ruby or Scala)
43
43
44
-
We had a tricky, stuttery situation where some things would happen automatically, other things would be delayed slightly.
45
-
In the Android version of Processing, these methods weren't possible, so we enhanced the preprocessor to parse the `size()` command used in the sketch and create methods called `sketchWidth()` and `sketchHeight()` and so on, that returned the values found in `setup()`.
44
+
We had a tricky, stuttery situation where some things would happen automatically, other things would be delayed slightly.
45
+
In the Android version of Processing, these methods weren't possible, so we enhanced the preprocessor to parse the `size()` command used in the sketch and create methods called `sketchWidth()` and `sketchHeight()` and so on, that returned the values found in `setup()`.
46
46
47
-
In Processing 3, we've moved in a different direction. A new method called `settings()` has been introduced. When running inside the PDE, commands like `size()`, `fullScreen()`, `pixelDensity()`, and `smooth()` are all moved to the `settings()` method, which is called once, before `setup()`. Those are the only methods that can be called inside `settings()`. When outside the PDE (i.e. using Eclipse), you'll need to move those methods to `settings()` yourself.
47
+
In Processing 3, we've moved in a different direction. A new method called `settings()` has been introduced. When running inside the PDE, commands like `size()`, `fullScreen()`, `pixelDensity()`, and `smooth()` are all moved to the `settings()` method, which is called once, before `setup()`. Those are the only methods that can be called inside `settings()`. When outside the PDE (i.e. using Eclipse), you'll need to move those methods to `settings()` yourself.
48
48
49
49
50
50
#### Offscreen rendering
@@ -56,42 +56,42 @@ Documentation is on its way, see [here](https://github.com/processing/processing
56
56
57
57
58
58
#### The Event Dispatch Thread
59
-
The source has gone back and forth between putting all AWT (and Swing, if any) calls on the [EDT](https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html). Per Oracle's statements in Java's documentation, this is best practice (at least for Swing; for AWT it's not clear). However, we've gone back and forth several times as to whether it's necessary or worthwhile.
59
+
The source has gone back and forth between putting all AWT (and Swing, if any) calls on the [EDT](https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html). Per Oracle's statements in Java's documentation, this is best practice (at least for Swing; for AWT it's not clear). However, we've gone back and forth several times as to whether it's necessary or worthwhile.
60
60
Actual rendering in the default renderer happens off the EDT, but the EDT is used to blit the image to the screen (or resize windows, etc). By moving to the EDT, we're looking for more consistent cross-platform results. In practice, results are either mixed or not there.
61
61
62
62
63
-
## OpenGL
63
+
## OpenGL
64
64
65
65
And now, for something completely different.
66
66
67
67
### Changes from 2.x
68
68
69
-
Any code that uses `javax.media.opengl` in imports should replace that `com.jogamp.opengl`. I guess the JOGL folks are fully on their own w/o Oracle/Sun support.
69
+
Any code that uses `javax.media.opengl` in imports should replace that `com.jogamp.opengl`. I guess the JOGL folks are fully on their own w/o Oracle/Sun support.
70
70
71
-
### NEWT
71
+
### NEWT
72
72
73
73
NEWT was written by the JOGL guys so that they could avoid AWT altogether. The outdated/outmoded AWT makes a lot of assumptions that make implementation of GL a mess and causes performance trouble. This is a big part of the rendering changes that I’ve been making in 3—that we’re moving away from AWT as much as possible so that we don’t have performance problems. In the GL case, AWT causes some stuttering and lowered frame rates. We can get rid of those by dropping Applet, Component, and Canvas, and switching to NEWT’s windowing mechanism.
74
74
75
75
76
76
### JOGL vs LWJGL
77
77
78
-
During the alpha 6, 7, and 8 release process we did some juggling with what OpenGL library we should use.
78
+
During the alpha 6, 7, and 8 release process we did some juggling with what OpenGL library we should use.
79
79
80
80
The short version of how it played out (written 15 May 2015)
81
81
* JOGL had some major bugs and development seemed to have stopped (summer/fall 2014)
82
82
*@codeanticode had been trying out LWJGL2 to see how it fared (last fall 2014)
83
83
* The LWJGL project has moved all their development effort to LWJGL3 (since then)
84
84
* Andrés spent the week rewriting OpenGL to use LWJGL3
85
-
* LWJGL3 is simply too unstable for us to use, would require major reworking of PApplet to remove *all* uses of AWT, and they seem to be still struggling with many fundamental issues (this week)
86
-
* Andrés went back to JOGL (last 48 hours) to find that many bugs had been fixed and development was continuing.
85
+
* LWJGL3 is simply too unstable for us to use, would require major reworking of PApplet to remove *all* uses of AWT, and they seem to be still struggling with many fundamental issues (this week)
86
+
* Andrés went back to JOGL (last 48 hours) to find that many bugs had been fixed and development was continuing.
87
87
* For 3.0a8, we dropped LWJGL since JOGL is performing much better, and we're 99% sure that's the final decision for 3.0 (yesterday).
88
88
89
89
It looks like LWJGL3 will be a nice game-centric platform (full screen, affordances for game input/behavior) in the coming months, but the direction they're having to go with 3 means they're moving further away from what we need in Processing with something *slightly* more general.
90
90
91
91
LWJGL and JOGL are both great projects and we're thankful for all the work that they put in, and our own experience with Processing means that we couldn't be more sympathetic to the difficulty they face in maintaining their cross-platform, cross-chipset, cross-everything code. Like Processing, both projects are open source and created by volunteers who give their work away for free. We're enormously appreciative of their efforts.
92
92
93
93
94
-
## JavaFX
94
+
## JavaFX
95
95
96
96
Similarly to the NEWT situation in JOGL described above, we’ve hit the upper bound of what we can do on performance in Java2D as well. The graphics engineers from the Java team seem to have all moved to JavaFX for the last few years, perhaps because AWT is a dead end. So… I’ve started doing the JavaFX port so that we can drop even more of the AWT code.
97
97
@@ -102,9 +102,9 @@ We hope to make JavaFX the default renderer instead of Java2D. With any luck, we
102
102
103
103
## Whither AWT
104
104
105
-
Run away from the AWT. All of our focus is on the OpenGL and JavaFX rendering engines, neither of which use AWT. Even the (currently) default `PGraphicsJava2D` renderer will be de-emphasized (though not removed) in the final 3.0.
105
+
Run away from the AWT. All of our focus is on the OpenGL and JavaFX rendering engines, neither of which use AWT. Even the (currently) default `PGraphicsJava2D` renderer will be de-emphasized (though not removed) in the final 3.0.
106
106
107
-
* * *
107
+
* * *
108
108
109
109
# The Mess
110
110
@@ -126,11 +126,11 @@ The rest of this document are my notes while I'm making changes.
126
126
6. renderer that draws to screen (Java2D) or not (PDF)
127
127
7. OpenGL or not
128
128
129
-
resize events:
129
+
resize events:
130
130
Frame > Canvas > PGraphics > PApplet
131
131
user-driven Frame resize events follow that order
132
132
all resize events happen on the surface
133
-
applet sends message to the surface, which notifies the renderer itself
133
+
sketch sends message to the surface, which notifies the renderer itself
134
134
resize of component is handled in thread-safe way from PSurface
135
135
136
136
PApplet.size() calls setSize() in PSurface, and in surface:
@@ -152,7 +152,7 @@ inside main, will know the screen that's being used for the app
152
152
#### Questions/To Do
153
153
- change size() command to check through renderer constants and give better error message when using one of the built-in renderers
154
154
- bad idea, or worst idea, to have 'surface' var in PGraphics?
155
-
- move getFontRenderContext(font) to PApplet? surface? elsewhere?
155
+
- move getFontRenderContext(font) to PApplet? surface? elsewhere?
156
156
_ do we need canDraw() anymore?
157
157
- Can we remove while() loop that waits until defaultSize is set false?
158
158
- Does init() need to go away, because it's not going to work in any other setting? Because a surface must first be created, the init() method on its own will be a mess.
@@ -165,10 +165,10 @@ _ do we need canDraw() anymore?
165
165
- do we need sketchOutputPath() and sketchOutputStream()?
166
166
167
167
#### Removed functions (not final, just notes)
168
-
param()
168
+
param()
169
169
the old awt event handlers (they were a warning in 2.x)
170
170
PGraphics.requestDraw(), because renderers now have their own threads
171
171
PGraphics.setFrameRate removed, added to PSurface
172
172
requires 1.7.. uses revalidate() method
173
-
destroy() (only called by applet? calls dispose())
173
+
destroy() (only called by Applet? calls dispose())
0 commit comments