jocl.org

Utilities



The following is a collection of utilities for JOCL or OpenCL.

None of these utilities should be considered to be an official part of JOCL. These are standalone libraries, classes and collections of functions that are distributed independently.

Unless stated otherwise, these utilities are published under the terms of the GNU Lesser General Public License


JOCL Struct JAR file
(including documentation and source code)

Simple struct example
 This library shows how structs might be handled with JOCL. It contains the source code and documentation of a Struct class which can serve as the basis for own structs. For example, it is possible to create a struct 
public class Particle extends Struct
{
    public float mass;
    public cl_float4 position;
    public cl_float4 velocity;
}
which corresponds to the native struct 
typedef struct Particle
{
    float mass;
    float4 position;
    float4 velocity;
} Particle;
Arrays of instances of these Struct classes may then be written to buffers, which in turn can be copied into OpenCL memory objects. The utilitiy classes for doing so will automatically take care of the alignment requirements imposed by the OpenCL specification. The sample shows how these classes may be used.


Important note:

"Structs are difficult, both alignment of individual components and alignment and size of the overall struct must match on the device and host code. It probably will take trial and error to get it correct."
An employee of one of the largest OpenCL implementors

This library and the general approach are highly experimental. It has only been tested on 32 bit Windows, with a GeForce 8800 GPU. Other operating systems, architectures and GPUs may use different endianness or have different alignment requirements. The library should only be considered as a very basic demonstration of how structs might be used, but not more.
JET JAR file
(including documentation and source code)

Simple JET example
 This JAR file contains the JET - the "JOCL Event Tracer". This is a small utility that allows tracing events in JOCL and displays a bar chart showing the schedule and duration of the commands that the events belong to.

This is not a profiler!

It might be a helpful utility for analyzing the schedule of relatively long-lasting operations, and for detecting bottlenecks or disadvantageous wait conditions. However, its precision is not nearly as high as that of a real native OpenCL profiler.


The simple JET example shows how the JET may be used to trace events for some simple operations, and the output is shown in this screenshot:
The main area of the event tracer shows the bar plot of the events, encoding the information about how long each command has been waiting in the command queue or taken for execution.

The following interaction with the bar chart is possible:
  • Move the chart horizontally by dragging the mouse with the right button pressed
  • Zoom the chart by rotating the mouse wheel
  • Auto-fit the chart to be completely visible using a double-click of the right mouse button
  • Zoom to fit a single command by double-clicking the command with the left mouse button
  • Select an event with a single click of the left mouse button
When an event is selected, the panel on the right hand side will display specific information about the command that is associated with this event, namely the type and name of the command, and how long it stayed in each of the four possible states. Additionally, the "wait list" for the command will be displayed, and the dependencies between the commands will be indicated by the connections that are drawn between the bars in the chart panel.


Notes:

Currently, all events are associated with the same command queue and device, but of course, this is not the intention: The internal data structures already aim at supporting the visualization of multiple devices and multiple command queues for each device. This is currently not supported due to some flaws of the existing OpenCL implementations, of which some do not allow obtaining the command queue for an event, the device for a command queue, or precise timing information for events on multiple devices.

However, when this utility turns out to be useful and these functionalities are provided by future OpenCL implementations, they will be integrated into the event tracer utility.

The following screenshot shows another example: Here the event tracer was used to trace the events in the "JOCLMandelbrot" sample from the samples section, which divides the region of interest into smaller tiles and computes these tiles individually.



QuadFloat CL file
 This OpenCL source file contains some very basic functions for high-precision floating point values that are represented as a float4. The functions that are prefixed with "qf" may be considered as the "public" functions.

This file is also used in the "JOCLMandelbrot" sample from the samples section, to allow deep zooms into the Mandelbrot set.


These functions have been created by porting parts of the Quad-Double package from http://crd.lbl.gov/~dhbailey/mpdist/index.html to the float4 type of OpenCL. This file is distributed using any license that is compatible with the original license of the Quad-Double package (which is a slightly modified BSD license).