#include <CE_Context.h>

Classes
struct	DeviceDescriptor

struct	KernelInfo

Public Types
typedef int64(*	FreeFunc )(int64)

Public Member Functions
	CE_Context ()

virtual	~CE_Context ()

cl::Context	getCLContext () const
	Returns the underlying cl::Context object. More...

cl::CommandQueue	getQueue () const

cl::Device	getDevice () const
	Returns the OpenCL Device object. More...

ceTraceCtx	getTraceContext () const

void	get1DRanges (const cl::Kernel &k, size_t items, cl::NDRange &g, cl::NDRange &l)

size_t	getMaxWorkgroupSize (const cl::Kernel &k)
	Get the maximum workgroup size for the given kernel. More...

std::vector< size_t >	getMaxWorkItemSizes ()

cl::Program	loadProgram (const char progname, const char options=NULL, bool recompile=false)

cl::Program	compileProgram (const char progtext, const char options=NULL, bool recompile=false)

cl::Kernel	loadKernel (const cl::Program &prog, const UT_StringRef &kernelname)

cl::Kernel	loadKernel (const char progname, const UT_StringRef &kernelname, const char options=NULL)

bool	isValid () const
	Returns whether the CE_Context has been successfully initialized. More...

bool	isCPU () const
	Returns true if the OpenCL device is running on the CPU. More...

bool	hasDoubleSupport () const
	Returns true if the OpenCL device supports double precision. More...

bool	has3DImageWriteSupport () const
	Returns true if the OpenCL device supports writing to 3D image objects. More...

void	finish (bool sweepPool=true)

cl::Buffer	allocBuffer (int64 size, bool usePool=true, bool read=true, bool write=true, uint32 ogl_bind=SYS_UINT32_MAX)

void	releaseBuffer (cl::Buffer &&buf)
	Release the specified buffer, possibly to the CE_MemoryPool. More...

void	readBuffer (const cl::Buffer &buf, size_t size, void *p, bool blocking=true, size_t offset=0)
	Read the specified number of bytes from the buffer. More...

void	writeBuffer (const cl::Buffer &buf, size_t size, const void *p, bool blocking=true, size_t offset=0)
	Write the specified number of bytes to the buffer. More...

void	enqueueKernel (const cl::Kernel &kernel, const cl::NDRange &global, const cl::NDRange &local)
	Enqueue the kernel over the provided ranges. More...

uint32	registerDelayedOGLBindBuffer (CE_DelayedOGLBindBuffer *buffer)

void	unregisterDelayedOGLBindBuffer (uint32 id)

CE_DelayedOGLBindBuffer *	lookupDelayedOGLBindBuffer (uint id)

bool	supportsUUID ()

void	getDeviceUUID (cl_uchar(&uuid)[CL_UUID_SIZE_KHR])

void	getDriverUUID (cl_uchar(&uuid)[CL_UUID_SIZE_KHR])

bool	supportsExternalMemory ()

CE_ExternalBuffer	createExternalMemoryBuffer (SYS_Handle handle, int64_t size, bool read=true, bool write=true)

CE_ExternalImage	createExternalImage (SYS_Handle handle, const cl_image_format &format, const cl_image_desc &image_desc, bool read=true, bool write=true)

void	clearMemoryPool ()
	Clear the CE_MemoryPool object. More...

fpreal32 *	getPinnedBuffer (int64 size)

cl::Buffer	getXNoiseData ()

void	setOutOfMemoryFailure (bool hasfailed=true)

bool	hasOutOfMemoryFailureHappened () const

bool	getDeviceInfo (const char *flag, fpreal &result)

size_t	getAddressableMemory () const

void	registerMemFreeFunc (FreeFunc func)

const UT_Array< FreeFunc > &	getMemFreeFuncs () const
	Returns the list of registered memory freeing functions. More...

void	reportUsage (std::ostream &os) const
	Report memory usage. More...

Static Public Member Functions
static CE_Context *	getContext (bool gl_shared=true, bool shared_fallback=true)

static bool	isGLSharingPossible ()
	Returns true if interoperability between CL and GL is possible. More...

static void	getInfo (const cl::Device &device, UT_WorkBuffer &buffer)

