com.jme3.opencl

Class Context

java.lang.Object

com.jme3.opencl.AbstractOpenCLObject

com.jme3.opencl.Context

All Implemented Interfaces:

OpenCLObject

Direct Known Subclasses:

LwjglContext

public abstract class Context
extends AbstractOpenCLObject

The central OpenCL context. Every action starts from here. The context can be obtained by JmeContext.getOpenCLContext().

The context is used to:

• Query the available devices
• Create a command queue
• Create buffers and images
• Created buffers and images shared with OpenGL vertex buffers, textures and renderbuffers
• Create program objects from source code and source files

Nested Class Summary

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

OpenCLObject.ObjectReleaser

Field Summary

Fields inherited from class com.jme3.opencl.AbstractOpenCLObject

releaser

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
abstract Image	bindImage(Image image, Texture.Type textureType, int miplevel, MemoryAccess access) Creates a shared image object from a jME3-image.
Image	bindImage(Texture texture, int miplevel, MemoryAccess access) Creates a shared image object from a jME3 texture.
Image	bindImage(Texture texture, MemoryAccess access) Alternative version to bindImage(com.jme3.texture.Texture, int, com.jme3.opencl.MemoryAccess), uses miplevel=0.
protected abstract Image	bindPureRenderBuffer(FrameBuffer.RenderBuffer buffer, MemoryAccess access)
Image	bindRenderBuffer(FrameBuffer.RenderBuffer buffer, MemoryAccess access) Creates a shared image object from a jME3 render buffer.
abstract Buffer	bindVertexBuffer(VertexBuffer vb, MemoryAccess access) Creates a shared buffer from a VertexBuffer.
Buffer	createBuffer(long size) Alternative version of createBuffer(long, com.jme3.opencl.MemoryAccess), creates a buffer with read and write access.
abstract Buffer	createBuffer(long size, MemoryAccess access) Allocates a new buffer of the specific size and access type on the device.
Buffer	createBufferFromHost(java.nio.ByteBuffer data) Alternative version of createBufferFromHost(java.nio.ByteBuffer, com.jme3.opencl.MemoryAccess), creates a buffer with read and write access.
abstract Buffer	createBufferFromHost(java.nio.ByteBuffer data, MemoryAccess access) Creates a new buffer wrapping the specific host memory.
abstract Image	createImage(MemoryAccess access, Image.ImageFormat format, Image.ImageDescriptor descr) Creates a new 1D, 2D, 3D image. ImageFormat specifies the element type and order, like RGBA of floats. ImageDescriptor specifies the dimension of the image. Furthermore, a ByteBuffer can be specified in the ImageDescriptor together with row and slice pitches.
abstract Program	createProgramFromBinary(java.nio.ByteBuffer binaries, Device device) Creates a program from the specified binaries.
abstract Program	createProgramFromSourceCode(java.lang.String sourceCode) Creates a program object from the provided source code.
Program	createProgramFromSourceCodeWithDependencies(java.lang.String sourceCode, AssetManager assetManager) Resolves dependencies (using #include in the source code) and delegates the combined source code to createProgramFromSourceCode(java.lang.String).
Program	createProgramFromSourceFiles(AssetManager assetManager, java.util.List<java.lang.String> resources) Alternative version of createProgramFromSourceFilesWithInclude(com.jme3.asset.AssetManager, java.lang.String, java.util.List) with an empty include string
Program	createProgramFromSourceFiles(AssetManager assetManager, java.lang.String... resources) Alternative version of createProgramFromSourceFilesWithInclude(com.jme3.asset.AssetManager, java.lang.String, java.lang.String...) with an empty include string
Program	createProgramFromSourceFilesWithInclude(AssetManager assetManager, java.lang.String include, java.util.List<java.lang.String> resources) Creates a program object from the provided source code and files.
Program	createProgramFromSourceFilesWithInclude(AssetManager assetManager, java.lang.String include, java.lang.String... resources) Creates a program object from the provided source code and files.
CommandQueue	createQueue() Alternative version of createQueue(com.jme3.opencl.Device), just uses the first device returned by getDevices().
abstract CommandQueue	createQueue(Device device) Creates a command queue sending commands to the specified device.
abstract java.util.List<? extends Device>	getDevices() Returns all available devices for this context.
abstract Image.ImageFormat[]	querySupportedFormats(MemoryAccess access, Image.ImageType type) Queries all supported image formats for a specified memory access and image type.
Context	register() Registers this object for automatic releasing on garbage collection.
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

Constructor Detail

Context

protected Context(OpenCLObject.ObjectReleaser releaser)

Method Detail

register

public Context 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

getDevices

public abstract java.util.List<? extends Device> getDevices()

Returns all available devices for this context. These devices all belong to the same Platform. They are used to create a command queue sending commands to a particular device, see createQueue(com.jme3.opencl.Device). Also, device capabilities, like the supported OpenCL version, extensions, memory size and so on, are queried over the Device instances.
The available devices were specified by a PlatformChooser.

Returns:

a list of devices

createQueue

public CommandQueue createQueue()

Alternative version of createQueue(com.jme3.opencl.Device), just uses the first device returned by getDevices().

Returns:

the command queue

createQueue

public abstract CommandQueue createQueue(Device device)

Creates a command queue sending commands to the specified device. The device must be an entry of getDevices().

Parameters:

device - the target device

Returns:

the command queue

createBuffer

public abstract Buffer createBuffer(long size,
                                    MemoryAccess access)

Allocates a new buffer of the specific size and access type on the device.

Parameters:

size - the size of the buffer in bytes

access - the allowed access of this buffer from kernel code

Returns:

the new buffer

createBuffer

public Buffer createBuffer(long size)

Alternative version of createBuffer(long, com.jme3.opencl.MemoryAccess), creates a buffer with read and write access.

Parameters:

size - the size of the buffer in bytes

Returns:

the new buffer

createBufferFromHost

public abstract Buffer createBufferFromHost(java.nio.ByteBuffer data,
                                            MemoryAccess access)

Creates a new buffer wrapping the specific host memory. This host memory specified by a ByteBuffer can then be used directly by kernel code, although the access might be slower than with native buffers created by createBuffer(long, com.jme3.opencl.MemoryAccess).

Parameters:

data - the host buffer to use

access - the allowed access of this buffer from kernel code

Returns:

the new buffer

createBufferFromHost

public Buffer createBufferFromHost(java.nio.ByteBuffer data)

Alternative version of createBufferFromHost(java.nio.ByteBuffer, com.jme3.opencl.MemoryAccess), creates a buffer with read and write access.

Parameters:

data - the host buffer to use

Returns:

the new buffer

createImage

public abstract Image createImage(MemoryAccess access,
                                  Image.ImageFormat format,
                                  Image.ImageDescriptor descr)

Creates a new 1D, 2D, 3D image.
ImageFormat specifies the element type and order, like RGBA of floats.
ImageDescriptor specifies the dimension of the image.
Furthermore, a ByteBuffer can be specified in the ImageDescriptor together with row and slice pitches. This buffer is then used to store the image. If no ByteBuffer is specified, a new buffer is allocated (this is the normal behaviour).

Parameters:

access - the allowed access of this image from kernel code

format - the image format

descr - the image descriptor

Returns:

the new image object

querySupportedFormats

public abstract Image.ImageFormat[] querySupportedFormats(MemoryAccess access,
                                                          Image.ImageType type)

Queries all supported image formats for a specified memory access and image type.
Note that the returned array may contain ImageFormat objects where ImageChannelType or ImageChannelOrder are null (or both). This is the case when the device supports new formats that are not included in this wrapper yet.

Parameters:

access - the memory access type

type - the image type (1D, 2D, 3D, ...)

Returns:

an array of all supported image formats

bindVertexBuffer

public abstract Buffer bindVertexBuffer(VertexBuffer vb,
                                        MemoryAccess access)

Creates a shared buffer from a VertexBuffer. The returned buffer and the vertex buffer operate on the same memory, changes in one view are visible in the other view. This can be used to modify meshes directly from OpenCL (e.g. for particle systems).
Note: The vertex buffer must already been uploaded to the GPU, i.e. it must be used at least once for drawing.

Before the returned buffer can be used, it must be acquired explicitly by Buffer.acquireBufferForSharingAsync(com.jme3.opencl.CommandQueue) and after modifying it, released by Buffer.releaseBufferForSharingAsync(com.jme3.opencl.CommandQueue). This is needed so that OpenGL and OpenCL operations do not interfere with each other.

Parameters:

vb - the vertex buffer to share

access - the memory access for the kernel

Returns:

the new buffer

bindImage

public abstract Image bindImage(Image image,
                                Texture.Type textureType,
                                int miplevel,
                                MemoryAccess access)

Creates a shared image object from a jME3-image. The returned image shares the same memory with the jME3-image, changes in one view are visible in the other view. This can be used to modify textures and images directly from OpenCL (e.g. for post-processing effects and other texture effects).
Note: The image must already been uploaded to the GPU, i.e. it must be used at least once for drawing.

Before the returned image can be used, it must be acquired explicitly by Image.acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) and after modifying it, released by Image.releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) This is needed so that OpenGL and OpenCL operations do not interfere with each other.

