Convenience class which makes allocating, updating and releasing OpenCL buffers easy. More...

#include <MOpenCLBuffer.h>

Public Member Functions
	MOpenCLBuffer (cl_context gpuContext, cl_mem_flags flags)
	Class constructor. More...

	MOpenCLBuffer (cl_context gpuContext, cl_mem_flags flags, size_t size, void host_ptr, cl_int err)
	Class constructor. More...

	MOpenCLBuffer ()
	Class constructor. More...

	MOpenCLBuffer (MOpenCLBuffer &&)
	Move constructor. More...

	~MOpenCLBuffer ()
	Class destructor. More...

MOpenCLBuffer &	operator= (MOpenCLBuffer &&)
	Move operator. More...

void	reset ()
	Release the OpenCL buffer (if any) and the event (if any). More...

cl_int	uploadDataToGPU (cl_command_queue gpuQueue, cl_bool blocking_write, size_t offset, size_t size, void host_ptr, cl_uint numEvents, const cl_event events)
	Send data to the GPU. More...

cl_int	ensureBufferSize (size_t size)
	Make certain that the OpenCL buffer held by MOpenCLBuffer is large enough to hold size bytes. More...

size_t	bufferSize () const
	Introduced in 2023.0 More...

MAutoCLMem	buffer ()
	Get the OpenCL buffer held by MOpenCLBuffer. More...

const MAutoCLMem	buffer () const
	Get the OpenCL buffer held by MOpenCLBuffer. More...

MAutoCLEvent	bufferReadyEvent ()
	Get the OpenCL event held by MOpenCLBuffer. More...

Detailed Description

Convenience class which makes allocating, updating and releasing OpenCL buffers easy.

MOpenCLBuffer is a convenience class which can replace calls to clCreateBuffer, clEnqueueWriteBuffer and clReleaseBuffer. MOpenCLBuffer provides a number of features which make creating, updating and releasing an OpenCL buffer simple.

When MOpenCLBuffer allocates a cl_mem object MOpenCLBuffer automatically notifies Maya of the increased GPU memory usage (see MRenderer::holdGPUMemory()).

When MOpenCLBuffer updates a cl_mem object it will automatically allocate a larger buffer if the new data size is larger than the old data size.

When MOpenCLBuffer deallocates a cl_mem object MOpenCLBuffer automatically notifies Maya of the decreased GPU memory usage.

Examples:: offsetNode/offsetNode.cpp.

Constructor & Destructor Documentation

MOpenCLBuffer	(	cl_context	gpuContext,
		cl_mem_flags	flags
	)

Class constructor.

Create an MOpenCLBuffer without creating a GPU buffer.

Parameters

[in]	gpuContext	A valid OpenCL context to be used to create a buffer object.
[in]	flags	Specify usage information for the buffer object. CL_MEM_READ_WRITE The memory object will be read and written by a kernel. CL_MEM_WRITE_ONLY The memory object will only be written to by a kernel. CL_MEM_READ_ONLY The memory object will only be read from by a kernel.

MOpenCLBuffer	(	cl_context	gpuContext,
		cl_mem_flags	flags,
		size_t	size,
		void *	host_ptr,
		cl_int *	err
	)

Class constructor.

Create a GPU buffer able to hold size bytes. If host_ptr is not NULL, copy the data from host_ptr to the GPU buffer. host_ptr must be larger than size bytes.

Parameters

[in]	gpuContext	A valid OpenCL context to be used to create a buffer object.
[in]	flags	Specify usage information for the buffer object. CL_MEM_READ_WRITE The memory object will be read and written by a kernel. CL_MEM_WRITE_ONLY The memory object will only be written to by a kernel. CL_MEM_READ_ONLY The memory object will only be read from by a kernel.
[in]	size	The size in bytes of the OpenCL buffer to be allocated.
[in]	host_ptr	Optional. Data to be copied into the OpenCL buffer.
[out]	err	OpenCL error code.

MOpenCLBuffer ( )

Class constructor.

Create an MOpenCLBuffer without creating a GPU buffer. The cl_context used is the cl_context returned by MOpenCLInfo::getOpenCLContext(). The cl_mem_flags used are CL_MEM_READ_ONLY.

MOpenCLBuffer ( MOpenCLBuffer && other )

Move constructor.

Create an MOpenCLBuffer from an existing MOpenCLBuffer other. After calling MOpenCLBuffer(MOpenCLBuffer &&) it is not valid to call any method on other except for its destructor.

~MOpenCLBuffer ( )

Class destructor.

Release the OpenCL buffer (if any) and the event (if any).

Member Function Documentation

MOpenCLBuffer & operator= ( MOpenCLBuffer && other )

Move operator.

The GPU buffer held in this object is released. The GPU buffer held in other is now held in this object. It is not safe to call any methods on other expect for ~MOpenCLBuffer.

void reset ( )

Release the OpenCL buffer (if any) and the event (if any).

Set the size of the MOpenCLBuffer back to zero.

cl_int uploadDataToGPU	(	cl_command_queue	gpuQueue,
		cl_bool	blocking_write,
		size_t	offset,
		size_t	size,
		void *	host_ptr,
		cl_uint	numEvents,
		const cl_event *	events
	)

Send data to the GPU.

Allocate a new OpenCL buffer if the size of the upload is larger than the current size of the MOpenCLBuffer.

Parameters

[in]	gpuQueue	A valid OpenCL context to be used to create a buffer object.
[in]	blocking_write	Specify usage information for the buffer object.
[in]	offset	The offset in bytes in the OpenCL buffer to write to.
[in]	size	The size in bytes of the data to write to OpenCL.
[in]	host_ptr	Data to be copied into the OpenCL buffer. Must be at least size bytes.
[in]	numEvents	Number of events to wait for before beginning to modify the OpenCL buffer.
[in]	events	List of events to wait for before beginning to modify the OpenCL buffer.

Returns: CL_SUCCESS for success, an OpenCL error code otherwise.

cl_int ensureBufferSize ( size_t size )

Make certain that the OpenCL buffer held by MOpenCLBuffer is large enough to hold size bytes.

If the MOpenCLBuffer already exists and is greater than or equal to the new size, MOpenCLBuffer will re-use the underlying OpenCL buffer. If the existing buffer is not large enough a new and larger buffer will be allocated.

Parameters

[in] size The desired size in bytes of the OpenCL buffer.

Returns: CL_SUCCESS for success, an OpenCL error code otherwise.

size_t bufferSize ( ) const

Introduced in 2023.0

Return the current size in bytes of the buffer.

2023.0:: Introduced in this version.

Returns: The size in bytes of the buffer.

MAutoCLMem buffer ( )

Get the OpenCL buffer held by MOpenCLBuffer.

The underlying cl_mem object may change if uploadDataToGPU() or ensureBufferSize() is called.

Returns: The OpenCL buffer held by MOpenCLBuffer.

const MAutoCLMem buffer ( ) const

Get the OpenCL buffer held by MOpenCLBuffer.

The underlying cl_mem object may change if uploadDataToGPU() or ensureBufferSize() is called.

Returns: The OpenCL buffer held by MOpenCLBuffer.

MAutoCLEvent bufferReadyEvent ( )

Get the OpenCL event held by MOpenCLBuffer.

The OpenCL buffer is safe to read if the event held in the MAutoCLEvent is NULL or complete.

Returns: The OpenCL event which must complete before it is safe to read the buffer.

The documentation for this class was generated from the following files:

MOpenCLBuffer.h
MOpenCLBuffer.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation