ImmediateLayer

[GoogleCodeExporter]

Purpose of code changes on this branch:
Implements a layer that draws in "immediate mode". The game provides a callback 
which is executed every frame which renders directly into the framebuffer via a 
Surface interface.

When creating an immediate layer, one has the option of clipping to a bounding 
rectangle (in which case one gets back an ImmediateLayer.Clipped which extends 
ImmedateLayer and implements Layer.HasSize), or one can render with no 
clipping, in which case one gets back an ImmediateLayer which exposes no 
dimensions.

The transform of the immediate layer is taken into account when rendering, and 
additional transformations can be applied as desired via the Surface interface.

Note that using a clipped immediate layer requires the graphics queue to be 
flushed before and after the rendering of the immediate layer. This will 
negatively impact performance, but is unavoidable, as the unclipped rendering 
must be sent to the GPU before SCISSOR_TEST is enabled, and the clipped 
rendering must be sent before SCISSOR_TEST is disabled.

An implementation has been provided for Java, HTML/Canvas, HTML/WebGL, Android 
and iOS. HTML/DOM and Flash both lack immediate-mode rendering capabilities and 
I didn't especially feel like taking the time to "fake it" using an additional 
back buffer. Someone who cares about those backends is welcome to provide 
implementations.

I added tests/core/src/playn/tests/core/ImmediateTest.java to test (and 
demonstrate the use of) ImmediateLayer. I also rewrote the Cute sample to use 
it (but haven't committed, since I didn't want to force Cute to depend on PlayN 
1.1-SNAPSHOT). Naturally, it's faster and uses less memory. Once I ship this, 
we could consider a 1.1 PlayN release that includes this and (incomplete, but 
complete enough to be interesting) iOS support.

Related to the Cute port, I considered passing the frame alpha (from 
Game.paint) down through the render pipeline so that the 
ImmediateLayer.Renderer could have a "void render(Surface surf, float 
frameAlpha)" callback, but I decided that the majority of ImmediateLayer users 
won't care about frameAlpha, and if they do, they can save it in Game.paint and 
then reference it in their callbacks. That's what I did in Cute.

When reviewing my code changes, please focus on:
https://github.com/threerings/playn/commit/3cbda23c5b44f05ba62c9ced3b281a263a92a
fb5

After the review, I'll merge this branch into:
/trunk

Original issue reported on code.google.com by samskiv...@gmail.com on 7 Feb 2012 at 10:50

[GoogleCodeExporter]

For posterity's sake, I'll repeat what I said on the forum -- looks great, and 
thanks for taking care of this.

Original comment by jgw@google.com on 13 Feb 2012 at 9:45

[GoogleCodeExporter]

Original comment by m...@samskivert.com on 22 Apr 2012 at 10:58

• Changed state: Done