Parameters:

image - the jME3 image object

textureType - the texture type (1D, 2D, 3D), since this is not stored in the image

miplevel - the mipmap level that should be shared

access - the allowed memory access for kernels

Returns:

the OpenCL image

bindImage

public Image bindImage(Texture texture,
                       int miplevel,
                       MemoryAccess access)

Creates a shared image object from a jME3 texture. The returned image shares the same memory with the jME3 texture, changes in one view are visible in the other view. This can be used to modify textures and images directly from OpenCL (e.g. for post-processing effects and other texture effects).
Note: The image must already been uploaded to the GPU, i.e. it must be used at least once for drawing.

Before the returned image can be used, it must be acquired explicitly by Image.acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) and after modifying it, released by Image.releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) This is needed so that OpenGL and OpenCL operations do not interfere with each other.

This method is equivalent to calling bindImage(texture.getImage(), texture.getType(), miplevel, access).

Parameters:

texture - the jME3 texture

miplevel - the mipmap level that should be shared

access - the allowed memory access for kernels

Returns:

the OpenCL image

bindImage

public Image bindImage(Texture texture,
                       MemoryAccess access)

Alternative version to bindImage(com.jme3.texture.Texture, int, com.jme3.opencl.MemoryAccess), uses miplevel=0.