static void	getExtendedInfo (const cl::Device &device, UT_WorkBuffer &buffer)

static void	getAllPlatformsInfo (UT_WorkBuffer &buffer)

static size_t	roundUpGroupSize (size_t gsize)

static bool	isInitialized (bool gl_shared=false)

static void	reportError (const cl::Error &err)

static void	outputErrorMessage (const char *errMsg)

static void	setErrorCB (CE_ErrorCB callback, void *data)

static void	outputWarningMessage (const char *errMsg)

static void	initMainSharedGLContext (int devicetype, void context, void display)

static bool	useHalfNormalDelayedBindBuffer ()

static void	getDevices (UT_Array< DeviceDescriptor > &, cl_device_type t)
	Get the vector of available devices of the given type. More...

static int	getDefaultDevice (cl_device_type t, const UT_Array< DeviceDescriptor > &devices)

static bool	isEnvironmentOverride ()
	Returns true if environment variables are set that override preferences. More...

template<class T >
static bool	getDeviceInfoRestricted (cl_device_id device, cl_uint flag, T &result)

Protected Member Functions
cl::Program *	doCompileProgram (const char progtext, const char options, bool recompile)

void	init (cl::Context &context, cl::Device &device)
	Initialize the context for the given device. More...

void	releasePinnedBuffer ()
	Releases the pinned, page-locked memory buffer. More...

Protected Attributes
cl::Context	myContext

cl::CommandQueue	myQueue

cl::CommandQueue	myDeviceQueue

ceTraceCtx	myTraceCtx

cl::Device	myDevice

bool	myIsValid

bool	mySupportsDouble

bool	mySupports3DImageWrites

cl::Buffer	myXNoiseData

UT_StringMap< cl::Program * >	myProgramTable

UT_Map< const _cl_program , UT_Array< KernelInfo > >	myKernelTable

CE_MemoryPool *	myMemPool

UT_Array< FreeFunc >	myMemFreeFuncs

cl::Buffer	myPinnedBuffer

fpreal32 *	myPinnedData

bool	myOutOfMemoryFailure

UT_Map< uint32, CE_DelayedOGLBindBuffer * >	myDelayedOGLBindBuffers

Static Protected Attributes
static void *	theGLContext

static void *	theGLDisplay

static int	theGLDeviceType

Detailed Description

CE_Context encapsulates the OpenCL context and provides various convenience functions for loading kernel programs and allocating GPU memory.

Definition at line 87 of file CE_Context.h.

Member Typedef Documentation

typedef int64(* CE_Context::FreeFunc)(int64)

Type of a pointer to a memory freeing function. Input is how much to attempt to free, and return value is the actual amount freed.

Definition at line 317 of file CE_Context.h.

Constructor & Destructor Documentation

CE_Context::CE_Context ( )

virtual CE_Context::~CE_Context ( )

virtual

Member Function Documentation

cl::Buffer CE_Context::allocBuffer	(	int64	size,
		bool	usePool = `true`,
		bool	read = `true`,
		bool	write = `true`,
		uint32	ogl_bind = `SYS_UINT32_MAX`
	)

Allocate a buffer of specified size on the CE_Device. usePool= true, attempts to use the underlying CE_MemoryPool to possibly return an already allocated, unused buffer. read=true, creates a buffer that is readable inside kernels. write=true, creates a buffer that is writable inside kernels. ogl_bind, specifies an OGL buffer to bind to.

void CE_Context::clearMemoryPool ( )

Clear the CE_MemoryPool object.

cl::Program CE_Context::compileProgram	(	const char *	progtext,
		const char *	options = `NULL`,
		bool	recompile = `false`
	)

CE_ExternalImage CE_Context::createExternalImage	(	SYS_Handle	handle,
		const cl_image_format &	format,
		const cl_image_desc &	image_desc,
		bool	read = `true`,
		bool	write = `true`
	)

CE_ExternalBuffer CE_Context::createExternalMemoryBuffer	(	SYS_Handle	handle,
		int64_t	size,
		bool	read = `true`,
		bool	write = `true`
	)

