QCLContext Class Reference

    #include <QCLContext>

Member Function Documentation

QCLContext::QCLContext ()

Constructs a new OpenCL context object. This constructor is typically followed by calls to setPlatform() and create().

QCLContext::~QCLContext () [virtual]

Destroys this OpenCL context object. If the underlying contextId() has been created, then it will be released.

void QCLContext::barrier ()

Adds a barrier to the active command queue. All commands that were queued before this point must finish before any further commands added after this point are executed.

This function will return immediately and will not block waiting for the commands to finish. Use sync() to block until all queued commands finish.

See also marker() and sync().

void QCLContext::barrier ( const QCLEventList & events )

This is an overloaded function.

Adds a barrier to the active command queue that will prevent future commands from being executed until after all members of events have been signalled.

See also marker().

QCLProgram QCLContext::buildProgramFromBinaries ( const QList<QCLDevice> & devices, const QList<QByteArray> & binaries )

Creates an OpenCL program object from the list of binaries for devices and then builds the program. Returns a null QCLProgram if the program could not be built. The binaries and devices lists must have the same number of elements.

See also createProgramFromBinaries() and buildProgramFromBinaryCode().

QCLProgram QCLContext::buildProgramFromBinaryCode ( const QByteArray & binary )

Creates an OpenCL program object from the supplied binary for defaultDevice() and then builds it. Returns a null QCLProgram if the program could not be built.

This function can only load the binary for a single device. For multiple devices, use createProgramFromBinaries() instead.

See also createProgramFromBinaryCode(), buildProgramFromBinaryFile(), and buildProgramFromBinaries().

QCLProgram QCLContext::buildProgramFromBinaryFile ( const QString & fileName )

Creates an OpenCL program object from the binary contents of the supplied fileName for defaultDevice() and then builds it. Returns a null QCLProgram if the program could not be built.

See also createProgramFromBinaryFile() and buildProgramFromBinaryCode().

QCLProgram QCLContext::buildProgramFromSourceCode ( const QByteArray & sourceCode )

Creates an OpenCL program object from the supplied sourceCode and then builds it. Returns a null QCLProgram if the program could not be built.

See also createProgramFromSourceCode() and buildProgramFromSourceFile().

QCLProgram QCLContext::buildProgramFromSourceFile ( const QString & fileName )

Creates an OpenCL program object from the contents of the supplied fileName and then builds it. Returns a null QCLProgram if the program could not be built.

See also createProgramFromSourceFile() and buildProgramFromSourceCode().

QCLCommandQueue QCLContext::commandQueue ()

Returns the context's active command queue, which will be defaultCommandQueue() if the queue has not yet been set.

See also setCommandQueue() and defaultCommandQueue().

cl_context QCLContext::contextId () const

Returns the native OpenCL context identifier associated with this object.

See also setContextId().

bool QCLContext::create ( QCLDevice::DeviceTypes type = QCLDevice::Default )

Creates a new OpenCL context that matches type. Does nothing if the context has already been created. The default value for type is QCLDevice::Default.

This function will search for the first platform that has a device that matches type. The following code can be used to select devices that match type on a specific platform:

    context.create(QCLDevice::devices(type, platform));

Returns true if the context was created; false otherwise. On error, the status can be retrieved by calling lastError().

See also isCreated(), setContextId(), and release().

bool QCLContext::create ( const QList<QCLDevice> & devices )

Creates a new OpenCL context that matches devices. Does nothing if the context has already been created. All of the devices must be associated with the same platform.

Returns true if the context was created; false otherwise. On error, the status can be retrieved by calling lastError().

See also isCreated(), setContextId(), and release().

QCLBuffer QCLContext::createBufferCopy ( const void * data, size_t size, QCLMemoryObject::Access access )

Creates an OpenCL memory buffer of size bytes in length, with the specified access mode.

The buffer is initialized with a copy of the contents of data. The application's data can be discarded after the buffer is created.

Returns the new OpenCL memory buffer object, or a null object if the buffer could not be created.

See also createBufferDevice(), createBufferHost(), and createVector().

QCLBuffer QCLContext::createBufferDevice ( size_t size, QCLMemoryObject::Access access )

Creates an OpenCL memory buffer of size bytes in length, with the specified access mode.

The memory is created on the device and will not be accessible to the host via a direct pointer. Use createBufferHost() to create a host-accessible buffer.

Returns the new OpenCL memory buffer object, or a null object if the buffer could not be created.

See also createBufferHost(), createBufferCopy(), and createVector().

QCLBuffer QCLContext::createBufferHost ( void * data, size_t size, QCLMemoryObject::Access access )

Creates an OpenCL memory buffer of size bytes in length, with the specified access mode.

If data is not null, then it will be used as the storage for the buffer. If data is null, then a new block of host-accessible memory will be allocated.

Returns the new OpenCL memory buffer object, or a null object if the buffer could not be created.

See also createBufferDevice(), createBufferCopy(), and createVector().