Parameters:

texture - the jME3 texture

access - the allowed memory access for kernels

Returns:

the OpenCL image

bindRenderBuffer

public Image bindRenderBuffer(FrameBuffer.RenderBuffer buffer,
                              MemoryAccess access)

Creates a shared image object from a jME3 render buffer. The returned image shares the same memory with the jME3 render buffer, changes in one view are visible in the other view.
This can be used as an alternative to post-processing effects (e.g. reduce sum operations, needed e.g. for tone mapping).
Note: The renderbuffer must already been uploaded to the GPU, i.e. it must be used at least once for drawing.

Before the returned image can be used, it must be acquired explicitly by Image.acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) and after modifying it, released by Image.releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) This is needed so that OpenGL and OpenCL operations do not interfere with each other.

Parameters:

buffer - the buffer to bind

access - the kernel access permissions

Returns:

an image

bindPureRenderBuffer

protected abstract Image bindPureRenderBuffer(FrameBuffer.RenderBuffer buffer,
                                              MemoryAccess access)

createProgramFromSourceCode

public abstract Program createProgramFromSourceCode(java.lang.String sourceCode)

Creates a program object from the provided source code. The program still needs to be compiled using Program.build().

Parameters:

sourceCode - the source code

Returns:

the program object

createProgramFromSourceCodeWithDependencies