Create a buffer backed by external memory. The handle will be the reference to the actual memory object, and its lifetime is externally managed. The memory might be owned by another GPU API, such as Vulkan. In those cases, that handle can be obtained by a call to vkGetMemoryFdKHR or vkGetMemoryWin32HandleKHR This requires a few extensions to be available. Check that the context supports these by calling CE_Context::supportsExternalMemory first.

cl::Program* CE_Context::doCompileProgram	(	const char *	progtext,
		const char *	options,
		bool	recompile
	)

protected

void CE_Context::enqueueKernel	(	const cl::Kernel &	kernel,
		const cl::NDRange &	global,
		const cl::NDRange &	local
	)

Enqueue the kernel over the provided ranges.

void CE_Context::finish ( bool sweepPool = true )

Block until any outstanding kernel or memory transfers on the main CommandQueue have executed. If sweepPool is true, the context's CE_MemoryPool will sweep for any buffers that were in use when their CE_Grid's went out of scope, but that were still active in kernels.

void CE_Context::get1DRanges	(	const cl::Kernel &	k,
		size_t	items,
		cl::NDRange &	g,
		cl::NDRange &	l
	)

Get the suggested global and local ranges for the given 1-D kernel over the specified number of items.

size_t CE_Context::getAddressableMemory ( ) const

This function returns the total size of addressable compute memory for the current device.

static void CE_Context::getAllPlatformsInfo ( UT_WorkBuffer & buffer )

static

cl::Context CE_Context::getCLContext ( ) const

inline

Returns the underlying cl::Context object.

Definition at line 107 of file CE_Context.h.

static CE_Context* CE_Context::getContext	(	bool	gl_shared = `true`,
		bool	shared_fallback = `true`
	)

static

Returns a pointer to the singleton CE_Context object. This function attempts to initialize OpenCL if it has not yet been. gl_shared should be true if the context will be expected to interoperate with the OpenGL context. If both gl_shared and shared_fallback are true, then the function will try to make an unshared context in case the shared context fails to create.

static int CE_Context::getDefaultDevice	(	cl_device_type	t,
		const UT_Array< DeviceDescriptor > &	devices
	)

static

Get an index to the preferred/default device for the specified device type and the list of available devices.

cl::Device CE_Context::getDevice ( ) const

inline

Returns the OpenCL Device object.

Definition at line 114 of file CE_Context.h.

bool CE_Context::getDeviceInfo	(	const char *	flag,
		fpreal &	result
	)

Queries the current device give the specified flag using clGetDeviceInfo, used by ocldeviceinfo EXPR function. Returns false for unrecognized flag.

template<class T >

static bool CE_Context::getDeviceInfoRestricted	(	cl_device_id	device,
		cl_uint	flag,
		T &	result
	)

static

static void CE_Context::getDevices	(	UT_Array< DeviceDescriptor > &	,
		cl_device_type	t
	)

static

Get the vector of available devices of the given type.

void CE_Context::getDeviceUUID ( cl_uchar(&) uuid[CL_UUID_SIZE_KHR] )

Writes the OpenCL device UUID. Check that supportsUUID() returns true before trying to query the UUID.

void CE_Context::getDriverUUID ( cl_uchar(&) uuid[CL_UUID_SIZE_KHR] )

Writes the OpenCL driver UUID. Check that supportsUUID() returns true before trying to query the UUID.

static void CE_Context::getExtendedInfo	(	const cl::Device &	device,
		UT_WorkBuffer &	buffer
	)

static

static void CE_Context::getInfo	(	const cl::Device &	device,
		UT_WorkBuffer &	buffer
	)

static

size_t CE_Context::getMaxWorkgroupSize ( const cl::Kernel & k )

Get the maximum workgroup size for the given kernel.

std::vector<size_t> CE_Context::getMaxWorkItemSizes ( )

Get the array of maximum work items along each dimension supported by the compute device.

const UT_Array<FreeFunc>& CE_Context::getMemFreeFuncs ( ) const

inline

Returns the list of registered memory freeing functions.

Definition at line 325 of file CE_Context.h.

fpreal32* CE_Context::getPinnedBuffer ( int64 size )

Return a pointer to pinned (page-locked) host memory. On some devices (Nvidia), using this type of memory for the PCI/E host/device transfers can double the throughput. Will return NULL if the memory can't be allocated, or if the device is not a GPU.

