sigonasr2
/
jmonkeyengine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

some more documentation

Browse Source
define_list_fix
shamanDevel 9 years ago
parent ee43853ff1
commit 510c40955f
2 changed files with 275 additions and 14 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 12
      jme3-core/src/main/java/com/jme3/opencl/Event.java
  2. 277
      jme3-core/src/main/java/com/jme3/opencl/Image.java

12
jme3-core/src/main/java/com/jme3/opencl/Event.java
Unescape View File

@ -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();
}

277
jme3-core/src/main/java/com/jme3/opencl/Image.java
Unescape View File

@ -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
}

Write Preview
Loading…
Cancel
Save