+ * Most methods take long arrays as input: {@code long[] origin} and {@code 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.
*
* @author Sebastian Weiss
*/
public interface Image extends OpenCLObject {
+ /**
+ * {@code ImageChannelType} describes the size of the channel data type.
+ */
public static enum ImageChannelType {
SNORM_INT8,
SNORM_INT16,
@@ -59,6 +97,10 @@ public interface Image extends OpenCLObject {
FLOAT
}
+ /**
+ * {@code ImageChannelOrder} specifies the number of channels and the channel layout i.e. the
+memory layout in which channels are stored in the image.
+ */
public static enum ImageChannelOrder {
R, Rx, A,
INTENSITY,
@@ -69,6 +111,10 @@ public interface Image extends OpenCLObject {
ARGB, BGRA
}
+ /**
+ * Describes the image format, consisting of
+ * {@link ImageChannelOrder} and {@link ImageChannelType}.
+ */
public static class ImageFormat { //Struct
public ImageChannelOrder channelOrder;
public ImageChannelType channelType;
@@ -114,6 +160,9 @@ public interface Image extends OpenCLObject {
}
+ /**
+ * The possible image types / dimensions.
+ */
public static enum ImageType {
IMAGE_1D,
IMAGE_1D_BUFFER,
@@ -123,6 +172,15 @@ public interface Image extends OpenCLObject {
IMAGE_2D_ARRAY
}
+ /**
+ * The image descriptor structure describes the type and dimensions of the image or image array.
+ *
+ * There exists two constructors:
+ * {@link #ImageDescriptor(com.jme3.opencl.Image.ImageType, long, long, long, long) }
+ * is used when an image with new memory should be created (used most often).
+ * {@link #ImageDescriptor(com.jme3.opencl.Image.ImageType, long, long, long, long, long, long, java.nio.ByteBuffer) }
+ * creates an image using the provided {@code ByteBuffer} as source.
+ */
public static class ImageDescriptor { //Struct
public ImageType type;
public long width;
@@ -140,6 +198,17 @@ public interface Image extends OpenCLObject {
public ImageDescriptor() {
}
+ /**
+ * Used to specify an image with the provided ByteBuffer as soruce
+ * @param type the image type
+ * @param width the width
+ * @param height the height, unused for image types {@code ImageType.IMAGE_1D*}
+ * @param depth the depth of the image, only used for image type {@code ImageType.IMAGE_3D}
+ * @param arraySize the number of array elements for image type {@code ImageType.IMAGE_1D_ARRAY} and {@code ImageType.IMAGE_2D_ARRAY}
+ * @param rowPitch the row pitch of the provided buffer
+ * @param slicePitch the slice pitch of the provided buffer
+ * @param hostPtr host buffer used as image memory
+ */
public ImageDescriptor(ImageType type, long width, long height, long depth, long arraySize, long rowPitch, long slicePitch, ByteBuffer hostPtr) {
this.type = type;
this.width = width;
@@ -150,6 +219,15 @@ public interface Image extends OpenCLObject {
this.slicePitch = slicePitch;
this.hostPtr = hostPtr;
}
+ /**
+ * Specifies an image without a host buffer, a new chunk of memory
+ * will be allocated.
+ * @param type the image type
+ * @param width the width
+ * @param height the height, unused for image types {@code ImageType.IMAGE_1D*}
+ * @param depth the depth of the image, only used for image type {@code ImageType.IMAGE_3D}
+ * @param arraySize the number of array elements for image type {@code ImageType.IMAGE_1D_ARRAY} and {@code ImageType.IMAGE_2D_ARRAY}
+ */
public ImageDescriptor(ImageType type, long width, long height, long depth, long arraySize) {
this.type = type;
this.width = width;
@@ -168,33 +246,175 @@ public interface Image extends OpenCLObject {
}
+ /**
+ * @return the width of the image
+ */
long getWidth();
+ /**
+ * @return the height of the image
+ */
long getHeight();
+ /**
+ * @return the depth of the image
+ */
long getDepth();
+ /**
+ * @return the row pitch when the image was created from a host buffer
+ * @see ImageDescriptor#ImageDescriptor(com.jme3.opencl.Image.ImageType, long, long, long, long, long, long, java.nio.ByteBuffer)
+ */
long getRowPitch();
+ /**
+ * @return the slice pitch when the image was created from a host buffer
+ * @see ImageDescriptor#ImageDescriptor(com.jme3.opencl.Image.ImageType, long, long, long, long, long, long, java.nio.ByteBuffer)
+ */
long getSlicePitch();
+ /**
+ * @return the number of elements in the image array
+ * @see ImageType#IMAGE_1D_ARRAY
+ * @see ImageType#IMAGE_2D_ARRAY
+ */
long getArraySize();
+ /**
+ * @return the image format
+ */
ImageFormat getImageFormat();
+ /**
+ * @return the image type
+ */
ImageType getImageType();
+ /**
+ * @return the number of bytes per pixel
+ */
int getElementSize();
+ /**
+ * Performs a blocking read of the image into the specified byte buffer.
+ * @param queue the command queue
+ * @param dest the target byte buffer
+ * @param origin the image origin location, see class description for the format
+ * @param region the copied region, see class description for the format
+ * @param 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 {@code bytesPerElement * width}
+ * @param 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 {@code rowPitch * height}
+ */
void readImage(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.
+ * @param queue the command queue
+ * @param dest the target byte buffer
+ * @param origin the image origin location, see class description for the format
+ * @param region the copied region, see class description for the format
+ * @param 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 {@code bytesPerElement * width}
+ * @param 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 {@code rowPitch * height}
+ * @return the event object indicating the status of the operation
+ */
Event readImageAsync(CommandQueue queue, ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch);
- void writeImage(CommandQueue queue, ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch);
- Event writeImageAsync(CommandQueue queue, ByteBuffer dest, long[] origin, long[] region, long rowPitch, long slicePitch);
+ /**
+ * Performs a blocking write from the specified byte buffer into the image.
+ * @param queue the command queue
+ * @param src the source buffer
+ * @param origin the image origin location, see class description for the format
+ * @param region the copied region, see class description for the format
+ * @param 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 {@code bytesPerElement * width}
+ * @param 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 {@code rowPitch * height}
+ */
+ void writeImage(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.
+ * @param queue the command queue
+ * @param src the source buffer
+ * @param origin the image origin location, see class description for the format
+ * @param region the copied region, see class description for the format
+ * @param 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 {@code bytesPerElement * width}
+ * @param 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 {@code rowPitch * height}
+ * @return the event object indicating the status of the operation
+ */
+ Event writeImageAsync(CommandQueue queue, ByteBuffer src, long[] origin, long[] region, long rowPitch, long slicePitch);
+ /**
+ * Performs a blocking copy operation from one image to another.
+ * Important: Both images must have the same format!
+ * @param queue the command queue
+ * @param dest the target image
+ * @param srcOrigin the source image origin, see class description for the format
+ * @param destOrigin the target image origin, see class description for the format
+ * @param region the copied region, see class description for the format
+ */
void copyTo(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!
+ * @param queue the command queue
+ * @param dest the target image
+ * @param srcOrigin the source image origin, see class description for the format
+ * @param destOrigin the target image origin, see class description for the format
+ * @param region the copied region, see class description for the format
+ * @return the event object indicating the status of the operation
+ */
Event copyToAsync(CommandQueue queue, Image dest, long[] srcOrigin, long[] destOrigin, long[] region);
+ /**
+ * 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 {@code null}, it is needed for the asnyc
+ * version {@link #mapAsync(com.jme3.opencl.CommandQueue, long[], long[], com.jme3.opencl.MappingAccess) }.
+ * @param queue the command queue
+ * @param origin the image origin, see class description for the format
+ * @param region the mapped region, see class description for the format
+ * @param access the allowed memory access to the mapped memory
+ * @return a structure describing the mapped memory
+ * @see #unmap(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image.ImageMapping)
+ */
ImageMapping map(CommandQueue queue, long[] origin, long[] region, MappingAccess access);
+ /**
+ * Non-blocking version of {@link #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.
+ * @param queue the command queue
+ * @param origin the image origin, see class description for the format
+ * @param region the mapped region, see class description for the format
+ * @param access the allowed memory access to the mapped memory
+ * @return a structure describing the mapped memory
+ * @see #unmap(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image.ImageMapping)
+ */
ImageMapping mapAsync(CommandQueue queue, long[] origin, long[] region, MappingAccess access);
+ /**
+ * Unmaps the mapped memory
+ * @param queue the command queue
+ * @param mapping the mapped memory
+ */
void unmap(CommandQueue queue, ImageMapping mapping);
+ /**
+ * Describes a mapped region of the image
+ */
public static class ImageMapping {
+ /**
+ * The raw byte buffer
+ */
public final ByteBuffer buffer;
+ /**
+ * The row pitch in bytes.
+ * This value is at least {@code bytesPerElement * width}
+ */
public final long rowPitch;
+ /**
+ * The slice pitch in bytes.
+ * This value is at least {@code rowPitch * height}
+ */
public final long slicePitch;
+ /**
+ * The event object used to detect when the memory is available.
+ * @see #mapAsync(com.jme3.opencl.CommandQueue, long[], long[], com.jme3.opencl.MappingAccess)
+ */
public final Event event;
public ImageMapping(ByteBuffer buffer, long rowPitch, long slicePitch, Event event) {
@@ -216,29 +436,60 @@ public interface Image extends OpenCLObject {
* Fills the image with the specified color.
* Does only work if the image channel is {@link ImageChannelType#FLOAT}
* or {@link ImageChannelType#HALF_FLOAT}.
- * @param queue
- * @param origin
- * @param region
- * @param color
- * @return
+ * @param queue the command queue
+ * @param origin the image origin, see class description for the format
+ * @param region the size of the region, see class description for the format
+ * @param color the color to fill
+ * @return an event object to detect for the completion
*/
Event fillAsync(CommandQueue queue, long[] origin, long[] region, ColorRGBA color);
/**
* Fills the image with the specified color given as four integer variables.
* Does not work if the image channel is {@link ImageChannelType#FLOAT}
* or {@link ImageChannelType#HALF_FLOAT}.
- * @param queue
- * @param origin
- * @param region
- * @param color
- * @return
+ * @param queue the command queue
+ * @param origin the image origin, see class description for the format
+ * @param region the size of the region, see class description for the format
+ * @param color the color to fill, must be an array of length 4
+ * @return an event object to detect for the completion
*/
Event fillAsync(CommandQueue queue, long[] origin, long[] region, int[] color);
+ /**
+ * Copies this image into the specified buffer, no format conversion is done.
+ * This is the dual function to
+ * {@link Buffer#copyToImageAsync(com.jme3.opencl.CommandQueue, com.jme3.opencl.Image, long, long[], long[]) }.
+ * @param queue the command queue
+ * @param dest the target buffer
+ * @param srcOrigin the image origin, see class description for the format
+ * @param srcRegion the copied region, see class description for the format
+ * @param destOffset an offset into the target buffer
+ * @return the event object to detect the completion of the operation
+ */
Event copyToBufferAsync(CommandQueue queue, Buffer dest, long[] srcOrigin, long[] srcRegion, long destOffset);
-
+ /**
+ * Aquires this image object for using. Only call this method if this image
+ * represents a shared object from OpenGL, created with e.g.
+ * {@link 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
+ * {@link #releaseImageForSharingAsync(com.jme3.opencl.CommandQueue) }
+ * so that OpenGL can use the image/texture/renderbuffer again.
+ * @param queue the command queue
+ * @return the event object
+ */
Event acquireImageForSharingAsync(CommandQueue queue);
+ /**
+ * Releases a shared image object.
+ * Call this method after the image object was acquired by
+ * {@link #acquireImageForSharingAsync(com.jme3.opencl.CommandQueue) }
+ * to hand the control back to OpenGL.
+ * @param queue the command queue
+ * @return the event object
+ */
Event releaseImageForSharingAsync(CommandQueue queue);
+
//TODO: add variants of the above two methods that don't create the event object, but release the event immediately
}