Package com.jme3.opencl

Class Image

java.lang.Object
com.jme3.opencl.AbstractOpenCLObject
com.jme3.opencl.Image
All Implemented Interfaces:
OpenCLObject
Direct Known Subclasses:
LwjglImage
public abstract class Image extends AbstractOpenCLObject
Wrapper for an OpenCL image.
An image object is similar to a Buffer, but with a specific element format and buffer structure.
The image is specified by the Image.ImageDescriptor, specifying the type and dimensions of the image, and Image.ImageFormat, specifying the type of each pixel.
An image is created from scratch using Context.createImage(com.jme3.opencl.MemoryAccess, com.jme3.opencl.Image.ImageFormat, com.jme3.opencl.Image.ImageDescriptor) or from OpenGL by Context.bindImage(com.jme3.texture.Image, com.jme3.texture.Texture.Type, int, com.jme3.opencl.MemoryAccess) (and alternative versions).

Most methods take long arrays as input: long[] origin and long[] region. Both are arrays of length 3.
origin defines the (x, y, z) offset in pixels in the 1D, 2D or 3D image, the (x, y) offset and the image index in the 2D image array or the (x) offset and the image index in the 1D image array. If image is a 2D image object, origin[2] must be 0. If image is a 1D image or 1D image buffer object, origin[1] and origin[2] must be 0. If image is a 1D image array object, origin[2] must be 0. If image is a 1D image array object, origin[1] describes the image index in the 1D image array. If image is a 2D image array object, origin[2] describes the image index in the 2D image array.
region defines the (width, height, depth) in pixels of the 1D, 2D or 3D rectangle, the (width, height) in pixels of the 2D rectangle and the number of images of a 2D image array or the (width) in pixels of the 1D rectangle and the number of images of a 1D image array. If image is a 2D image object, region[2] must be 1. If image is a 1D image or 1D image buffer object, region[1] and region[2] must be 1. If image is a 1D image array object, region[2] must be 1. The values in region cannot be 0.

  • Constructor Details

  • Method Details

    • register

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

    • getWidth

      public abstract long getWidth()
      Returns:
      the width of the image

    • getHeight

      public abstract long getHeight()
      Returns:
      the height of the image

    • getDepth

      public abstract long getDepth()
      Returns:
      the depth of the image

    • getRowPitch

      public abstract long getRowPitch()
      Returns:
      the row pitch when the image was created from a host buffer

    • getSlicePitch

      public abstract long getSlicePitch()
      Returns:
      the slice pitch when the image was created from a host buffer

    • getArraySize

      public abstract long getArraySize()
      Returns:
      the number of elements in the image array
      See Also:

    • getImageFormat

      public abstract Image.ImageFormat getImageFormat()
      Returns:
      the image format

    • getImageType

      public abstract Image.ImageType getImageType()
      Returns:
      the image type

    • getElementSize

      public abstract int getElementSize()
      Returns:
      the number of bytes per pixel

    • readImage

      public abstract void readImage(CommandQueue queue, ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch)
      Performs a blocking read of the image into the specified byte buffer.
      Parameters:
      queue - the command queue
      dest - the target byte buffer
      origin - the image origin location, see class description for the format
      region - the copied region, see class description for the format
      rowPitch - the row pitch of the target buffer, must be set to 0 if the image is 1D. If set to 0 for 2D and 3D image, the row pitch is calculated as bytesPerElement * width
      slicePitch - the slice pitch of the target buffer, must be set to 0 for 1D and 2D images. If set to 0 for 3D images, the slice pitch is calculated as rowPitch * height

    • readImageAsync

      public abstract Event readImageAsync(CommandQueue queue, ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch)
      Performs an async/non-blocking read of the image into the specified byte buffer.
      Parameters:
      queue - the command queue
      dest - the target byte buffer
      origin - the image origin location, see class description for the format
      region - the copied region, see class description for the format
      rowPitch - the row pitch of the target buffer, must be set to 0 if the image is 1D. If set to 0 for 2D and 3D image, the row pitch is calculated as bytesPerElement * width
      slicePitch - the slice pitch of the target buffer, must be set to 0 for 1D and 2D images. If set to 0 for 3D images, the slice pitch is calculated as rowPitch * height
      Returns:
      the event object indicating the status of the operation

    • writeImage

      public abstract void writeImage(CommandQueue queue, ByteBuffer src, long[] origin, long[] region, long rowPitch, long slicePitch)
      Performs a blocking write from the specified byte buffer into the image.
      Parameters:
      queue - the command queue
      src - the source buffer
      origin - the image origin location, see class description for the format
      region - the copied region, see class description for the format
      rowPitch - the row pitch of the target buffer, must be set to 0 if the image is 1D. If set to 0 for 2D and 3D image, the row pitch is calculated as bytesPerElement * width
      slicePitch - the slice pitch of the target buffer, must be set to 0 for 1D and 2D images. If set to 0 for 3D images, the slice pitch is calculated as rowPitch * height

    • writeImageAsync

      public abstract Event writeImageAsync(CommandQueue queue, ByteBuffer src, long[] origin, long[] region, long rowPitch, long slicePitch)
      Performs an async/non-blocking write from the specified byte buffer into the image.
      Parameters:
      queue - the command queue
      src - the source buffer
      origin - the image origin location, see class description for the format
      region - the copied region, see class description for the format
      rowPitch - the row pitch of the target buffer, must be set to 0 if the image is 1D. If set to 0 for 2D and 3D image, the row pitch is calculated as bytesPerElement * width
      slicePitch - the slice pitch of the target buffer, must be set to 0 for 1D and 2D images. If set to 0 for 3D images, the slice pitch is calculated as rowPitch * height
      Returns:
      the event object indicating the status of the operation

    • copyTo

      public abstract void copyTo(CommandQueue queue, Image dest, long[] srcOrigin, long[] destOrigin, long[] region)
      Performs a blocking copy operation from one image to another. Important: Both images must have the same format!
      Parameters:
      queue - the command queue
      dest - the target image
      srcOrigin - the source image origin, see class description for the format
      destOrigin - the target image origin, see class description for the format
      region - the copied region, see class description for the format

    • copyToAsync

      public abstract Event copyToAsync(CommandQueue queue, Image dest, long[] srcOrigin, long[] destOrigin, long[] region)
      Performs an async/non-blocking copy operation from one image to another. Important: Both images must have the same format!
      Parameters:
      queue - the command queue
      dest - the target image
      srcOrigin - the source image origin, see class description for the format
      destOrigin - the target image origin, see class description for the format
      region - the copied region, see class description for the format
      Returns:
      the event object indicating the status of the operation

    • map

      public abstract Image.ImageMapping map(CommandQueue queue, long[] origin, long[] region, MappingAccess access)
      Maps the image into host memory. The returned structure contains the mapped byte buffer and row and slice pitch. The event object is set to null, it is needed for the async version mapAsync(com.jme3.opencl.CommandQueue, long[], long[], com.jme3.opencl.MappingAccess).
      Parameters:
      queue - the command queue
      origin - the image origin, see class description for the format
      region - the mapped region, see class description for the format
      access - the allowed memory access to the mapped memory
      Returns:
      a structure describing the mapped memory
      See Also:

    • mapAsync

      public abstract Image.ImageMapping mapAsync(CommandQueue queue, long[] origin, long[] region, MappingAccess access)
      Non-blocking version of map(com.jme3.opencl.CommandQueue, long[], long[], com.jme3.opencl.MappingAccess). The returned structure contains the mapped byte buffer and row and slice pitch. The event object is used to detect when the mapped memory is available.
      Parameters:
      queue - the command queue
      origin - the image origin, see class description for the format
      region - the mapped region, see class description for the format
      access - the allowed memory access to the mapped memory
      Returns:
      a structure describing the mapped memory
      See Also:

    • unmap

      public abstract void unmap(CommandQueue queue, Image.ImageMapping mapping)
      Unmaps the mapped memory
      Parameters:
      queue - the command queue
      mapping - the mapped memory

    • fillAsync

      public abstract Event fillAsync(CommandQueue queue, long[] origin, long[] region, ColorRGBA color)
      Fills the image with the specified color. Does only work if the image channel is Image.ImageChannelType.FLOAT or Image.ImageChannelType.HALF_FLOAT.
      Parameters:
      queue - the command queue
      origin - the image origin, see class description for the format
      region - the size of the region, see class description for the format
      color - the color to fill
      Returns:
      an event object to detect for the completion

    • fillAsync

      public abstract Event fillAsync(CommandQueue queue, long[] origin, long[] region, int[] color)
      Fills the image with the specified color given as four integer variables. Does not work if the image channel is Image.ImageChannelType.FLOAT or Image.ImageChannelType.HALF_FLOAT.
      Parameters:
      queue - the command queue
      origin - the image origin, see class description for the format
      region - the size of the region, see class description for the format
      color - the color to fill, must be an array of length 4
      Returns:
      an event object to detect for the completion

    • copyToBufferAsync

      public abstract Event copyToBufferAsync(CommandQueue queue, Buffer dest, long[] srcOrigin, long[] srcRegion, long destOffset)
      Copies this image into the specified buffer, no format conversion is done. This is the dual function to Buffer.copyToImageAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image, long, long[], long[]).
      Parameters:
      queue - the command queue
      dest - the target buffer
      srcOrigin - the image origin, see class description for the format
      srcRegion - the copied region, see class description for the format
      destOffset - an offset into the target buffer
      Returns:
      the event object to detect the completion of the operation

    • acquireImageForSharingAsync

      public abstract Event acquireImageForSharingAsync(CommandQueue queue)
      Acquires this image object for using. Only call this method if this image represents a shared object from OpenGL, created with e.g. Context.bindImage(com.jme3.texture.Image, com.jme3.texture.Texture.Type, int, com.jme3.opencl.MemoryAccess) or variations. This method must be called before the image is used. After the work is done, the image must be released by calling releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) so that OpenGL can use the image/texture/renderbuffer again.
      Parameters:
      queue - the command queue
      Returns:
      the event object

    • acquireImageForSharingNoEvent

      public void acquireImageForSharingNoEvent(CommandQueue queue)
      Acquires this image object for using. Only call this method if this image represents a shared object from OpenGL, created with e.g. Context.bindImage(com.jme3.texture.Image, com.jme3.texture.Texture.Type, int, com.jme3.opencl.MemoryAccess) or variations. This method must be called before the image is used. After the work is done, the image must be released by calling releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) so that OpenGL can use the image/texture/renderbuffer again. The generated event object is directly released. This brings a performance improvement when the resource is e.g. directly used by a kernel afterwards on the same queue (this implicitly waits for this action). If you need the event, use acquireImageForSharingAsync(com.jme3.opencl.CommandQueue).
      Parameters:
      queue - the command queue

    • releaseImageForSharingAsync

      public abstract Event releaseImageForSharingAsync(CommandQueue queue)
      Releases a shared image object. Call this method after the image object was acquired by acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) to hand the control back to OpenGL.
      Parameters:
      queue - the command queue
      Returns:
      the event object

    • releaseImageForSharingNoEvent

      public void releaseImageForSharingNoEvent(CommandQueue queue)
      Releases a shared image object. Call this method after the image object was acquired by acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) to hand the control back to OpenGL. The generated event object is directly released, resulting in performance improvements.
      Parameters:
      queue - the command queue

    • toString

      public String toString()
      Overrides:
      toString in class Object