Z's Simple OpenCL Binding for Java

zcl is a Java binding for OpenCL 2.1. The goal of the design was to create a small and direct binding to OpenCL whilst maintaining `javaness' and a clean and type-safe object orientated interface.

A side goal of the project was to explore Java to native binding mechanisms ``by hand'' rather than scripts and automation.

The API closely follows OpenCL and has 100% coverage and so general OpenCL programming resources should be applicable. All of the header constants are defined in au.notzed.zcl.CL which when imported statically allow direct use as if it were C.

For further details see the README and javadocs.

Status

As of 1.0 this has been converted to a Java 11 modular project. But it should be possible to build with Java 8 with some minor changes to the makefiles.

This is still more or leass beta as I haven't been using it much. It's pretty easy to hack on to fix. I think it's much nicer to use than pretty much any other OpenCL binding.

Native kernels written in Java are supported. As is garbage collection and a lambda interface.

The only 'supported' platform is GNU/amd64, but a build script is provided for native code via mingw32.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Note that this is not the lesser license, the full source-code must accompany any programme which utilises this library.

I'm still trying to find out whether this license is applicable for .jmod files.

Downloads

It requires an OpenJDK, perl, and the usual GNU build tools. It only builds on GNU/Linux systems.

There are currently no examples but as the API follows OpenCL closely it should be straightforward to use.

• zcl-1.0.tar.gz source code.

  23/4/2019: 1.0! It's finally here!

  • Converted to a modular project, split the demo clinfo into a separate module;
  • New build system using common java.make across my java modular projects;
  • Simpler cross-platform build system (Only GNU/Linux is supported!);
  • Requires nativez 1.0;
  • Requires cproto (for nativez);
  • Native library size is a bit smaller due to more efficient tables for object resolution (via nativez).

• zcl-0.6.tar.gz source code.

  9/9/2017: Updated to OpenCL version 2.1 and many other changes.

  • Updated to OpenCL version 2.1;
  • New build system based on my java.make;
  • Platfrom version tracking on CLExtendable objects.
  • Added run-time API version checking to most 2.0 or alter apis for increased robustness;
  • Filled out primitive array interfaces for buffer read/write functions (i.e. rectangular buffer transfers);
  • Generally more compact paramterised native code;
  • If OpenCL is not available then fail gracefully rather than abort the application;
  • More accurate and complete range checking for image and buffer transfer operations;
  • Added missing CLKernel functions;
  • Filled out cl_khr_gl_sharing implementation;
  • Fixed some races in the object tracking;
  • Added some common worksize constants to CLCommandQueue such as WORKSIZE_64x1x4, and so on;
  • Some generification of the query interfaces to clean up use;
  • Some more experiemtal `CLTask' stuff, apis and a series task for efficiency;
  • Some experimental half float stuff (untested);
  • Some (minor) doc improvements.

  A long time coming but the code is still being exercised and filling out.

  Apart from some ongoing experiments this is very stable and quite robust and the core API is expected to remain unchanged.

• zcl-0.5.tar.gz source code.

  6/11/2015: A bigger update than I expected although most are small but wide changes.

  • Multi-platform native build;
  • Automatic (or manual) garbage collection via a referent queue;
  • All objects are now globally unique (not just interface references);
  • Use dynamic linking to libOpenCL.so;
  • Filled out extension binding mechanism;
  • Implemented khr_gl_sharing and khr_gl_event extensions;
  • Experimental lambda interfaces (see blog);
  • Subsequently, Java 8 for both JDK/JRE is now REQUIRED;
  • Added some helper functions to create buffers and images from primitive arrays;
  • Added some helper functions for direct ByteBuffer allocation;
  • Minor api function renames (e.g. set to setArg);
  • Minor bug fixes and quality improvements.

  As usual see the README and source for all the grit, and the blog has some thoughts on the lambda and gc codes.

  This is functionally a 1.0 release apart from more testing and documentation.

• zcl-0.4.tar.gz source code.

  14/3/2015: Updated to OpenCL 2.0 support. Working toward a 1.0 release.

  Apart from 'it compiles' this hasn't had any testing. Aside from whether it functions i'm not sure if the approach I took to the new SVM mechanism is desirable - using direct ByteBuffer as the only type is the closest representation to the C api possible though.

  This is essentially an alpha build, moving toward a 1.0 release. There is testing, documentation, and OpenCL 2.1 to include yet.

  And wow, has it really been a year?

• zcl-0.3.tar.gz source code.

  11/3/2014: More fixes, arrays, and actual parallella support.

  Found a few more things missing - mostly CLDevice properties. This should have properly fixed 32-bit pointer handling as well and I managed to get a kernel to run on parallella (arm only). Because coprthr is really only OpenCL 1.0 I had to support that too.

  The biggest change is support for primitive arrays for the read/write buffer and image commands. This added a big chunk of code for all the overloaded methods. The way i've implemented it is nice in that you can simply pass an array and it should all work as expected but the problem is that requires event listeners to unpin the array when done which uses OpenCL 1.1 and adds some execution overhead; as such i'm contemplating a more explicit if convoluted programming model. Right now performance of thousands of non-blocking reads of a given buffer is about 1/2 the speed of using a direct Buffer.

  Also added a simple clinfo tool.

• zcl-0.2.tar.gz source code.

  5/3/2014: Fixes and parallella support.

  Fixed some missing api entry points, added compile-time support for OpenCL 1.1, fixed builds and warnings for 32-bit platforms (specifically parallella). Fixed the endian-ness issue with ByteBuffer return values.

  OpenCL 1.1 backend is emulated through the OpenCL 1.2 interfaces where possible. New functionality throws an UnsupportedOperation exception. Cases are in javadoc.

• zcl-0.1.tar.gz source code.

  4/3/2014: Initial release.

  This includes 100% coverage of the core OpenCL 1.2 API with minimal extra helper functions.

  Future versions may change the api.

  This represents under 5 days of effort.

Links

• zcl homepage - should be this page;
• opencl related posts on my blog;
• jogamp.org provides a production ready OpenCL and OpenGL binding library for Java;
• Khronos OpenCL Registry.

Contact

notzed on various mail servers, primarily gmail.com.