Introducing SceneGraph

I haven't written a blog entry since January when I advertised the fledgling Swing Application Framework (JSR-296) project with an uncharacteristically brief item. Work on that kept me busy until summer, when the Java FX juggernaut got underway here at Sun. Since then I've devoted much of my time to leading a project we've called "Scenario" that provides the graphical runtime for Java FX Script. We're now a public project on java.net called scenegraph.dev.java.net . You'll find downloads of the the 0.4.1 version of the Scenario source and binaries and (very) sketchy javadoc on the site. The 0.x version number is intended to convey the fact that the API hasn't stabilized yet. It's sufficient for experimentation and the implementation was robust enough to support a port of the Java FX Script interpreter, which we've showcased with a Scenario version of the FXPad Demo . Obviously, we don't recommend putting anything based on Scenario into production. Not yet.

The code is being made available under the GPLv2 license. Passion about open source licenses is not something I possess so I'll leave the shouting about the implications of this choice to others. Suffice it to say that, per my limited understanding of these matters, you're free to share the code, and in the process of developing it further. We're moving our discussions of the API to the newly minted Scene Graph java.net forum . If you're interested in the project's evolution, that would be a good place to start looking.

There are quite a few engineers working on Scenario, most of whom have made bigger contributions to the new software than I have, and you'll be hearing from them in their own blogs before too long. For now, what I'd like to do is to provide an introduction to the new Java APIs and just one demo. The team has written a whole raft of demos and we'll be opening up a subproject before too long, that contains the entire demo catalog.

Demo

All of the examples that follow are part of a demo, each one occupies a tab. If you press "control-T" after clicking on a demo, you'll get a nice interactive tree view of the scene graph's structure, thanks to Amy Fowler for that! So press the orange button to launch the demo.

Note also: the demo scales the selected example scene to fit. This is done with a small extension to JSGPanel, take a look at the code if you're interested.

Basics, Hello World

A scene graph, really a tree for now, is a data structure you create from leaf nodes that represent visual elements like 2D graphics and Swing components, filter nodes that represent visual state, like 2D transforms and composition, and group nodes that manage a list of children. All nodes are subclasses of SGNode and have a parent node, rectangular bounds, visibility, and support for event dispatching. Leaf nodes extend SGLeaf and have paint/repaint methods similar to AWT/Swing. SGFilter nodes have one child, and SGGroups have a list of them. To display a scene graph you set the scene property of a JSGPanel, and add the panel to a Swing application in the usual way. Here's a simple example:

SGText text = new SGText();
text.setText("Hello World");
JSGPanel panel = new JSGPanel();
panel.setScene(text);
panel.setPreferredSize(new Dimension(640, 480));
// create a JFrame, add the panel to it, etc..
    

One unusual line from the previous example, from a Swing programmer's perspective, is that we've explicitly set the preferred size of the JSGPanel. Although the JSGPanel will compute (and recompute...) a preferred size based on bounds of its scene, it's usually a good idea to define a reasonable fixed preferred size instead. To make the scene slightly more interesting to look at, we can set the SGText node's font and color, turn on antialiasing, and configure the panel's background color:

