some more documentation

jme3-core/src/main/java/com/jme3/opencl/Event.java

@@ -32,12 +32,22 @@
 package com.jme3.opencl;
 
 /**
- *
+ * Wrapper for an OpenCL Event object.
+ * Events are returned from kernel launches and all asynchronous operations.
+ * They allow to test if the action has completed and to block until the operation
+ * is done.
  * @author Sebastian Weiss
  */
 public interface Event extends OpenCLObject {
 	
+    /**
+     * Waits until the action has finished (blocking)
+     */
 	void waitForFinished();
 	
+    /**
+     * Tests if the action is completed
+     * @return {@code true} if the action is completed
+     */
 	boolean isCompleted();
 }

jme3-core/src/main/java/com/jme3/opencl/Image.java

@@ -36,11 +36,49 @@ import java.nio.ByteBuffer;
 import java.util.Objects;
 
 /**
+ * Wrapper for an OpenCL image.
+ * <br>
+ * An image object is similar to a {@link Buffer}, but with a specific element
+ * format and buffer structure.
+ * <br>
+ * The image is specified by the {@link ImageDescriptor}, specifying 
+ * the extend and dimension of the image, and {@link ImageFormat}, specifying
+ * the type of each pixel.
+ * <br>
+ * An image is created from scratch using 
+ * {@link Context#createImage(com.jme3.opencl.MemoryAccess, com.jme3.opencl.Image.ImageFormat, com.jme3.opencl.Image.ImageDescriptor) }
+ * or from OpenGL by
+ * {@link Context#bindImage(com.jme3.texture.Image, com.jme3.texture.Texture.Type, int, com.jme3.opencl.MemoryAccess) }
+ * (and alternative versions).
+ * 
+ * <p>
+ * Most methods take long arrays as input: {@code long[] origin} and {@code long[] region}.
+ * Both are arrays of length 3.
+ * <br>
+ * <b>origin</b> 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.
+ * <br>
+ * <b>region</b> 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.
+     * <p>
+     * There exists two constructors:<br>
+     * {@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).<br>
+     * {@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.
+     * <b>Important:</b> 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.
+     * <b>Important:</b> 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 <b>only</b> 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 <b>not</b> 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
 }