Michael Bien's Weblog

Java Binding for the OpenCL API

2010-09-10T22:49:42+00:00

I am currently working on Java Binding for the OpenCL API using GlueGen (as used in JOGL, JOAL). The project started as part of my bachelor of CS thesis short after the release of the first OpenCL specification draft and is now fully feature complete with OpenCL 1.1. JOCL is currently in the stabilization phase, a beta release shouldn't be far away.

Overview - How does it work?

JOCL enables applications running on the JVM to use OpenCL for massively parallel, high performance computing tasks, executed on heterogeneous hardware (GPUs, CPUs, FPGAs etc) in a platform independent manner. JOCL consists of two parts, the low level and the high level binding.

The low level bindings (LLB) are automatically generated using the official OpenCL headers as input and provide a high performance, JNI based, 1:1 mapping to the C functions.

This has the following advantages:

reduces maintenance overhead and ensures spec conformance
compiletime JNI bindings are the fastest way to access native libs from the JVM
makes translating OpenCL C code into Java + JOCL very easy (e.g. from books or tutorials)
flexibility and stability: OpenCL libs are loaded dynamically and accessed via function pointers

The hand written high level bindings (HLB) is build on top of LLB and hides most boilerplate code (like object IDs, pointers and resource management) behind easy to use java objects. HLB use direct NIO buffers internally for fast memory transfers between the JVM and the OpenCL implementation and is very GC friendly. Most of the API is designed for method chaining but of course you don't have to use it this way if you don't want to. JOCL also seamlessly integrates with JOGL 2 (both are built and tested together). Just pass the JOGL context as parameter to the JOCL context factory and you will receive a shared context. If you already know OpenCL and Java, HLB should be very intuitive for you.

The project is available on jogamp.org. Please use the mailinglist / forum for feedback or questions and the bugtracker if you experience any issues. The JOCL root repository is located on github, you may also want to take a look at the jocl-demos project. (If the demos are not enough you might also want to take a look at the junit tests)

Screenshots (sourcecode in jocl-demos project):

More regarding OpenGL interoperability and other features in upcoming blog entries.

The following sample shows basic setup, computation and cleanup using the high level APIs.

Hello World or parallel a+b=c


/**
 * Hello Java OpenCL example. Adds all elements of buffer A to buffer B
 * and stores the result in buffer C.
 * Sample was inspired by the Nvidia VectorAdd example written in C/C++
 * which is bundled in the Nvidia OpenCL SDK.
 * @author Michael Bien
 */
public class HelloJOCL {

    public static void main(String[] args) throws IOException {
        // Length of arrays to process (arbitrary number)
        int elementCount = 11444777;
        // Local work size dimensions
        int localWorkSize = 256;
        // rounded up to the nearest multiple of the localWorkSize
        int globalWorkSize = roundUp(localWorkSize, elementCount);

        // setup
        CLContext context = CLContext.create();

        CLProgram program = context.createProgram(
                       HelloJOCL.class.getResourceAsStream("VectorAdd.cl")
                                 ).build();

        CLBuffer<FloatBuffer> clBufferA =
                       context.createFloatBuffer(globalWorkSize, READ_ONLY);
        CLBuffer<FloatBuffer> clBufferB =
                       context.createFloatBuffer(globalWorkSize, READ_ONLY);
        CLBuffer<FloatBuffer> clBufferC =
                       context.createFloatBuffer(globalWorkSize, WRITE_ONLY);

        out.println("used device memory: "
            + (clBufferA.getSize()+clBufferB.getSize()+clBufferC.getSize())/1000000 +"MB");

        // fill read buffers with random numbers (just to have test data).
        fillBuffer(clBufferA.getBuffer(), 12345);
        fillBuffer(clBufferB.getBuffer(), 67890);

        // get a reference to the kernel functon with the name 'VectorAdd'
        // and map the buffers to its input parameters.
        CLKernel kernel = program.createCLKernel("VectorAdd");
        kernel.putArgs(clBufferA, clBufferB, clBufferC).putArg(elementCount);

        // create command queue on fastest device.
        CLCommandQueue queue = context.getMaxFlopsDevice().createCommandQueue();

        // asynchronous write to GPU device,
        // blocking read later to get the computed results back.
        long time = nanoTime();
        queue.putWriteBuffer(clBufferA, false)
             .putWriteBuffer(clBufferB, false)
             .put1DRangeKernel(kernel, 0, globalWorkSize, localWorkSize)
             .putReadBuffer(clBufferC, true);
        time = nanoTime() - time;

        // cleanup all resources associated with this context.
        context.release();

        // print first few elements of the resulting buffer to the console.
        out.println("a+b=c results snapshot: ");
        for(int i = 0; i < 10; i++)
            out.print(clBufferC.getBuffer().get() + ", ");
        out.println("...; " + clBufferC.getBuffer().remaining() + " more");

        out.println("computation took: "+(time/1000000)+"ms");

    }

