Skip to main content

Offscreen render using java.awt.headless

3 replies [Last post]
Joined: 2007-02-08

I'm trying to use a Java3D-based library
called VisAD in a headless mode (to generate
OpenGL-rendered images from within a servlet).
I keep running into exceptions.

When using java.awt.headless, getBestScreenDevice()
will throw a HeadlessException, so I get a
GraphicsConfiguration using this snippet of code:

Image te = new File("/tmp/test.jpg") );
Graphics2D g = te.createGraphics();
GraphicsConfiguration config = g.getDeviceConfiguration();

but somehow the GraphicsConfiguration doesn't quite meet what seems to be required. I get a cast exception from
within Java3D.

(a) Does the headless environment work with Java3D?
(b) Should I be creating a GraphicsConfiguration some
other way?
(c) Has any one successfully used Canvas3D's offscreen
rendering capability from within servlets?

Tips and pointers are welcome.


Exception in thread "main" java.lang.ClassCastException
at visad.java3d.VisADCanvasJ3D.(
at visad.java3d.DisplayImplJ3D.initialize(
at visad.java3d.DisplayImplJ3D.(
at visad.java3d.DisplayImplJ3D.(
at visad.java3d.DisplayImplJ3D.(

Reply viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
Joined: 2004-03-17

Java 3D does not work with headless AWT. It requires OpenGL which requires a window system to run.

-- Kevin

Joined: 2007-02-08

Here is some test code that illustrates the problem.
To instantiate a Canvas3D with the offscreen flag,
a non-null GraphicsConfiguration is required.

So, how do I create a GraphicsConfiguration in
headless mode?


[lakshman@cpalmas test]$ cat
import java.awt.image.BufferedImage;
import javax.imageio.ImageIO;
import javax.imageio.ImageWriter;
import java.awt.*;

public class TestOffScreen {

public static GraphicsConfiguration withHead() throws Exception
System.out.println("GraphicsConfiguration based on screen device");
// fails if java.awt.headless=true
return ( GraphicsEnvironment.getLocalGraphicsEnvironment().getDefaultScreenDevice().getBestConfiguration(new GraphicsConfigTemplate3D()) );

public static GraphicsConfiguration withImage() throws Exception
System.out.println("GraphicsConfiguration based on image");
// throws ClassCastException at when Canvas3D is instantiated
BufferedImage template = new File("/tmp/test.jpg") );
Graphics2D g = template.createGraphics();
GraphicsConfiguration config = g.getDeviceConfiguration();
return config;

public static void main(String[] args) throws Exception {

GraphicsConfiguration config = null;
if ( args.length == 0 )
config = withHead();
config = withImage();

if ( config != null )
System.out.println("Got valid graphics configuration");

Canvas3D myCanvas = new Canvas3D( config, true );

Can't use ScreenDevice in headless mode:

[lakshman@cpalmas test]$ java -Djava.awt.headless=true TestOffScreen
GraphicsConfiguration based on screen device
Exception in thread "main" java.awt.HeadlessException
at sun.java2d.HeadlessGraphicsEnvironment.getDefaultScreenDevice(
at TestOffScreen.withHead(
at TestOffScreen.main(

So, how do I create a valid GraphicsConfiguration object in headless mode? Using the image-reading method
in the code snippet doesn't work -- I get a ClassCast
Exception in J3dGraphicsConfig:

[lakshman@cpalmas test]$ java -Djava.awt.headless=true TestOffScreen 2
GraphicsConfiguration based on image
Got valid graphics configuration
Exception in thread "main" java.lang.ClassCastException
at TestOffScreen.main(

Joined: 2006-05-05

Here are some useful resources regarding server side

The second link provides some hints regarding using
headless with AWT. If you want to use hardware OpenGL
accelerated offscreen rendering with headless option,
I will keep my finger crossed. Good Lock!

-- Scott