com.jme3.opencl

Class Kernel

java.lang.Object

com.jme3.opencl.AbstractOpenCLObject

com.jme3.opencl.Kernel

All Implemented Interfaces:

OpenCLObject

Direct Known Subclasses:

LwjglKernel

public abstract class Kernel
extends AbstractOpenCLObject

Wrapper for an OpenCL kernel, a piece of executable code on the GPU.

Terminology:
A Kernel is executed in parallel. In total number of parallel threads, called work items, are specified by the global work size (of type Kernel.WorkSize). These threads are organized in a 1-D, 2-D or 3-D grid (of course, this is only a logical view). Inside each kernel, the id of each thread (i.e. the index inside this grid) can be requested by get_global_id(dimension) with dimension=0,1,2.
Not all threads can always be executed in parallel because there simply might not be enough processor cores. Therefore, the concept of a work group is introduced. The work group specifies the actual number of threads that are executed in parallel. The maximal size of it can be queried by Device.getMaxiumWorkItemsPerGroup(). Again, the threads inside the work group can be organized in a 1D, 2D or 3D grid, but this is also just a logical view (specifying how the threads are indexed). The work group is important for another concept: shared memory Unlike the normal global or constant memory (passing a Buffer object as argument), shared memory can't be set from outside. Shared memory is allocated by the kernel and is only valid within the kernel. It is used to quickly share data between threads within a work group. The size of the shared memory is specified by setting an instance of Kernel.LocalMem or Kernel.LocalMemPerElement as argument.
Due to heavy register usage or other reasons, a kernel might not be able to utilize a whole work group. Therefore, the actual number of threads that can be executed in a work group can be queried by getMaxWorkGroupSize(com.jme3.opencl.Device), which might differ from the value returned from the Device.

