OpenCL

Typedefs

typedef struct _IPLOpenCLDeviceList_t *IPLOpenCLDeviceList

Provides a list of OpenCL devices available on the user’s system.

Use this to enumerate the available OpenCL devices, inspect their capabilities, and select the most suitable one for your application’s needs.

typedef struct _IPLOpenCLDevice_t *IPLOpenCLDevice

Application-wide state for OpenCL.

An OpenCL device must be created before using any of Steam Audio’s Radeon Rays or TrueAudio Next functionality. In terms of the OpenCL API, this object encapsulates a cl_context object, along with up to 2 cl_command_queue objects.

Functions

IPLerror iplOpenCLDeviceListCreate(IPLContext context, IPLOpenCLDeviceSettings *settings, IPLOpenCLDeviceList *deviceList)

Creates an OpenCL device list.

This involves listing all available OpenCL devices on the user’s system.

Parameters

  • context – The context used to initialize Steam Audio.

  • settings – The requirements that all listed OpenCL devices must satisfy.

  • deviceList – [out] The created OpenCL device list.

Returns

Status code indicating whether or not the operation succeeded.

IPLOpenCLDeviceList iplOpenCLDeviceListRetain(IPLOpenCLDeviceList deviceList)

Retains an additional reference to an OpenCL device list.

Parameters

deviceList – The OpenCL device list to retain a reference to.

Returns

The additional reference to the OpenCL device list.

void iplOpenCLDeviceListRelease(IPLOpenCLDeviceList *deviceList)

Releases a reference to an OpenCL device list.

Parameters

deviceList – The OpenCL device list to release a reference to.

IPLint32 iplOpenCLDeviceListGetNumDevices(IPLOpenCLDeviceList deviceList)
Parameters

deviceList – The OpenCL device list.

Returns

The number of devices in an OpenCL device list.

void iplOpenCLDeviceListGetDeviceDesc(IPLOpenCLDeviceList deviceList, IPLint32 index, IPLOpenCLDeviceDesc *deviceDesc)

Retrieves information about a specific device in an OpenCL device list.

Parameters

  • deviceList – The OpenCL device list.

  • index – The index of the device within the list.

  • deviceDesc – [out] A descriptor for the properties of the specified OpenCL device.

IPLerror iplOpenCLDeviceCreate(IPLContext context, IPLOpenCLDeviceList deviceList, IPLint32 index, IPLOpenCLDevice *device)

Creates an OpenCL device.

The device is specified as an index into an OpenCL device list.

Parameters

  • context – The context used to initialize Steam Audio.

  • deviceList – The OpenCL device list.

  • index – The index of the device within the list.

  • device – [out] The created OpenCL device.

Returns

Status code indicating whether or not the operation succeeded.

IPLerror iplOpenCLDeviceCreateFromExisting(IPLContext context, void *convolutionQueue, void *irUpdateQueue, IPLOpenCLDevice *device)

Creates an OpenCL device from an existing OpenCL device created by your application.

Steam Audio will use up to two command queues that you provide for enqueuing OpenCL computations.

Parameters

  • context – The context used to initialize Steam Audio.

  • convolutionQueue – The cl_command_queue to use for enqueueing convolution work.

  • irUpdateQueue – The cl_command_queue to use for enqueueing IR update work.

  • device – [out] The created OpenCL device.

Returns

Status code indicating whether or not the operation succeeded.

IPLOpenCLDevice iplOpenCLDeviceRetain(IPLOpenCLDevice device)

Retains an additional reference to an OpenCL device.

Parameters

device – The OpenCL device to retain a reference to.

Returns

The additional reference to the OpenCL device.

void iplOpenCLDeviceRelease(IPLOpenCLDevice *device)

Releases a reference to an OpenCL device.

Parameters

device – The OpenCL device to release a reference to.

Structures

struct IPLOpenCLDeviceSettings