public Program createProgramFromSourceCodeWithDependencies(java.lang.String sourceCode,
                                                           AssetManager assetManager)

Resolves dependencies (using #include in the source code) and delegates the combined source code to createProgramFromSourceCode(java.lang.String). Important: only absolute paths are allowed.

Parameters:

sourceCode - the original source code

assetManager - the asset manager to load the files

Returns:

the created program object

Throws:

AssetNotFoundException - if a dependency could not be loaded

createProgramFromSourceFilesWithInclude

public Program createProgramFromSourceFilesWithInclude(AssetManager assetManager,
                                                       java.lang.String include,
                                                       java.lang.String... resources)

Creates a program object from the provided source code and files. The source code is made up from the specified include string first, then all files specified by the resource array (array of asset paths) are loaded by the provided asset manager and appended to the source code.

The typical use case is:

• The include string contains some compiler constants like the grid size
• Some common OpenCL files used as libraries (Convention: file names end with .clh
• One main OpenCL file containing the actual kernels (Convention: file name ends with .cl)

After the files were combined, additional include statements are resolved by createProgramFromSourceCodeWithDependencies(java.lang.String, com.jme3.asset.AssetManager).

Parameters:

assetManager - the asset manager used to load the files

include - an additional include string

resources - an array of asset paths pointing to OpenCL source files

Returns:

the new program objects

Throws:

AssetNotFoundException - if a file could not be loaded

createProgramFromSourceFilesWithInclude

public Program createProgramFromSourceFilesWithInclude(AssetManager assetManager,
                                                       java.lang.String include,
                                                       java.util.List<java.lang.String> resources)

Creates a program object from the provided source code and files. The source code is made up from the specified include string first, then all files specified by the resource array (array of asset paths) are loaded by the provided asset manager and appended to the source code.

The typical use case is:

• The include string contains some compiler constants like the grid size
• Some common OpenCL files used as libraries (Convention: file names end with .clh
• One main OpenCL file containing the actual kernels (Convention: file name ends with .cl)

After the files were combined, additional include statements are resolved by createProgramFromSourceCodeWithDependencies(java.lang.String, com.jme3.asset.AssetManager).

Parameters:

assetManager - the asset manager used to load the files

include - an additional include string

resources - an array of asset paths pointing to OpenCL source files

Returns:

the new program objects

Throws:

AssetNotFoundException - if a file could not be loaded

createProgramFromSourceFiles

public Program createProgramFromSourceFiles(AssetManager assetManager,
                                            java.lang.String... resources)

Alternative version of createProgramFromSourceFilesWithInclude(com.jme3.asset.AssetManager, java.lang.String, java.lang.String...) with an empty include string

Parameters:

assetManager - for loading assets

resources - asset paths pointing to OpenCL source files

Returns:

a new instance

Throws:

AssetNotFoundException - if a file could not be loaded

createProgramFromSourceFiles

public Program createProgramFromSourceFiles(AssetManager assetManager,
                                            java.util.List<java.lang.String> resources)

Alternative version of createProgramFromSourceFilesWithInclude(com.jme3.asset.AssetManager, java.lang.String, java.util.List) with an empty include string

Parameters:

assetManager - for loading assets

resources - a list of asset paths pointing to OpenCL source files

Returns:

a new instance

Throws:

AssetNotFoundException - if a file could not be loaded

createProgramFromBinary

public abstract Program createProgramFromBinary(java.nio.ByteBuffer binaries,
                                                Device device)

Creates a program from the specified binaries. The binaries are created by Program.getBinary(com.jme3.opencl.Device). The returned program still needs to be build using Program.build(java.lang.String, com.jme3.opencl.Device...). Important:The device passed to Program.getBinary(..), this method and Program#build(..) must be the same. The binaries are used to build a program cache across multiple launches of the application. The programs build much faster from binaries than from sources.

Parameters:

binaries - the binaries

device - the device to use

Returns:

the new program

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object