    private static final void fillBuffer(FloatBuffer buffer, int seed) {
        Random rnd = new Random(seed);
        while(buffer.remaining() != 0)
            buffer.put(rnd.nextFloat()*100);
        buffer.rewind();
    }

    private static final int roundUp(int groupSize, int globalSize) {
        int r = globalSize % groupSize;
        if (r == 0) {
            return globalSize;
        } else {
            return globalSize + groupSize - r;
        }
    }

}

VectorAdd.cl


    // OpenCL Kernel Function for element by element vector addition
    kernel void VectorAdd(global const float* a,
                          global const float* b,
                          global float* c, int numElements) {

        // get index into global data array
        int iGID = get_global_id(0);

        // bound check (equivalent to the limit on a 'for' loop)
        if (iGID >= numElements)  {
            return;
        }

        // add the vector elements
        c[iGID] = a[iGID] + b[iGID];
    }

New Getting Started with JOGL 2 tutorials

2010-09-04T00:22:38+00:00

Thanks to Justin Stoecker, computer science graduate student at the University of Miami, JOGL gets a new set of getting started tutorials:

JOGL, or Java Bindings for OpenGL, allows Java programs to access the OpenGL API for graphics programming. The graphics code in JOGL programs will look almost identical to that found in C or C++ OpenGL programs, as the API is automatically generated from C header files. This is one of the greatest strengths of JOGL, as it is quite easy to port OpenGL programs written in C or C++ to JOGL; learning JOGL is essentially learning OpenGL[...]

Tutorials:

Thanks Justin!

JOGL 2 - Composeable Pipline

2010-08-25T15:27:31+00:00

JOGL provides a feature called 'composeable pipeline' which can be quite useful in some situations. It enables you to put additional delegating layers between your java application and the OpenGL driver. A few usecases could be:

performance metrics
logging, debugging or diagnostics
to ignore specific function calls

It is very easy to set up. Just put this line into your code and the DebugGL layer will throw a GLException as soon an error occurs (you want this usually when you are developing the software).


    public void init(GLAutoDrawable drawable) {
        // wrap composeable pipeline in a Debug utility, all OpenGL error codes are automatically
        // converted to GLExceptions as soon as they appear
        drawable.setGL(new DebugGL3(drawable.getGL().getGL3()));
        //..
    }

Another predefined layer is TraceGL which intercepts all OpenGL calls and prints them to an output stream.


        drawable.setGL(new TraceGL3(drawable.getGL().getGL3(), System.out));

You have won the Jackpot (3.0)

2010-06-03T23:16:27+00:00

You might remember the project called Jackpot which came out of SunLabs and had James Gosling involved with. It was basically a way to declaratively define refactoring rules, allowing for example, to migrate client code between incompatible third party libraries. The project has been integrated into NetBeans as the IDE's refactoring engine since then. NetBeans 6.9 uses Jackpot for most of the in-code hints and code inspections for instance.

