JOCL FAQ: Difference between revisions

From JogampWiki
Jump to navigation Jump to search
(added rudimentary getting started page)
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Get the Source Code ==
__TOC__


Create a local copy/branch of the git repository,
== What OpenCL platforms / Operating Systems / JDKs are supported? ==
either anonymous:
OpenCL Platforms:
* all of them. We are testing every build (in fact every commit) on AMD, Nvidia and Intel SDKs.
* If you are running on a different platform or would like to provide a build server, please let us know.


* git clone git://github.com/mbien/gluegen.git gluegen
Operating Systems:
* git clone git://github.com/mbien/jocl.git jocl
* Linux 32/64, Mac OS and Windows 32/64
* git clone git://github.com/mbien/jocl-demos.git jocl-demos
* Building JOCL on other systems is easy provided that a OpenCL implementation for that system.
* git clone git://github.com/mbien/jogl.git jogl
(e.g. OpenSolaris doesn't have OpenCL drivers yet)
 
Java Runtime Environments:
* We are testing on Oracle JDK and OpenJDK
* Java 5+ is required to run JOCL.
 
== OpenCL on Mobile ARM SoC ==
StreamComputing maintains a list of SoC GPU's supporting OpenCL.
http://streamcomputing.eu/knowledge/sdks/
 
=== Android ===
JogAmp provide OpenCL bindings using the JOCL .apk files on Android.
 
 
The first generation Android OpenCL devices, the Nexus 10 tablet and Nexus 4 phone
uses non standards OpenCL library names
 
https://jogamp.org/bugzilla/show_bug.cgi?id=773
 
If you have one of these new devices and want to help improve JOCL to dynamically link to these non standard library names please get in touch with the JogAmp community.
 
=== GNU/Linux ===
JogAmp provide OpenCL bindings using the JOCL jar for use on ARM GNU/Linux systems, we support both the soft-float and hard-float ABI.
 
 
OpenCL drivers are provided from Freescale for its many i.MX6 Vivante GPU based boards.
 
http://streamcomputing.eu/knowledge/sdks/vivante-gpu/
 
https://community.freescale.com/docs/DOC-94464
 
 
=== CPU software OpenCL on systems where no GPU drivers are available ===
 
* COPRTHR SDK
** libcoprthr - An open-source OpenCL implementation for multicore x86_64 and ARM.
** http://www.browndeertechnology.com/coprthr.htm
** https://github.com/browndeer/coprthr.git
** libcoprthr provides a reference build of OpenCL for the Parallella board. http://www.kickstarter.com/projects/adapteva/parallella-a-supercomputer-for-everyone
** libcoprthr - is licensed under the LGPL
 
 
* POCL - based on LLVM
** Portable OpenCL aims to be an efficient open source (MIT-licensed) implementation of the OpenCL 1.2 standard.
** http://pocl.sourceforge.net/
** http://lists.linaro.org/pipermail/linaro-gpgpu/2013-May/000001.html - pocl running on the CPU reported to be working on the Samsung Chromebook
 
 
* SAMSUNG SNU
** http://aces.snu.ac.kr/Center_for_Manycore_Programming/SNU-SAMSUNG_OpenCL_Framework.html - registration needed before download.
** http://chromebookcomputing.blogspot.se/?view=classic - setup instructions for SAMSUNG SNU on a Samsung Chromebook.
** http://opencl.snu.ac.kr/license.php - SNU compiler is released under GPL and the runtime LGPL
 
 
* PGCL The portland group - http://www.pgroup.com/products/pgcl/
** PGCL is released under a properitary license.
** PGCL provides reference OpenCL builds for the ST-Ericsson NovaThor boards.
 
== How do I get the Source Code? ==
The project repository is located on [http://jogamp.org/git/?p=jocl.git jogamp],
 
You can create a local copy/branch of the git repository,
either anonymous from jogamp:
 
* git clone git://jogamp.org/srv/scm/gluegen.git gluegen
* git clone git://jogamp.org/srv/scm/jogl.git jogl
* git clone git://jogamp.org/srv/scm/jocl.git jocl
* git clone git://jogamp.org/srv/scm/jocl-demos.git jocl-demos
 
or github, e.g.:
* git clone https://github.com/JogAmp/jocl.git jocl
 
.. etc ..


or via SSH and your user credential, so you can easily push back your
or via SSH and your user credential, so you can easily push back your
Line 17: Line 91:
* git clone [email protected]:username/jogl.git jogl
* git clone [email protected]:username/jogl.git jogl


== What are the Build Dependencies? ==
JOCL depends on [[GlueGen_Wiki|GlueGen]] and [[JOGL_Wiki|JOGL]]


== Getting Started ==
JDK6 and ANT 1.8 or later. JUnit tests require OpenCL capable hardware and OpenCL drivers.
Hello JOCL host program:
<pre>
import com.mbien.opencl.*;
import java.io.IOException;
import java.nio.FloatBuffer;
import java.util.Random;
 
import static java.lang.System.*;
import static com.mbien.opencl.CLMemory.Mem.*;
 
/**
* Hello Java OpenCL example. Adds all elements of buffer A to buffer B
* and stores the result in buffer C.<br/>
* 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 {
 
        int elementCount = 11444777;    // Length of arrays to process
        int localWorkSize = 256;        // Local work size       
        int globalWorkSize = roundUp(localWorkSize, elementCount);  // rounded up to the nearest multiple of the localWorkSize
 
        // set up
        CLContext context = CLContext.create();
        CLProgram program = context.createProgram(HelloJOCL.class.getResourceAsStream("VectorAdd.cl")).build();


        CLBuffer<FloatBuffer> clBufferA = context.createFloatBuffer(globalWorkSize, READ_ONLY);
== I have all the Sourcecode, how do I build it? ==
        CLBuffer<FloatBuffer> clBufferB = context.createFloatBuffer(globalWorkSize, READ_ONLY);
Please refer to [https://jogamp.org/jocl/doc/HowToBuild.html this HowTo]
        CLBuffer<FloatBuffer> clBufferC = context.createFloatBuffer(globalWorkSize, WRITE_ONLY);


        // fill read buffers with random numbers.
== What files do I need at Runtime?  ==
        fillBuffer(clBufferA.getBuffer(), 12345);
JOCL consists of two files:
        fillBuffer(clBufferB.getBuffer(), 67890);
* jocl.jar
* and one system dependent native library (e.g libjocl.so or jocl.dll or ..).
additionally you will have to provide
* gluegen-rt.jar
* and the corresponding native library (e.g libgluegen-rt.so or gluegen.dll or ...)
optionally you might want to add JOGL if you want to do OpenGL - OpenCL interoperability
* see [{{SERVER}}/jogl/doc/deployment/JOGL-DEPLOYMENT.html JOGL deployment options]


        // get a reference to the kernel functon with the name 'VectorAdd'
== How do I Get Started? ==
        // and map the buffers to its input parameters.
* [http://michael-bien.com/mbien/entry/java_binding_for_the_opencl Short Introduction to JOCL]
        CLKernel kernel = program.createCLKernel("VectorAdd");
* [[JOCL_Tutorial|Hello JOCL]]
        kernel.putArgs(clBufferA, clBufferB, clBufferC).putArg(elementCount);
* [http://jogamp.org/jocl-demos/www JOCL Demo Projects]


        // create command queue on fastest device.
== How can I test if OpenCL is properly set up on my system? ==
        CLCommandQueue queue = context.getMaxFlopsDevice().createCommandQueue();
* run [http://jogamp.org/deployment/webstart-next/jocl-demos/clinfo.jnlp CLInfo] via webstart for basic OpenCL diagnostic readouts
* or invoke:
  java -jar jocl.jar:gluegen-rt.jar -Djava.library.path="path/to/jocl/libs:path/to/gluegen-rt/libs" com.jogamp.opencl.util.CLInfo


        // asynchronous write of data to GPU device,
: '''note1:''' replace ':' with ';' on windows
        // blocking read later to get the computed results back.
: '''note2:''' extract gluegen-rt-natives-xxx.jar and jocl-natives-xxx.jar. It won't work if you place the jars in the library path!
        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.
* run some of the other [http://jogamp.org/jocl-demos/www/ webstart demos]
        context.release();


        // print first few elements of the resulting buffer to the console.
== Is it possible to run JOCL based app without JOGL? ==
        out.println("a+b=c results snapshot: ");
Yes. JOCL is independent from JOGL and can be used without JOGL in the classpath.
        for(int i = 0; i < 10; i++)
In fact you have to explicitly create a shared context from a existing JOGL context if you want to interoperate with OpenGL.
            out.print(clBufferC.getBuffer().get() + ", ");
        out.println("...; " + clBufferC.getBuffer().remaining() + " more");


        out.println("computation took: "+(time/1000000)+"ms");
// creates a pure OpenCL context
    }
CLContext context = [http://jogamp.org/deployment/webstart-next/javadoc/jocl/javadoc/com/jogamp/opencl/CLContext.html CLContext].create();


    /* utilities */
// creates a shared context. This context can be used to share memory with JOGL's OpenGL context
    private static void fillBuffer(FloatBuffer buffer, int seed) {
CLGLContext context = [http://jogamp.org/deployment/webstart-next/javadoc/jocl/javadoc/com/jogamp/opencl/gl/CLGLContext.html CLGLContext].create(glContext);
        Random rnd = new Random(seed);
        while(buffer.remaining() != 0)
            buffer.put(rnd.nextFloat()*100);
        buffer.rewind();
    }


    private static int roundUp(int groupSize, int globalSize) {
== Can I allocate a CLBuffer without allocating a java.nio.Buffer? ==
        int r = globalSize % groupSize;
yes, just use the right context.createBuffer() method.
        if (r == 0) return globalSize;
        else        return globalSize + groupSize - r;
    }
}
</pre>
Hello JOCL Kernel
<pre>
    // 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
discussion: http://forum.jogamp.org/Allocate-memory-object-on-device-only-tp2465039p2465039.html
        int iGID = get_global_id(0);


        // bound check, equivalent to the limit on a 'for' loop
== How do I do image processing with JOCL? ==
        if (iGID >= numElements)  {
For a simple example take a look at the [https://github.com/mbien/jocl-demos/blob/master/src/com/jogamp/opencl/demos/gamma/CLSimpleGammaCorrection.java gamma correction demo] from the  
            return;
[http://jogamp.org/jocl-demos/www/ jocl-demos] repository.
        }


        // add the vector elements
== Is jocl.org the same as JOCL? ==
        c[iGID] = a[iGID] + b[iGID];
no its not. Both are independent projects and do not share the same codebase.
    }
</pre>

Latest revision as of 23:12, 4 July 2013

What OpenCL platforms / Operating Systems / JDKs are supported?

OpenCL Platforms:

  • all of them. We are testing every build (in fact every commit) on AMD, Nvidia and Intel SDKs.
  • If you are running on a different platform or would like to provide a build server, please let us know.

Operating Systems:

  • Linux 32/64, Mac OS and Windows 32/64
  • Building JOCL on other systems is easy provided that a OpenCL implementation for that system.

(e.g. OpenSolaris doesn't have OpenCL drivers yet)

Java Runtime Environments:

  • We are testing on Oracle JDK and OpenJDK
  • Java 5+ is required to run JOCL.

OpenCL on Mobile ARM SoC

StreamComputing maintains a list of SoC GPU's supporting OpenCL. http://streamcomputing.eu/knowledge/sdks/

Android

JogAmp provide OpenCL bindings using the JOCL .apk files on Android.


The first generation Android OpenCL devices, the Nexus 10 tablet and Nexus 4 phone uses non standards OpenCL library names

https://jogamp.org/bugzilla/show_bug.cgi?id=773

If you have one of these new devices and want to help improve JOCL to dynamically link to these non standard library names please get in touch with the JogAmp community.

GNU/Linux

JogAmp provide OpenCL bindings using the JOCL jar for use on ARM GNU/Linux systems, we support both the soft-float and hard-float ABI.


OpenCL drivers are provided from Freescale for its many i.MX6 Vivante GPU based boards.

http://streamcomputing.eu/knowledge/sdks/vivante-gpu/

https://community.freescale.com/docs/DOC-94464


CPU software OpenCL on systems where no GPU drivers are available




  • PGCL The portland group - http://www.pgroup.com/products/pgcl/
    • PGCL is released under a properitary license.
    • PGCL provides reference OpenCL builds for the ST-Ericsson NovaThor boards.

How do I get the Source Code?

The project repository is located on jogamp,

You can create a local copy/branch of the git repository, either anonymous from jogamp:

or github, e.g.:

.. etc ..

or via SSH and your user credential, so you can easily push back your changes to the github server:

What are the Build Dependencies?

JOCL depends on GlueGen and JOGL

JDK6 and ANT 1.8 or later. JUnit tests require OpenCL capable hardware and OpenCL drivers.

I have all the Sourcecode, how do I build it?

Please refer to this HowTo

What files do I need at Runtime?

JOCL consists of two files:

  • jocl.jar
  • and one system dependent native library (e.g libjocl.so or jocl.dll or ..).

additionally you will have to provide

  • gluegen-rt.jar
  • and the corresponding native library (e.g libgluegen-rt.so or gluegen.dll or ...)

optionally you might want to add JOGL if you want to do OpenGL - OpenCL interoperability

How do I Get Started?

How can I test if OpenCL is properly set up on my system?

  • run CLInfo via webstart for basic OpenCL diagnostic readouts
  • or invoke:
 java -jar jocl.jar:gluegen-rt.jar -Djava.library.path="path/to/jocl/libs:path/to/gluegen-rt/libs" com.jogamp.opencl.util.CLInfo
note1: replace ':' with ';' on windows
note2: extract gluegen-rt-natives-xxx.jar and jocl-natives-xxx.jar. It won't work if you place the jars in the library path!

Is it possible to run JOCL based app without JOGL?

Yes. JOCL is independent from JOGL and can be used without JOGL in the classpath. In fact you have to explicitly create a shared context from a existing JOGL context if you want to interoperate with OpenGL. 

// creates a pure OpenCL context
CLContext context = CLContext.create();

// creates a shared context. This context can be used to share memory with JOGL's OpenGL context
CLGLContext context = CLGLContext.create(glContext);

Can I allocate a CLBuffer without allocating a java.nio.Buffer?

yes, just use the right context.createBuffer() method.

discussion: http://forum.jogamp.org/Allocate-memory-object-on-device-only-tp2465039p2465039.html

How do I do image processing with JOCL?

For a simple example take a look at the gamma correction demo from the jocl-demos repository.

Is jocl.org the same as JOCL?

no its not. Both are independent projects and do not share the same codebase.

Retrieved from "https://jogamp.org/wiki/index.php?title=JOCL_FAQ&oldid=1047"