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 extend and dimension 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Image.ImageChannelOrder ImageChannelOrder specifies the number of channels and the channel layout i.e.
static class	Image.ImageChannelType ImageChannelType describes the size of the channel data type.
static class	Image.ImageDescriptor The image descriptor structure describes the type and dimensions of the image or image array.
static class	Image.ImageFormat Describes the image format, consisting of Image.ImageChannelOrder and Image.ImageChannelType.
static class	Image.ImageMapping Describes a mapped region of the image
static class	Image.ImageType The possible image types / dimensions.

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	Image(OpenCLObject.ObjectReleaser releaser)

Method Summary

Modifier and Type	Method and Description
abstract Event	acquireImageForSharingAsync(CommandQueue queue) Acquires this image object for using.
void	acquireImageForSharingNoEvent(CommandQueue queue) Acquires this image object for using.
abstract void	copyTo(CommandQueue queue, Image dest, long[] srcOrigin, long[] destOrigin, long[] region) Performs a blocking copy operation from one image to another.
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.
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.
abstract Event	fillAsync(CommandQueue queue, long[] origin, long[] region, ColorRGBA color) Fills the image with the specified color.
abstract Event	fillAsync(CommandQueue queue, long[] origin, long[] region, int[] color) Fills the image with the specified color given as four integer variables.
abstract long	getArraySize()
abstract long	getDepth()
abstract int	getElementSize()
abstract long	getHeight()
abstract Image.ImageFormat	getImageFormat()
abstract Image.ImageType	getImageType()
abstract long	getRowPitch()
abstract long	getSlicePitch()
abstract long	getWidth()
abstract Image.ImageMapping	map(CommandQueue queue, long[] origin, long[] region, MappingAccess access) Maps the image into host memory.
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).
abstract void	readImage(CommandQueue queue, java.nio.ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch) Performs a blocking read of the image into the specified byte buffer.
abstract Event	readImageAsync(CommandQueue queue, java.nio.ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch) Performs an async/non-blocking read of the image into the specified byte buffer.
Image	register() Registers this object for automatic releasing on garbage collection.
abstract Event	releaseImageForSharingAsync(CommandQueue queue) Releases a shared image object.
void	releaseImageForSharingNoEvent(CommandQueue queue) Releases a shared image object.
java.lang.String	toString()
abstract void	unmap(CommandQueue queue, Image.ImageMapping mapping) Unmaps the mapped memory
abstract void	writeImage(CommandQueue queue, java.nio.ByteBuffer src, long[] origin, long[] region, long rowPitch, long slicePitch) Performs a blocking write from the specified byte buffer into the image.
abstract Event	writeImageAsync(CommandQueue queue, java.nio.ByteBuffer src, long[] origin, long[] region, long rowPitch, long slicePitch) Performs an async/non-blocking write from the specified byte buffer into the image.

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

Image

protected Image(OpenCLObject.ObjectReleaser releaser)

Method Detail

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:

Image.ImageType.IMAGE_1D_ARRAY, Image.ImageType.IMAGE_2D_ARRAY

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,
                               java.nio.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,
                                     java.nio.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,
                                java.nio.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,
                                      java.nio.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:

unmap(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image.ImageMapping)

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(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image.ImageMapping)

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 java.lang.String toString()

Overrides:

toString in class java.lang.Object