Specifies requirements that an OpenCL device must meet in order to be considered when listing OpenCL devices.

Public Members

IPLOpenCLDeviceType type

The type of device.

Set to IPL_OPENCLDEVICETYPE_ANY to consider all available devices.

IPLint32 numCUsToReserve

The number of GPU compute units (CUs) that should be reserved for use by Steam Audio.

If set to a non-zero value, then a GPU will be included in the device list only if it can reserve at least this many CUs. Set to 0 to indicate that Steam Audio can use the entire GPU, in which case all available GPUs will be considered.

Ignored if type is IPL_OPENCLDEVICETYPE_CPU.

IPLfloat32 fractionCUsForIRUpdate

The fraction of reserved CUs that should be used for impulse response (IR) update.

IR update includes: a) ray tracing using Radeon Rays to simulate sound propagation, and/or b) pre-transformation of IRs for convolution using TrueAudio Next. Steam Audio will only list GPU devices that are able to subdivide the reserved CUs as per this value. The value must be between 0 and 1.

For example, if numCUsToReserve is 8, and fractionCUsForIRUpdate is 0.5f, then 4 CUs will be used for IR update and 4 CUs will be used for convolution. Below are typical scenarios:

  • Using only TrueAudio Next. Set fractionCUsForIRUpdate to 0.5f. This ensures that reserved CUs are available for IR update as well as convolution.

  • Using TrueAudio Next and Radeon Rays for real-time simulation and rendering. Choosing fractionCUsForIRUpdate may require some experimentation to utilize reserved CUs optimally. You can start by setting fractionCUsForIRUpdate to 0.5f. However, if IR calculation has high latency with these settings, increase fractionCUsForIRUpdate to use more CUs for ray tracing.

  • Using only Radeon Rays. Set fractionCUsForIRUpdate to 1, to make sure all the reserved CUs are used for ray tracing. If using Steam Audio for preprocessing (e.g. baking reverb), then consider setting numCUsToReserve to 0 to use the entire GPU for accelerated ray tracing.

Ignored if type is IPL_OPENCLDEVICETYPE_CPU or numCUsToReserve is 0.

IPLbool requiresTAN

If IPL_TRUE, then the GPU device must support TrueAudio Next.

It is not necessary to set this to IPL_TRUE if numCUsToReserve or fractionCUsForIRUpdate are set to non-zero values.

struct IPLOpenCLDeviceDesc

Describes the properties of an OpenCL device.

This information can be used to select the most suitable device for your application.

Public Members

void *platform

The OpenCL platform id.

Can be cast to cl_platform_id.

IPLstring platformName

The OpenCL platform name.

IPLstring platformVendor

The OpenCL platform vendor’s name.

IPLstring platformVersion

The OpenCL platform version.

void *device

The OpenCL device id.

Can be cast to cl_device_id.

IPLstring deviceName

The OpenCL device name.

IPLstring deviceVendor

The OpenCL device vendor’s name.

IPLstring deviceVersion

The OpenCL device version.

IPLOpenCLDeviceType type

The type of OpenCL device.

IPLint32 numConvolutionCUs

The number of CUs reserved for convolution.

May be 0 if CU reservation is not supported.

IPLint32 numIRUpdateCUs

The number of CUs reserved for IR update.

May be 0 if CU reservation is not supported.

IPLint32 granularity

The CU reservation granularity.

CUs can only be reserved on this device in multiples of this number.

IPLfloat32 perfScore

A relative performance score of a single CU of this device.

Only applicable to supported AMD GPUs.

Enumerations

enum IPLOpenCLDeviceType

The type of devices to include when listing OpenCL devices.

Values:

enumerator IPL_OPENCLDEVICETYPE_ANY

List both CPU and GPU devices.

enumerator IPL_OPENCLDEVICETYPE_CPU

Only list CPU devices.

enumerator IPL_OPENCLDEVICETYPE_GPU

Only list GPU devices.