Package 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

  • Constructor Details

  • Method Details

    • 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 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(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(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(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(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, String include, 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, String include, List<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, 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, List<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(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 String toString()
      Overrides:
      toString in class Object