There were various ways to specify the transformation rules, e.g. via a special declarative language or even in Annotations directly in the library-code which would cause incompatibilities (or e.g in conjunction with @Deprecated).

Jan Lahoda recently started with the efforts to make the project usable as standalone tool again. Jackpot 3.0 is available via bitbucket for early adopters.

Back to the Future

I used this opportunity to test jackpotc (the jackpot compiler) with JOGL. What I tired is to provide transformations which transform old JOGL 1.1.1 code into latest JOGL 2 compatible client code. So firstly thanks to Jan for fixing all the bugs we ran into while testing the experimental command line compiler.

The first thing I did was to transform the code to properly use OpenGL profiles. As testcode i will use the famous Gears OpenGL demo as example (but those kind of automatic transformations will only pay of if you use them on large codebases). Since it was written against JOGL 1.1.1 it can only use OpenGL up to version 2.x, which means we can simply use the GL2 profile.

Transformation Rules


'JOGL2 API change: javax.media.opengl.GL -> javax.media.opengl.GL2':
javax.media.opengl.GL=>javax.media.opengl.GL2;;

'JOGL2 API change: new javax.media.opengl.GLCapabilities(javax.media.opengl.GLProfile)':
new javax.media.opengl.GLCapabilities()=>
new javax.media.opengl.GLCapabilities(javax.media.opengl.GLProfile.get(javax.media.opengl.GLProfile.GL2));;

'JOGL2 API change: GL gl = drawable.getGL() -> GL2 gl = drawable.getGL().getGL2()':
$d.getGL() :: $d instanceof javax.media.opengl.GLAutoDrawable=>
$d.getGL().getGL2();;

Just by looking at the transformation rules you can easily see that it is far more powerful than any simple text replacement could be. Jackpot uses javac and can therefore work with full qualified names, instanceof and more. It will also correctly fix imports for you (there is currently a open bug in this area). The quotes are used as description string which will be printed when jackpotc runs on every code occurrence which applies to that rule.

Invoking Jackpot


jackpotc -sourcepath $SRC -cp $LIBS -d $OUTPUT\
         -Ajackpot30_extra_hints=./jogl1Tojogl2.hint $FILESET

$LIBS must contain both library versions, JOGL 1.1.1 and JOGL 2. This is not optimal but it will probably work in most situations to just use both without thinking about an particular ordering or the need to do multiple iterations.

Results

If everything runs fine the console output should look like the sample below for each transformation which applies for the given $FILESET:


./test/oldgears/src/jogl111/gears/Gears.java:54: warning: JOGL2 API change: GL gl = drawable.getGL() -> GL2 gl = drawable.getGL().getGL2()
    GL gl = drawable.getGL();
...

The final result is a diff patch located in $OUTPUT/META_INF/upgrade called upgrade.diff containing the complete changeset for the transformation. Now the only thing you have to do is to review the changes and apply them.


@@ -51,7 +51,7 @@
     // Use debug pipeline
     // drawable.setGL(new DebugGL(drawable.getGL()));
 
-    GL gl = drawable.getGL();
+    GL2 gl = drawable.getGL().getGL2();
...

You can find the complete demo and all ready-to-run shellscripts in the tools/jackpotc folder inside JOGL's git repository. The classic JOGL 2 Gears demo can be found in form of an applet here (uses latest hudson builds... can be unstable).

happy coding!

- - - -
The JOGL repositories are open for contributions. If you would like to add some rules or fix other things... feel free to fork the repos on github and commit to them. (same rule applies for all JogAmp Projects like JOCL, JOAL, GlueGen... etc)

JogAmp at SIGGRAPH 2010

2010-05-23T21:17:07+00:00

The JogAmp team will be present at SIGGRAPH this year:

3D & Multimedia Across Platforms and Devices Using JOGL
Tuesday, 27 July | 4:00 PM - 6:00 PM

This session discusses the features, contributions, and future of OpenGL, OpenCL, and OpenMax
across devices and OS exposed on top of Java using the JogAmp open-source libraries.

