From 510c40955fd47d9be0b0fe5cf3b8c9e4f810cc05 Mon Sep 17 00:00:00 2001 From: shamanDevel Date: Tue, 26 Apr 2016 10:16:48 +0200 Subject: [PATCH] some more documentation --- .../src/main/java/com/jme3/opencl/Event.java | 12 +- .../src/main/java/com/jme3/opencl/Image.java | 277 +++++++++++++++++- 2 files changed, 275 insertions(+), 14 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/opencl/Event.java b/jme3-core/src/main/java/com/jme3/opencl/Event.java index ae72d0995..4e5400459 100644 --- a/jme3-core/src/main/java/com/jme3/opencl/Event.java +++ b/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(); } diff --git a/jme3-core/src/main/java/com/jme3/opencl/Image.java b/jme3-core/src/main/java/com/jme3/opencl/Image.java index 4e595d974..368b9a62d 100644 --- a/jme3-core/src/main/java/com/jme3/opencl/Image.java +++ b/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. + *
+ * An image object is similar to a {@link Buffer}, but with a specific element + * format and buffer structure. + *
+ * 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. + *
+ * 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). + * + *

+ * 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 }