Aparapi Documentation

Aparapi is a framework for executing native Java code on the GPU. It works by converting Java bytecode into OpenCL kernels dynamically at runtime. Because it is backed by OpenCL, it is compatible with any OpenCL-compliant graphics card.

Key benefits:

• Data-Parallel Computation: Highly suited for tasks that can be parallelized across hundreds of GPU cores.
• Automatic Fallback: If OpenCL is not found on the system, Aparapi will automatically fall back to running the code on the CPU.
• Cross-Platform: Runs on all operating systems, with GPU acceleration support for Windows (32/64bit), Mac OSX (64bit), and Linux (32/64bit).

The core repository only contains the Java library. For other components, consider these related projects:

• Aparapi Examples: A collection of Java examples to help developers get started.
• Aparapi JNI: A JAR that embeds and loads native components at runtime (useful if you want to avoid separate native library management).
• Aparapi Native: The C/C++ project containing the native library components required for the Java library to communicate with the GPU.
• Aparapi Vagrant: A Vagrant environment for compiling Aparapi native libraries for Linux (x86 and x64).

To include Aparapi in your Java project, add the following dependency to your pom.xml file. Note that the Aparapi JNI native interface is now automatically handled as a Maven dependency, so manual installation of the native interface is no longer required.

<dependency>
    <groupId>com.aparapi</groupId>
    <artifactId>aparapi</artifactId>
    <version>3.0.0</version>
</dependency>

To move from sequential CPU execution to parallel GPU execution, you must wrap your logic inside an anonymous Kernel class and use a Range to define the execution space.

Instead of a standard for loop, you override the run() method and use getGlobalId() to identify the current iteration index.

// 1. Define the Kernel
Kernel kernel = new Kernel() {
    @Override
    public void run() {
        // getGlobalId() provides the index for the current parallel task
        int i = getGlobalId();
        result[i] = inA[i] + inB[i];
    }
};

// 2. Define the execution range (size of the data)
Range range = Range.create(result.length);

// 3. Execute the kernel on the GPU
kernel.execute(range);

While Aparapi can run on a CPU without any special configuration, GPU acceleration requires OpenCL to be installed on your local system.

Aparapi has been tested with and supports:

• OpenCL 1.2
• OpenCL 2.0
• OpenCL 2.1