link to Session

hope to meet you there.

about JogAmp.
JogAmp is the home of high performance Java libraries for 3D Graphics, Multimedia and Processing. JogAmp consists currently of the projects JOGL, JOCL and JOAL which provide cross platform language bindings to the OpenGL, OpenCL, OpenAL and OpenMAX APIs.

- - - -
(yes i know i should start bogging again :))

JOGL 2 - OpenGL Profiles explained

2009-08-22T20:20:41+00:00

June 16 2010, updated blogpost: OpenGL 4

JOGL 2 supports several OpenGL Profiles. In this blog entry I try to explain what profiles are and why they are needed.

History

SGI released the first OpenGL specification 1992. Since this point OpenGL 1.x constantly evolved (under the ARB and later Khronos Group) by adding new functions to the core API. This went well until programmable graphics hardware became mainstream and shaders became suddenly more flexible and efficient as the generic fixed function pipeline.

OpenGL 2.x was the last version in which you could freely mix the fixed function pipeline with the programmable pipeline (as a core feature).

With the release of OpenGL 3.0 the whole fixed function pipeline has been deprecated but you could still use it if you haven't requested a forward compatible context.

OpenGL 3.1 and 3.2 removed most deprecated functionality from core specification, however some implementations (e.g. Nvidia drivers) still allow to get them back via an optional compatibility extension. Since 3.1 was the first release which broke compatibility, it is often seen as major OpenGL 3 release.

JOGL 2 (JSR 231)

JOGL 1.1.1 lived in the timeframe up to OpenGL 3.0 which made it easy to stay in sync with the spec. To be able to solve the issue with the deprecation of functionality, JOGL 2 (JSR maintenance release) introduces an abstraction of the original OpenGL versioning called Profile. Profiles allow Java applications to be written in a way which allows compatibility with multiple OpenGL versions at the same time. Since OpenGL ES (GL for embedded systems) has overlapping functionality with OpenGL itself it opened the opportunity to add even Profiles which bridge desktop and embedded implementations. The class diagram below shows the dependencies between all available Profiles.

Before you start writing a JOGL application you will have to decide first which GLProfile you want to use. The code snippet below lists all currently supported profiles (extracted from GLProfile).

Current list of supported profiles and their mapping to the implementation versions


    /** The desktop OpenGL compatibility profile 4.x, with x >= 0, ie GL2 plus GL4.

        bc stands for backward compatibility. */
    public static final String GL4bc = "GL4bc";

    /** The desktop OpenGL core profile 4.x, with x >= 0 */
    public static final String GL4   = "GL4";

    /** The desktop OpenGL compatibility profile 3.x, with x >= 1, ie GL2 plus GL3.

        bc stands for backward compatibility. */
    public static final String GL3bc = "GL3bc";

    /** The desktop OpenGL core profile 3.x, with x >= 1 */
    public static final String GL3   = "GL3";

    /** The desktop OpenGL profile 1.x up to 3.0 */
    public static final String GL2   = "GL2";

    /** The embedded OpenGL profile ES 1.x, with x >= 0 */
    public static final String GLES1 = "GLES1";

    /** The embedded OpenGL profile ES 2.x, with x >= 0 */
    public static final String GLES2 = "GLES2";

    /** The intersection of the desktop GL2 and embedded ES1 profile */
    public static final String GL2ES1 = "GL2ES1";

    /** The intersection of the desktop GL3, GL2 and embedded ES2 profile */
    public static final String GL2ES2 = "GL2ES2";

    /** The intersection of the desktop GL3 and GL2 profile */
    public static final String GL2GL3 = "GL2GL3";

Note: GL2 Profile supports OpenGL up to version 3.0 (included) - this is not a bug: OpenGL 3.1 was the big game changer

The next two code snippets show the basic steps how to set up OpenGL with JOGL 2.

Context creation


        //create a profile, in this case OpenGL 3.1 or later
        GLProfile profile = GLProfile.get(GLProfile.GL3);
        
        //configure context
        GLCapabilities capabilities = new GLCapabilities(profile);
        capabilities.setNumSamples(2); // enable anti aliasing - just as a example
        capabilities.setSampleBuffers(true);
        
        //initialize a GLDrawable of your choice
        GLCanvas canvas = new GLCanvas(capabilities);

        //register GLEventListener
        canvas.addGLEventListener(...);
        //... (start rendering thread -> start rendering...)

Rendering


    public void display(GLAutoDrawable drawable) {
        GL3 gl = drawable.getGL().getGL3();
        gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT);
        //.. render something
    }

Summary

Profiles make JOGL 2 very flexible and allow it to build modular and portable applications. For instance part A of an application can be written against the GL2ES2 interface and part B (which is more hardware specific) against the GL3 interface. This would in theory allow to reuse A in an embedded application and B could e.g. disable itself on old desktop hardware which runs only OpenGL 2.x or fall back to a GL2 implementation.

More information can be found on JogAmp.org (direct link to javadoc)

The next release of the OpenGL Pack for NetBeans will fully support JOGL 2. Beta builds can be found here (builds contain JOGL2 beta5):

NetBeans OpenGL Pack 0.5.5 released

2009-06-29T18:58:43+00:00

The NetBeans 6.7 compatible OpenGL Pack has been updated to version 0.5.5 and is now available on the plugin portal also. The current release is feature compatible with 0.5.4 (release notes) only JOGL and project webstart extensions have been updated to JOGL 1.1.1a security update.

OpenGL Pack 0.5.4 now ready for NetBeans 6.7

2009-06-14T20:38:23+00:00

NetBeans OpenGL Pack 0.5.4 is now ready to be used in the upcoming NetBeans 6.7 release, currently as rc2 available.

It wasn't sure if we would be able to ship the GLSL editor in this release since NetBeans 6.7 changed the editor APIs once again. But fortunately the P1 bug was fixed in time and we (and apparently many others, thanks for voting!) can keep using the Generic Language Framework (GLF aka Schlieman) - at least for now since GLF it is now a deprecated/unsupported module.

Build 0.5.4 will break compatibility with NB 6.5. The latest and also all other releases can be downloaded on the project page. I will wait with the upload to the plugin portal until NetBeans 6.7 final is released.

Features/Enhancements:

Anyway. Not much changed since the last release. The most important point is probably that the GLWorker used internally for tasks like shader compilation or capabilities viewer is now more stable on systems which do software rendering (e.g Mesa GL).

I added also an experimental feature which lets you define GLSL shader dependencies similar to java imports.

It is very common in GLSL to reuse code by simple concatenation of files. For example a set of independent shaders can reuse a code fragment defining some generic mathematical functions if the fragment has been concatenated to the top of all shaders which make use of the functions. Editing those kind of shaders would produce compilation errors without a way to inform the editor about those dependencies.

For example the following shader uses the function light() of PerPixelLight.frag by inserting the file ./PerPixelLight.frag at the position of the //import statement.

PerPixelLight.frag


vec4 light(void) {
    // insert fancy light calculation here
}

PlanetShader.frag


//import PerPixelLight.frag

uniform samplerCube cubemap;
varying vec3 vertex;

void main (void) {
    //Cubemap
    gl_FragColor = vec4(textureCube(cubemap, vertex)) * light();
}

When you compile a shader with dependencies you should see something like that in the output window:

All dependencies are listed in the compiler log and even the line numbers of the compiler warnings are translated back to the code fragments, which lets you jump via hyperlink directly to the annotated files.

Just a warning: Please don't define cyclic dependencies, however double imports should work in theory (have I mentioned it is experimental? ;))

Happy coding!

NetBeans OpenGL Pack #2 in most popular plugins ranking

2009-05-19T20:50:12+00:00