QCLCommandQueue QCLContext::createCommandQueue ( cl_command_queue_properties properties, const QCLDevice & device = QCLDevice() )

Creates a new command queue on this context for device with the specified properties. If device is null, then defaultDevice() will be used instead.

Unlike defaultCommandQueue(), this function will create a new queue every time it is called. The queue will be deleted when the last reference to the returned object is removed.

See also defaultCommandQueue() and lastError().

QCLImage2D QCLContext::createImage2DCopy ( const QCLImageFormat & format, const void * data, const QSize & size, QCLMemoryObject::Access access, int bytesPerLine = 0 )

Creates a 2D OpenCL image object with the specified format, size, and access mode. If bytesPerLine is not zero, it indicates the number of bytes between lines in data.

The image is initialized with a copy of the contents of data. The application's data can be discarded after the image is created.

Returns the new 2D OpenCL image object, or a null object if the image could not be created.

See also createImage2DDevice() and createImage2DHost().

QCLImage2D QCLContext::createImage2DCopy ( const QImage & image, QCLMemoryObject::Access access )

Creates a 2D OpenCL image object from image with the specified access mode.

The OpenCL image is initialized with a copy of the contents of image. The application's image can be discarded after the OpenCL image is created.

Returns the new 2D OpenCL image object, or a null object if the image could not be created. If image has a zero size, this function will return a null QCLImage2D object.

See also createImage2DDevice() and createImage2DHost().

QCLImage2D QCLContext::createImage2DDevice ( const QCLImageFormat & format, const QSize & size, QCLMemoryObject::Access access )

Creates a 2D OpenCL image object with the specified format, size, and access mode.

The image memory is created on the device and will not be accessible to the host via a direct pointer. Use createImage2DHost() to create a host-accessible image.

Returns the new 2D OpenCL image object, or a null object if the image could not be created.

See also createImage2DHost() and createImage2DCopy().

QCLImage2D QCLContext::createImage2DHost ( const QCLImageFormat & format, void * data, const QSize & size, QCLMemoryObject::Access access, int bytesPerLine = 0 )

Creates a 2D OpenCL image object with the specified format, size, and access mode. If bytesPerLine is not zero, it indicates the number of bytes between lines in data.

If data is not null, then it will be used as the storage for the image. If data is null, then a new block of host-accessible memory will be allocated.

Returns the new 2D OpenCL image object, or a null object if the image could not be created.

See also createImage2DDevice() and createImage2DCopy().

QCLImage2D QCLContext::createImage2DHost ( QImage * image, QCLMemoryObject::Access access )

Creates a 2D OpenCL image object from image with the specified access mode.

OpenCL kernels that access the image will read and write the QImage contents directly.

Returns the new 2D OpenCL image object, or a null object if the image could not be created. If image is null or has a zero size, this function will return a null QCLImage2D object.

See also createImage2DDevice() and createImage2DCopy().

QCLImage3D QCLContext::createImage3DCopy ( const QCLImageFormat & format, const void * data, int width, int height, int depth, QCLMemoryObject::Access access, int bytesPerLine = 0, int bytesPerSlice = 0 )

Creates a 3D OpenCL image object with the specified format, width, height, depth, and access mode. If bytesPerLine is not zero, it indicates the number of bytes between lines in data. If bytesPerSlice is not zero, it indicates the number of bytes between slices in data.

The image is initialized with a copy of the contents of data. The application's data can be discarded after the image is created.

Returns the new 3D OpenCL image object, or a null object if the image could not be created.

See also createImage3DDevice() and createImage3DHost().

QCLImage3D QCLContext::createImage3DDevice ( const QCLImageFormat & format, int width, int height, int depth, QCLMemoryObject::Access access )

Creates a 3D OpenCL image object with the specified format, width, height, depth, and access mode.

The image memory is created on the device and will not be accessible to the host via a direct pointer. Use createImage3DHost() to create a host-accessible image.

Returns the new 3D OpenCL image object, or a null object if the image could not be created.

See also createImage3DHost() and createImage3DCopy().

QCLImage3D QCLContext::createImage3DHost ( const QCLImageFormat & format, void * data, int width, int height, int depth, QCLMemoryObject::Access access, int bytesPerLine = 0, int bytesPerSlice = 0 )

Creates a 3D OpenCL image object with the specified format, width, height, depth, and access mode. If bytesPerLine is not zero, it indicates the number of bytes between lines in data. If bytesPerSlice is not zero, it indicates the number of bytes between slices in data.

If data is not null, then it will be used as the storage for the image. If data is null, then a new block of host-accessible memory will be allocated.

Returns the new 3D OpenCL image object, or a null object if the image could not be created.

See also createImage3DDevice() and createImage3DCopy().

QCLProgram QCLContext::createProgramFromBinaries ( const QList<QCLDevice> & devices, const QList<QByteArray> & binaries )

Creates an OpenCL program object from the list of binaries for devices. The binaries and devices lists must have the same number of elements.

See also createProgramFromBinaryCode() and createProgramFromBinaryFile().