SGText text = new SGText();
text.setText("Hello World");
text.setFont(new Font("SansSerif", Font.PLAIN, 36));
text.setAntialiasingHint(RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
text.setFillPaint(Color.WHITE);
JSGPanel panel = new JSGPanel();
panel.setBackground(Color.BLACK);
panel.setScene(text);
panel.setPreferredSize(new Dimension(640, 480));
    

More Hello World: Groups and Shapes

Most of the Scenario classes are simple Java Beans. They provide null (no parameters) constructors and mutable properties. The API is intended to be "minimal" in the sense that it exposes the capabilities of the underlying Java 2D and Swing classes but does attempt to substantially simplify or abstract them. Scenario is intended to serve as the basis for higher level abstractions that require a scene graph, notably Java FX Script. For that reason, you may find programming against the Scenario API directly to be a bit tedious. Creating your own abstractions that simplify creating scene graphs is definitely the order of the day.

To add a border to the simple Hello World scene, we'll write a method that takes any scene graph node and puts a garish rounded rectangle border behind it. This example demonstrates using the SGShape leaf node which can render any Java 2D Shape , like lines, arcs, bezier curves, and of course rounded rectangles. Just to highlight the support for both filling and stroking (drawing the outline of) shapes, we'll do both here. The createBorder method creates a red and yellow rounded rectangle that's a little bigger than the node it's given. It returns an SGGroup scene graph node that contains both the original node and the "border".

SGNode createBorder(SGNode node) {
    Rectangle2D nodeR = node.getBounds();
    double borderWidth = 10;
    double x = nodeR.getX() - borderWidth;
    double y = nodeR.getY() - borderWidth;
    double w = nodeR.getWidth() + (2 * borderWidth);
    double h = nodeR.getHeight() + (2 * borderWidth);
    double a = 1.5 * borderWidth;
    SGShape border = new SGShape();
    border.setShape(new RoundRectangle2D.Double(x, y, w, h, a, a));
    border.setFillPaint(new Color(0x660000));
    border.setDrawPaint(new Color(0xFFFF33));
    border.setDrawStroke(new BasicStroke(borderWidth / 2.0));
    border.setMode(SGShape.Mode.STROKE_FILL);
    border.setAntialiasingHint(RenderingHints.VALUE_ANTIALIAS_ON);
    SGGroup borderedNode = new SGGroup();
    borderedNode.add(border);
    borderedNode.add(node);
    return borderedNode;
}
    

Adding a the border doesn't change the code that creates the scene graph very much:

SGText text = new SGText();
text.setText("Hello World");
// same as before ...
panel.setScene(createBorder(text));
    

Rotating Hello World: Transforms

As you can see in the previous example, the SGNode#getBounds() method returns a bounding box for the its node, in the way same way Component#getBounds() does for AWT and Swing components. In AWT and Swing, a component's parent node recursively defines its origin in terms of a translation, which is the value of getParent().getLocation(). Scene graphs are much more flexible than that. The relationship between a child and its parent node can be defined with any 2D affine transformation.

To rotate a scene graph node around a point, you have to assemble a chain of three transforms that: translate the node so that the rotation point is at the origin, rotate the desired amount, translate the node back to its original location. Transforms are created with SGTransform nodes, which are SGFilter subclasses because they have just one child, which is the node the transform is to be applied to. Here's a method that creates such a chain and uses the node's bounds' center as the rotation point:

SGTransform createRotation(SGNode node) {
    Rectangle2D nodeR = node.getBounds();
    double cx = nodeR.getCenterX();
    double cy = nodeR.getCenterY();
    SGTransform toOriginT = SGTransform.createTranslation(-cx, -cy, node);
    SGTransform.Rotate rotateT = SGTransform.createRotation(0.0, toOriginT);
    return SGTransform.createTranslation(cx, cy, rotateT);
}
    

To use the createRotation method we apply it to the node that's going to spin around its center, and then add the returned value to the scene instead of the node itself. The return value is the chain of three transform nodes followed by the original node. To specify a rotation you have to refer to the second SGTransform.Rotate from the chain and change its rotation property:

SGTransform scene = createRotation(node);
SGTransform.Rotate rotateT = (SGTransform.Rotate)scene.getChild();
rotateT.setRotation(...);
    

Images and More Layout

Images can be incorporated in a scene graph with the SGImage node type. To add one to our scene so that it appears to the right of the "Hello World" text, we'll have to create an SGGroup node that contains the text and the image, and then use SGTransform nodes to arrange the group's children along a row. Here's a method that creates such a group:

SGNode createRow(SGNode... nodes) {
    double rowHeight = 0.0;
    for(SGNode node : nodes) {
        rowHeight = Math.max(rowHeight, node.getBounds().getHeight());
    }
    SGGroup row = new SGGroup();
    double x = 0.0;
    double gap = 8.0;
    for(SGNode node : nodes) {        
        Rectangle2D nodeR = node.getBounds();
        double y = (rowHeight - nodeR.getHeight()) / 2.0;
        double dx = x - nodeR.getX();
        double dy = y - nodeR.getY();
        SGTransform xlate = SGTransform.createTranslation(dx, dy, node);
        row.add(xlate);
        x += nodeR.getWidth() + gap;
    }
    return row;
}
    

The code to create the SGImage node and the overall scene looks like this:

SGNode createEarth() {
    BufferedImage image = null; 
    // ... code to load the image file
    SGImage sgImage = new SGImage();
    sgImage.setImage(image);
    return sgImage;
}
// ...
SGNode row = createRow(createHelloWorldText(), createEarth());
SGNode scene = createBorder(row);
JSGPanel panel = new JSGPanel();
panel.setScene(scene);
    

Handling Input

All nodes can handle mouse and keyboard events and the support for doing so is very similar to what AWT/Swing provides. For example to make a node handle mouse events you add an SGMouseListener. SGMouseListener combines the methods from AWT's MouseListener and MouseMotionListener and it adds an SGNode argument to each one. SGKeyListener and SGFocusListener are similar. The source of a scene graph mouse or keyboard event is always a JSGPanel and the additional node argument indicates the node the event was actually dispatched to.

In this example, we've added a mouse listener to the earth node in the scene from the previous example and restored the support for rotating the scene. Dragging the earth with the mouse rotates the scene. Here's the code that sets up the scene and its SGMouseListener:

SGNode earth = createEarth();
SGNode row = createRow(createHelloWorldText(), earth);
SGTransform scene = createRotation(createBorder(row));
final SGTransform.Rotate rotateT = (SGTransform.Rotate)scene.getChild();
SGMouseListener changeRotation = new SGMouseAdapter() {
    @Override public void mouseDragged(MouseEvent e, SGNode node) {
        Rectangle2D r = e.getComponent().getBounds();
        double x = e.getX() - r.getCenterX();
        double y = e.getY() - r.getCenterY();
        rotateT.setRotation(Math.atan2(y, x));
    }
};
earth.addMouseListener(changeRotation);
JSGPanel panel = new JSGPanel();
panel.setScene(scene);
    

Although there's a great deal more to say by way of introducing Scenario, this blog entry has grown long enough that I'd better just take the same tack that Chet did , and declare this "Part 1".

The code for the examples can be found here: http://weblogs.java.net/blog/hansmuller/archive/Intro.java A easy to build version will appear along with the other Scenario demos, later this month.

I've made a prototype of the fledgling JSR-296 API available, it's https://appframework.dev.java.net/. There's a quick overview doc and downloads of the source code, the javadoc, and the AppFramework.jar file. If you're interested in this API, please take a look at the overview, and download the code and then take a look at some of the examples and the javadoc. You can post feedback here or, if you want to participate in the long-term discussion, subscribe to the appframework.dev.java.net "users" mailing list: https://appframework.dev.java.net/servlets/ProjectMailingListList . The users alias is the last one listed.

That's all I really wanted to say. I don't want to make too much of a commotion about this version of the design because there's still quite a bit that remains to be done. I was hoping that this would be a sort-of stealth release: not terribly noticeable, unless you know where to look. On the other hand, I know there are Swing developers who aren't members of the JSR-296 expert group, who'd like to take stock of where this project is going. And I know there are experienced Swing developers out there, some of whom have built their own application frameworks, that would like see how this one measures up. I'd welcome feedback from anyone who's interested and I'll promise to respond promptly, unless you bring up a really difficult issue or a really large number of them. That might take longer.

Note also: the JCP defines a milestone called "Early Draft Review" that means the expert group thinks the spec is complete enough to begin fine tuning. We have not reached that milestone yet.

Having written, by conservative estimates, about a jillion Java Beans classes over the years, I have to say that I'm amazed that we'd seriously consider changing the Java language to trivialize this kind of Java Bean property. It certainly is a property per the spec, a read/write property at that, but - as a Swing developer - it's the kind of property I almost never write. And if repetitive boilerplate is what we're hunting with this language change, then we're shooting at rabbits while a herd of buffalo thunders by. The mighty buffalo of the Java Beans boilerplate animal kingdom are bound properties. They're the kind of properties we write so that our beans can be automatically and dynamically synchronized with a GUI or with each other. As a desktop developer, I almost always write bound properties.

To write a bound property properly you've got to ensure that your class defines or inherits support for a PropertyChangeListener. That's about 20 lines of code just to get started:

class FooBean {
    private final java.beans.PropertyChangeSupport pcs;
    public FooBean () {
	pcs = new PropertyChangeSupport(this);
    }
    public void addPropertyChangeListener(PropertyChangeListener listener) {
        pcs.addPropertyChangeListener(listener);
    }
    public void removePropertyChangeListener(PropertyChangeListener listener) {
        pcs.removePropertyChangeListener(listener);
    }
    public PropertyChangeListener[] getPropertyChangeListeners() {
        return pcs.getPropertyChangeListeners();
    }
    protected void firePropertyChange(String propertyName, Object oldValue, Object newValue) {
        pcs.firePropertyChange(propertyName, oldValue, newValue);
    }
}
    

And then there's the definition of each read/write property which should: check the validity of new values in its set method as well as calling firePropertyChange to notify PropertyChangeListeners, and defensively copy the return value (if necessary) in its get method. I suppose one could concoct syntax that would simplify all of this, at least a little, as well as allowing for read-only/write-only variants. But that's not the proposal I wanted to make here.

If you consider the property keyword proposal in light of Java's origins in the C language, then it's pretty clear what the proposal's proponents are really after: structs. It's not about defining properties, it's about simplifying defining a Java class that's comparable to a struct in the C language. So perhaps the proposal should really focus on allowing one to write classes, not properties. Where this:

struct FooBean { Foo foo; }
    

class FooBean {
    private Foo foo; 
    public Foo getFoo() { return foo; }
    public void setFoo(Foo foo) { this.foo = foo; }
}
    

If you admit that the focus of the property proposal is really adding support for defining structs in Java, then using "->" to refer to struct properties feels like coming home again.

struct Point { int x, y; }
Point p = new Point(); 
p->x = p->y = 0; // oh joy
    

I'm not a language design expert however I would think that I would be among the target developers for Java language feature designed to support properties. In my humble (ha) opinion, the current proposal serves the needs of Java Beans developers poorly by targeting a special case that doesn't warrant language support. Although I would welcome a proposal that also simplified defining bound properties, I would guess that it would be hard to invent syntax that would handle the general case without being obscure. If there is a consituency for the current proposal, I say: give them structs instead.

Javapolis 2006

I spent most of last week at the Javapolis conference in Antwerp Belgium. With nearly 3000 attendees, it's the second biggest Java conference after JavaOne, and it's held in a movie cineplex complex called "Metropolis". The venue delivers large halls, comfortable seats (with beverage caddies!), and dramatic lighting. Half of each enormous movie screen is devoted to a live image of the presenter and the camerawork is quite good, pausing for a dramatic closeup now and then. My laptop wasn't working correctly so I had to turn around periodically, to visually sync up with my slides. That meant that the audience was treated to six linear feet of my balding hemisphere glowing in the klieg lights. I was thankful that everyone put up with that, and also with my raspy voice. I'd managed to pick up a cold the day before leaving, and only hours before I was scheduled to speak, I could do little more than croak and wheeze. Things were somewhat better by the showtime, however from the sound of my voice you might think I'd spent the day smoking heavily and shrieking.

My presentation topic was JSR-296 "Swing Application Framework". If you're interested, there's a copy here. Within a few months you'll find a nicely edited slides-and-video version of the presentation on parleys.com, thanks to Stephan Janssen, the tireless Javapolis organizer. And when it appears, do not miss the finale. As Richard Bair and I finished up a demo of a prototype of the Application Framework in NetBeans, Stephan appeared and asked to interrupt the proceedings for a special announcment. He picked up the microphone and asked a woman who's name I didn't catch to come forward. Sure enough, a tall young blonde woman came to the front, looking nonplussed. After a brief pause, a young man wearing a suit came loping down the aisle and in a moment he was facing the woman and making a declaration of some kind in Dutch. She looked pretty nervous and, not knowing where this was all going, we started feeling a bit anxious too. Until he dropped to one knee and assumed the international marriage proposal position. Then we really started to worry, because here was a situation that could only end really well, or really badly. The woman was crying (uh oh) and smiling (whew!), and then nodding her head, and to everyone's relief, we had a happy betrothal. The couple bounded up the steps to a nice round of applause, and Richard and I tried to remember what it was we'd been talking about.

The Javapolis conference was memorable as always. One evening the organizers arranged for enough french fries and mayonaise to serve 3000 (that's a lot), they showed the new James Bond movie, Mark Fleury performed his keynote dressed up like Flavor Flav, Sun raffled away a Nintendo Wii, the technical sessions were solid, and, mine was interrupted by a proposal of marriage. With a happy ending.

Merry Christmas!

Update: Stephan Janssen has published the video, you'll find it here:
http://www.javapolis.com/confluence/display/JP06/2006/12/22/JavaPolis+20...