Since I haven't bloged for a long time about the OpenGL Pack, here are some notes for the last two update releases.

Beside updates and fixes the only new feature I added is the OpenGL Quicksearch. It uses the NetBeans 6.5 Quicksearch functionality (similar to ctrl + 3 in eclipse) and searches through several OpenGL resources.

currently are five resources available for search:

OpenGL SDK
OpenGL SDK Extension Registry
Nvidia Extensions
ATI/AMD Extensions
JOGL sources (only when JOGL module installed and used in at least one opened project)

power users can restrict the search to a category with the following prefixes ([prefix space] searchstring (space searchstring)*):
gl for GL SDK, ext for GL extensions, nv for Nvidia extensions, ati for ATI/AMD Extensions.

Pictures featuring: Form Designer sample project, GL Quicksearch, updated GLSL 1.3 editor

Changes in 0.5.3:

Java Applet and Webstart support
OpenGL Quicksearch
GLSL editor updated to support GLSL 1.3 (OpenGL 3.0 spec)
two new NetBeans Form Designer sample JOGL projects
NetBeans 6.5 and JDK6 are the new minimum requirements

Changes in 0.5.2 since last release:

JOGL distribution has been updated to version 1.1.1
GLSL linker now does not stop linking shaders on compiler warnings
the pack should now correctly deploy JOGL and GlueGen's native libraries on all supported platforms (64bit bug)

To download the pack, please visit the plugin portal.

As always, please use the user mailing list for feedback and the issue tracker for bug reports on the project page.

- - - - -

BTW the pack recenty reached the 36k downloads milestone which makes it to the #2 in the most popular plugins category of the plugin portal ;)

NetBeans OpenGL Pack 0.5.1 released

2008-04-12T15:31:45+00:00

The NetBeans OpenGL Pack 0.5.1 has been released. This is a small bugfix release with no major features added.

Changes since last release:

updated JOGL distribution to v1.1.1rc8
updated JOGL demos (added gears Applet demo)
added JOGL API support module for doc and source integration
webstart support for JOGL project templates (just enable it in the project properties)
improved JOGL deployment code (fixed some issues on 64bit systems)
bug fixes

To download the pack please visit the plugin portal page.

The OpenGL pack will be soon available via plugin portal update center (Tools | Plugins). This will make our old "NetBeans OpenGL Pack update center" obsolete (and improve the download speed!). However, we will use the old update center for experimental not final releases in future.

As always, please use the user mailing list for feedback and the issue tracker for bug reports on the project page.

-------

Write once run everywhere [1][2][3][4][5][6] - seems like the platform agnostic JOGL deployment is working ;)

Pictures of my old 3D Engine in Java

2007-12-30T18:35:36+00:00

Here are some screenshots of my 3D Engine (codename Metaverse) I made a few years ago (click to enlarge). It is written in Java and uses JOGL (JSR 231) as OpenGL binding and JInput to access the controllers.

These shots show the real time lighting and water rendering capabilities. They also show that you are the whole time on a real 3D planet (codename potato ;) ).

The next shows a 'test vehicle' to test model loading, animation, physics and collision detection of the Engine. You can use this vehicle to explore the planet - it makes even a lot of fun to drive through rough terrain and try to survive jumps from steep hills ;). The other screenshot shows the planet as wireframe.

The last two show the continuous triangulation of the terrain mesh and the space subdivision into a quad-tree (used for fast frustum culling and physics). The viewer is configured to be located inside the river bed.

You think that Java for 3D Graphics is like a penguin in hell? If you follow some rules to prevent stop the world garbage collections (full GCs) and prevent calls through the JNI where possible you can reach with the server (hotspot compiler) JVM performance comparable to C++ code.

The rendering performance is quite good. Even fast fly overs are rendered with 60+ fps. If the camera stays still the renderer reaches 200+ fps on my notebook (ATI X1600).

I have currently no time to continue with this project but if I think back how fun it was to work on that engine I would love to start hacking again immediately ;).