QCLProgram QCLContext::createProgramFromBinaryCode ( const QByteArray & binary )

Creates an OpenCL program object from binary for defaultDevice().

This function can only load the binary for a single device. For multiple devices, use createProgramFromBinaries() instead.

See also createProgramFromBinaryFile() and createProgramFromBinaries().

QCLProgram QCLContext::createProgramFromBinaryFile ( const QString & fileName )

Creates an OpenCL program object from the binary data in fileName for defaultDevice().

See also createProgramFromBinaryCode() and createProgramFromBinaries().

QCLProgram QCLContext::createProgramFromSourceCode ( const QByteArray & sourceCode )

Creates an OpenCL program object from the supplied sourceCode.

See also createProgramFromSourceFile() and buildProgramFromSourceCode().

QCLProgram QCLContext::createProgramFromSourceFile ( const QString & fileName )

Creates an OpenCL program object from the contents of the specified fileName.

See also createProgramFromSourceCode() and buildProgramFromSourceFile().

QCLSampler QCLContext::createSampler ( bool normalizedCoordinates, QCLSampler::AddressingMode addressingMode, QCLSampler::FilterMode filterMode )

Creates a sampler for this context from the arguments normalizedCoordinates, addressingMode, and filterMode.

QCLUserEvent QCLContext::createUserEvent ()

Creates a user event. Returns null if user events are not supported.

User events are a feature of OpenCL 1.1 which allows an application to insert a marker into the command queue. Commands that depend upon the marker will not be executed until the application triggers the user event with QCLUserEvent::setFinished().

QCLVector<T> QCLContext::createVector ( int size, QCLMemoryObject::Access access = QCLMemoryObject::ReadWrite )

Creates a host-accessible vector of size elements of type T on this context and returns it. The elements will be initially in an undefined state.

Note that the access mode indicates how the OpenCL device (e.g. GPU) will access the vector. When the host maps the vector, it will always be mapped as ReadWrite.

See also createBufferHost().

QCLCommandQueue QCLContext::defaultCommandQueue ()

Returns the default command queue for defaultDevice(). If the queue has not been created, it will be created with the default properties of in-order execution of commands, and profiling disabled.

Use createCommandQueue() to create a queue that supports out-of-order execution or profiling. For example:

    QCLCommandQueue queue =
        context.createCommandQueue
            (CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE);
    context.setCommandQueue(queue);

See also commandQueue(), createCommandQueue(), and lastError().

QCLDevice QCLContext::defaultDevice () const

Returns the default device in use by this context, which is typically the first element of the devices() list; or a null QCLDevice if the context has not been created yet.

See also devices().

QList<QCLDevice> QCLContext::devices () const

Returns the list of devices that are in use by this context. If the context has not been created, returns an empty list.

See also defaultDevice().

QString QCLContext::errorName ( cl_int code ) [static]

Returns the name of the supplied OpenCL error code. For example, CL_SUCCESS, CL_INVALID_CONTEXT, etc.

See also lastError().

void QCLContext::finish ()

Blocks until all previously queued commands on the active command queue have finished execution.

See also flush().

void QCLContext::flush ()

Flushes all previously queued commands to the device associated with the active command queue. The commands are delivered to the device, but no guarantees are given that they will be executed.

See also finish().

bool QCLContext::isCreated () const

Returns true if the underlying OpenCL contextId() has been created; false otherwise.

See also create() and setContextId().

cl_int QCLContext::lastError () const

Returns the last OpenCL error that occurred while executing an operation on this context or any of the objects created by the context. Returns CL_SUCCESS if the last operation succeeded.

See also setLastError() and errorName().

QCLEvent QCLContext::marker ()

Returns a marker event for the active command queue. The event will be signalled when all commands that were queued before this point have finished.

See also barrier() and sync().

void QCLContext::release () [virtual]

Releases this context; destroying it if the reference count is zero. Does nothing if the context has not been created or is already released.

See also create().

void QCLContext::setCommandQueue ( const QCLCommandQueue & queue )

Sets the context's active command queue. If queue is null, then defaultCommandQueue() will be used.

See also commandQueue() and defaultCommandQueue().

void QCLContext::setContextId ( cl_context id )

Sets the native OpenCL context identifier associated with this object to id.

This function will call clRetainContext() to increase the reference count on id. If the identifier was previously set to something else, then clReleaseContext() will be called on the previous value.

See also contextId() and create().

void QCLContext::setLastError ( cl_int error )

Sets the last error code to error.

See also lastError() and errorName().

QList<QCLImageFormat> QCLContext::supportedImage2DFormats ( cl_mem_flags flags ) const

Returns the list of supported 2D image formats for processing images with the specified memory flags.

See also supportedImage3DFormats().

QList<QCLImageFormat> QCLContext::supportedImage3DFormats ( cl_mem_flags flags ) const

Returns the list of supported 3D image formats for processing images with the specified memory flags.

See also supportedImage2DFormats().

void QCLContext::sync ()

Synchronizes the host against the active command queue. This function will block until all currently queued commands have finished execution.