cl::CommandQueue CE_Context::getQueue ( ) const

inline

Returns the cl::Queue object that is used to enqueue OpenCL kernels and memory transfers.

Definition at line 111 of file CE_Context.h.

ceTraceCtx CE_Context::getTraceContext ( ) const

inline

Definition at line 116 of file CE_Context.h.

cl::Buffer CE_Context::getXNoiseData ( )

bool CE_Context::has3DImageWriteSupport ( ) const

inline

Returns true if the OpenCL device supports writing to 3D image objects.

Definition at line 177 of file CE_Context.h.

bool CE_Context::hasDoubleSupport ( ) const

inline

Returns true if the OpenCL device supports double precision.

Definition at line 175 of file CE_Context.h.

bool CE_Context::hasOutOfMemoryFailureHappened ( ) const

inline

Definition at line 279 of file CE_Context.h.

void CE_Context::init	(	cl::Context &	context,
		cl::Device &	device
	)

protected

Initialize the context for the given device.

static void CE_Context::initMainSharedGLContext	(	int	devicetype,
		void *	context,
		void *	display
	)

static

bool CE_Context::isCPU ( ) const

Returns true if the OpenCL device is running on the CPU.

static bool CE_Context::isEnvironmentOverride ( )

static

Returns true if environment variables are set that override preferences.

static bool CE_Context::isGLSharingPossible ( )

static

Returns true if interoperability between CL and GL is possible.

static bool CE_Context::isInitialized ( bool gl_shared = false )

static

Returns whether the singleton CE_Context has been initialized yet. This can be used to test whether OpenCL has been initialized without calling getContext and forcing an attempt at initialization.

bool CE_Context::isValid ( ) const

inline

Returns whether the CE_Context has been successfully initialized.

Definition at line 164 of file CE_Context.h.

cl::Kernel CE_Context::loadKernel	(	const cl::Program &	prog,
		const UT_StringRef &	kernelname
	)

Create an OpenCL kernel named kernelname from the program specified by progname. For some types of devices these kernels will be cached, as kernels can be expensive to create. This is the recommended method for creating kernels.

cl::Kernel CE_Context::loadKernel	(	const char *	progname,
		const UT_StringRef &	kernelname,
		const char *	options = `NULL`
	)

inline

Definition at line 159 of file CE_Context.h.

cl::Program CE_Context::loadProgram	(	const char *	progname,
		const char *	options = `NULL`,
		bool	recompile = `false`
	)

Loads the OpenCL program specified by progname. This functions searches for the file in the HOUDINI_OCL_PATH environment variable. Any compile- time options can be passed in the options parameter. If the program load succeeds, the progname will be cached, using the progrname and options strings together as a hash value lookup. In this way the same OpenCL program can be loaded several times with different compile-time flags.

CE_DelayedOGLBindBuffer* CE_Context::lookupDelayedOGLBindBuffer ( uint id )

static void CE_Context::outputErrorMessage ( const char * errMsg )

static

static void CE_Context::outputWarningMessage ( const char * errMsg )

static

void CE_Context::readBuffer	(	const cl::Buffer &	buf,
		size_t	size,
		void *	p,
		bool	blocking = `true`,
		size_t	offset = `0`
	)

Read the specified number of bytes from the buffer.

uint32 CE_Context::registerDelayedOGLBindBuffer ( CE_DelayedOGLBindBuffer * buffer )

Keep a map buffer to bind at render time The first time a CL::Buffer is created it can be registered to rebing to a OGL vertex buffer at drawing time. The uint returned by the register call can be attached to a detail attribute and the drawing code can convert the CL Buffer to a CL BufferGL.

void CE_Context::registerMemFreeFunc ( FreeFunc func )

Registers a function to be called for freeing memory on allocation failure. Multiple such functions can be registered, and will be called in registration order, until the allocation can be fulfilled. Signature of the function is (int64)->(int64), where the input is how much to attempt to free, and return value is the actual amount freed.

void CE_Context::releaseBuffer ( cl::Buffer && buf )

Release the specified buffer, possibly to the CE_MemoryPool.

void CE_Context::releasePinnedBuffer ( )

protected

