some more documentation
This commit is contained in:
shamanDevel
parent
ee43853ff1
commit
510c40955f
@ -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();
|
||||
}
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user