There are two ways to launch a kernel:
First, arguments and the work group sizes can be set in advance (setArg(index, ...), setGlobalWorkSize(...) and setWorkGroupSize(...). Then a kernel is launched by Run(com.jme3.opencl.CommandQueue).
Second, two convenient functions are provided that set the arguments and work sizes in one call: Run1(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...) and Run2(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...).

See Also:

Program.createKernel(java.lang.String)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Kernel.LocalMem A placeholder for kernel arguments representing local kernel memory.
static class	Kernel.LocalMemPerElement A placeholder for a kernel argument representing local kernel memory per thread.
static class	Kernel.WorkSize The work size (global and local) for executing a kernel

Nested classes/interfaces inherited from interface com.jme3.opencl.OpenCLObject

OpenCLObject.ObjectReleaser

Field Summary

Fields

Modifier and Type	Field and Description
protected Kernel.WorkSize	globalWorkSize The current global work size
protected Kernel.WorkSize	workGroupSize The current local work size

Fields inherited from class com.jme3.opencl.AbstractOpenCLObject

releaser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Kernel(OpenCLObject.ObjectReleaser releaser)

Method Summary

Modifier and Type	Method and Description
abstract int	getArgCount()
Kernel.WorkSize	getGlobalWorkSize()
abstract long	getMaxWorkGroupSize(Device device) Returns the maximal work group size when this kernel is executed on the specified device
abstract java.lang.String	getName()
Kernel.WorkSize	getWorkGroupSize()
Kernel	register() Registers this object for automatic releasing on garbage collection.
abstract Event	Run(CommandQueue queue) Launches the kernel with the current global work size, work group size and arguments.
Event	Run1(CommandQueue queue, Kernel.WorkSize globalWorkSize, java.lang.Object... args) Sets the work sizes and arguments in one call and launches the kernel.
void	Run1NoEvent(CommandQueue queue, Kernel.WorkSize globalWorkSize, java.lang.Object... args) Sets the work sizes and arguments in one call and launches the kernel.
Event	Run2(CommandQueue queue, Kernel.WorkSize globalWorkSize, Kernel.WorkSize workGroupSize, java.lang.Object... args) Sets the work sizes and arguments in one call and launches the kernel.
void	Run2NoEvent(CommandQueue queue, Kernel.WorkSize globalWorkSize, Kernel.WorkSize workGroupSize, java.lang.Object... args) Sets the work sizes and arguments in one call and launches the kernel.
void	RunNoEvent(CommandQueue queue) Launches the kernel with the current global work size, work group size and arguments without returning an event object.
abstract void	setArg(int index, Buffer t)
abstract void	setArg(int index, byte b)
abstract void	setArg(int index, java.nio.ByteBuffer buffer, long size) Raw version to set an argument.
abstract void	setArg(int index, double d)
abstract void	setArg(int index, float f)
abstract void	setArg(int index, Image i)
abstract void	setArg(int index, int i)
abstract void	setArg(int index, Kernel.LocalMem t)
abstract void	setArg(int index, Kernel.LocalMemPerElement t)
abstract void	setArg(int index, long l)
void	setArg(int index, Matrix3f mat)
abstract void	setArg(int index, Matrix4f mat)
void	setArg(int index, java.lang.Object arg) Sets the kernel argument at the specified index. The argument must be a known type: LocalMemPerElement, LocalMem, Image, Buffer, byte, short, int, long, float, double, Vector2f, Vector4f, Quaternion, Matrix3f, Matrix4f.
abstract void	setArg(int index, Quaternion q)
abstract void	setArg(int index, short s)
abstract void	setArg(int index, Vector2f v)
abstract void	setArg(int index, Vector4f v)
void	setGlobalWorkSize(int size) Sets the global work size to a 1D grid
void	setGlobalWorkSize(int width, int height) Sets the global work size to be a 2D grid
void	setGlobalWorkSize(int width, int height, int depth) Sets the global work size to be a 3D grid
void	setGlobalWorkSize(Kernel.WorkSize ws) Sets the global work size.
void	setWorkGroupSdize(int width, int height, int depth) Sets the work group size to be a 3D grid
void	setWorkGroupSize(int size) Sets the work group size to be a 1D grid
void	setWorkGroupSize(int width, int height) Sets the work group size to be a 2D grid
void	setWorkGroupSize(Kernel.WorkSize ws) Sets the work group size
void	setWorkGroupSizeToNull() Tells the driver to figure out the work group size on their own.
java.lang.String	toString()

Methods inherited from class com.jme3.opencl.AbstractOpenCLObject

finalize, getReleaser, release

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

globalWorkSize

protected final Kernel.WorkSize globalWorkSize

The current global work size

workGroupSize

protected final Kernel.WorkSize workGroupSize

The current local work size

Constructor Detail

Kernel

protected Kernel(OpenCLObject.ObjectReleaser releaser)

Method Detail

register

public Kernel register()

Description copied from interface: OpenCLObject

Registers this object for automatic releasing on garbage collection. By default, OpenCLObjects are not registered in the OpenCLObjectManager, you have to release it manually by calling OpenCLObject.release(). Without registering or releasing, a memory leak might occur.
Returns this to allow calls like Buffer buffer = clContext.createBuffer(1024).register();.

Specified by:

register in interface OpenCLObject

Overrides:

register in class AbstractOpenCLObject

Returns:

this

getName

public abstract java.lang.String getName()

Returns:

the name of the kernel as defined in the program source code

getArgCount

public abstract int getArgCount()

Returns:

the number of arguments

getGlobalWorkSize

public Kernel.WorkSize getGlobalWorkSize()

Returns:

the current global work size

setGlobalWorkSize

public void setGlobalWorkSize(Kernel.WorkSize ws)

Sets the global work size.

Parameters:

ws - the work size to set

setGlobalWorkSize

public void setGlobalWorkSize(int size)

Sets the global work size to a 1D grid

Parameters:

size - the size in 1D

setGlobalWorkSize

public void setGlobalWorkSize(int width,
                              int height)

Sets the global work size to be a 2D grid

Parameters:

width - the width

height - the height

setGlobalWorkSize

public void setGlobalWorkSize(int width,
                              int height,
                              int depth)

Sets the global work size to be a 3D grid

Parameters:

width - the width

height - the height

depth - the depth

getWorkGroupSize

public Kernel.WorkSize getWorkGroupSize()

Returns:

the current work group size

setWorkGroupSize

public void setWorkGroupSize(Kernel.WorkSize ws)

Sets the work group size

Parameters:

ws - the work group size to set

setWorkGroupSize

public void setWorkGroupSize(int size)

Sets the work group size to be a 1D grid

Parameters:

size - the size to set

setWorkGroupSize

public void setWorkGroupSize(int width,
                             int height)

Sets the work group size to be a 2D grid

Parameters:

width - the width

height - the height

setWorkGroupSdize

public void setWorkGroupSdize(int width,
                              int height,
                              int depth)

Sets the work group size to be a 3D grid

Parameters:

width - the width

height - the height

depth - the depth

setWorkGroupSizeToNull

public void setWorkGroupSizeToNull()

Tells the driver to figure out the work group size on their own. Use this if you do not rely on specific work group layouts, i.e. because shared memory is not used. Run1(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...) implicitly calls this method.

getMaxWorkGroupSize

public abstract long getMaxWorkGroupSize(Device device)

Returns the maximal work group size when this kernel is executed on the specified device

Parameters:

device - the device

Returns:

the maximal work group size

setArg

public abstract void setArg(int index,
                            Kernel.LocalMemPerElement t)

setArg

public abstract void setArg(int index,
                            Kernel.LocalMem t)

setArg

public abstract void setArg(int index,
                            Buffer t)

setArg

public abstract void setArg(int index,
                            Image i)

setArg

public abstract void setArg(int index,
                            byte b)

setArg

public abstract void setArg(int index,
                            short s)

setArg

public abstract void setArg(int index,
                            int i)

setArg

public abstract void setArg(int index,
                            long l)

setArg

public abstract void setArg(int index,
                            float f)

setArg

public abstract void setArg(int index,
                            double d)

setArg

public abstract void setArg(int index,
                            Vector2f v)

setArg

public abstract void setArg(int index,
                            Vector4f v)

setArg

public abstract void setArg(int index,
                            Quaternion q)

setArg

public abstract void setArg(int index,
                            Matrix4f mat)

setArg

public void setArg(int index,
                   Matrix3f mat)

setArg

public abstract void setArg(int index,
                            java.nio.ByteBuffer buffer,
                            long size)

Raw version to set an argument. size bytes of the provided byte buffer are copied to the kernel argument. The size in bytes must match exactly the argument size as defined in the kernel code. Use this method to send custom structures to the kernel

Parameters:

index - the index of the argument

buffer - the raw buffer

size - the size in bytes

setArg

public void setArg(int index,
                   java.lang.Object arg)

Sets the kernel argument at the specified index.
The argument must be a known type: LocalMemPerElement, LocalMem, Image, Buffer, byte, short, int, long, float, double, Vector2f, Vector4f, Quaternion, Matrix3f, Matrix4f.
Note: Matrix3f and Matrix4f will be mapped to a float16 (row major).

Parameters:

index - the index of the argument, from 0 to getArgCount()-1

arg - the argument

Throws:

java.lang.IllegalArgumentException - if the argument type is not one of the listed ones

Run

public abstract Event Run(CommandQueue queue)

Launches the kernel with the current global work size, work group size and arguments. If the returned event object is not needed and would otherwise be released immediately, RunNoEvent(com.jme3.opencl.CommandQueue) might bring a better performance.

Parameters:

queue - the command queue

Returns:

an event object indicating when the kernel is finished

See Also:

setGlobalWorkSize(com.jme3.opencl.Kernel.WorkSize), setWorkGroupSize(com.jme3.opencl.Kernel.WorkSize), setArg(int, java.lang.Object)

RunNoEvent

public void RunNoEvent(CommandQueue queue)

Launches the kernel with the current global work size, work group size and arguments without returning an event object. The generated event is directly released. Therefore, the performance is better, but there is no way to detect when the kernel execution has finished. For this purpose, use Run(com.jme3.opencl.CommandQueue).

Parameters:

queue - the command queue

See Also:

setGlobalWorkSize(com.jme3.opencl.Kernel.WorkSize), setWorkGroupSize(com.jme3.opencl.Kernel.WorkSize), setArg(int, java.lang.Object)

Run1

public Event Run1(CommandQueue queue,
                  Kernel.WorkSize globalWorkSize,
                  java.lang.Object... args)

Sets the work sizes and arguments in one call and launches the kernel. The global work size is set to the specified size. The work group size is automatically determined by the driver. Each object in the argument array is sent to the kernel by setArg(int, java.lang.Object).

Parameters:

queue - the command queue

globalWorkSize - the global work size

args - the kernel arguments

Returns:

an event object indicating when the kernel is finished

See Also:

Run2(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...)

Run1NoEvent

public void Run1NoEvent(CommandQueue queue,
                        Kernel.WorkSize globalWorkSize,
                        java.lang.Object... args)

Sets the work sizes and arguments in one call and launches the kernel. The global work size is set to the specified size. The work group size is automatically determined by the driver. Each object in the argument array is sent to the kernel by setArg(int, java.lang.Object). The generated event is directly released. Therefore, the performance is better, but there is no way to detect when the kernel execution has finished. For this purpose, use Run1(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...).

Parameters:

queue - the command queue

globalWorkSize - the global work size

args - the kernel arguments

See Also:

Run2(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...)

Run2

public Event Run2(CommandQueue queue,
                  Kernel.WorkSize globalWorkSize,
                  Kernel.WorkSize workGroupSize,
                  java.lang.Object... args)

Sets the work sizes and arguments in one call and launches the kernel.

Parameters:

queue - the command queue

globalWorkSize - the global work size

workGroupSize - the work group size

args - the kernel arguments

Returns:

an event object indicating when the kernel is finished

Run2NoEvent

public void Run2NoEvent(CommandQueue queue,
                        Kernel.WorkSize globalWorkSize,
                        Kernel.WorkSize workGroupSize,
                        java.lang.Object... args)

Sets the work sizes and arguments in one call and launches the kernel. The generated event is directly released. Therefore, the performance is better, but there is no way to detect when the kernel execution has finished. For this purpose, use Run2(com.jme3.opencl.CommandQueue, com.jme3.opencl.Kernel.WorkSize, com.jme3.opencl.Kernel.WorkSize, java.lang.Object...).

Parameters:

queue - the command queue

globalWorkSize - the global work size

workGroupSize - the work group size

args - the kernel arguments

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object