Releases the pinned, page-locked memory buffer.

static void CE_Context::reportError ( const cl::Error & err )

static

Standard error reporting for OpenCL exceptions. They should generally take the form:

try
{
     OpenCL calls...
}
catch(cl::Error &err)
{
     CE_Context::reportError(err);
     ///cleanup
}

This will not capture delayed errors, however. Instead you will need to add a callback to intercept them.

void CE_Context::reportUsage ( std::ostream & os ) const

Report memory usage.

static size_t CE_Context::roundUpGroupSize ( size_t gsize )

static

Round up a provided group size to a larger clean one as some driers die with prime-based groups sizes. Less than 1024 is raised to next power of 2, greater is to a multiple of 1024.

static void CE_Context::setErrorCB	(	CE_ErrorCB	callback,
		void *	data
	)

static

void CE_Context::setOutOfMemoryFailure ( bool hasfailed = true )

inline

Marks that an operation has run out of memory, allowing us to report elsewhere.

Definition at line 278 of file CE_Context.h.

bool CE_Context::supportsExternalMemory ( )

Returns true if the context supports the creation of buffers backed by external memory. Mainly for use in sharing buffers with Vulkan.

bool CE_Context::supportsUUID ( )

Returns true if the context supports querying for device and driver UUIDs that are unique across APIs (allowing for example, to match Vulkan device selection). This requires the cl_khr_device_uuid extension.

void CE_Context::unregisterDelayedOGLBindBuffer ( uint32 id )

static bool CE_Context::useHalfNormalDelayedBindBuffer ( )

static

void CE_Context::writeBuffer	(	const cl::Buffer &	buf,
		size_t	size,
		const void *	p,
		bool	blocking = `true`,
		size_t	offset = `0`
	)

Write the specified number of bytes to the buffer.

Member Data Documentation

cl::Context CE_Context::myContext

protected

Definition at line 344 of file CE_Context.h.

UT_Map<uint32,CE_DelayedOGLBindBuffer*> CE_Context::myDelayedOGLBindBuffers

protected

Definition at line 375 of file CE_Context.h.

cl::Device CE_Context::myDevice

protected

Definition at line 348 of file CE_Context.h.

cl::CommandQueue CE_Context::myDeviceQueue

protected

Definition at line 346 of file CE_Context.h.

bool CE_Context::myIsValid

protected

Definition at line 349 of file CE_Context.h.

UT_Map<const _cl_program *, UT_Array<KernelInfo> *> CE_Context::myKernelTable

protected

Definition at line 361 of file CE_Context.h.

UT_Array<FreeFunc> CE_Context::myMemFreeFuncs

protected

List of memory freeing functions (int64 -> int64). These are called upon on allocation failure.

Definition at line 367 of file CE_Context.h.

CE_MemoryPool* CE_Context::myMemPool

protected

Definition at line 363 of file CE_Context.h.

bool CE_Context::myOutOfMemoryFailure

protected

Definition at line 373 of file CE_Context.h.

cl::Buffer CE_Context::myPinnedBuffer

protected

Definition at line 370 of file CE_Context.h.

fpreal32* CE_Context::myPinnedData

protected

Definition at line 371 of file CE_Context.h.

UT_StringMap<cl::Program *> CE_Context::myProgramTable

protected

Definition at line 360 of file CE_Context.h.

cl::CommandQueue CE_Context::myQueue

protected

Definition at line 345 of file CE_Context.h.

bool CE_Context::mySupports3DImageWrites

protected

Definition at line 351 of file CE_Context.h.

bool CE_Context::mySupportsDouble

protected

Definition at line 350 of file CE_Context.h.

ceTraceCtx CE_Context::myTraceCtx

protected

Definition at line 347 of file CE_Context.h.

cl::Buffer CE_Context::myXNoiseData

protected

Definition at line 352 of file CE_Context.h.

void* CE_Context::theGLContext

staticprotected

Definition at line 377 of file CE_Context.h.

int CE_Context::theGLDeviceType

staticprotected

Definition at line 379 of file CE_Context.h.

void* CE_Context::theGLDisplay

staticprotected

Definition at line 378 of file CE_Context.h.

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

CE/CE_Context.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation