Context

Typedefs

typedef struct _IPLContext_t *IPLContext

A context object, which controls low-level operations of Steam Audio.

Typically, a context is specified once during the execution of the client program, before calling any other API functions.

Functions

IPLerror iplContextCreate(IPLContextSettings *settings, IPLContext *context)

Creates a context object.

A context must be created before creating any other API objects.

Parameters:

settings – Pointer to the IPLContextSettings struct that specifies context creation parameters.
context – [out] Handle to the created context object.

Returns:

Status code indicating whether or not the operation succeeded.

IPLContext iplContextRetain(IPLContext context)

Retains an additional reference to a context.

The context will not be destroyed until all references are released.

Parameters:: context – The context to retain a reference to.
Returns:: The additional reference to the context.

void iplContextRelease(IPLContext *context)

Releases a reference to a context.

The context will not be destroyed until all references are released.

Parameters:: context – [in, out] The context to release.

Structures

struct IPLContextSettings

Settings used to create a context object.

Public Members

IPLuint32 version

The API version used by the caller.

Context creation will fail if phonon.dll does not implement a compatible version of the API. Typically, this should be set to STEAMAUDIO_VERSION.

IPLLogFunction logCallback: (Optional) If non-NULL, Steam Audio will call this function to record log messages generated by certain operations.

IPLAllocateFunction allocateCallback: (Optional) If non-NULL, Steam Audio will call this function whenever it needs to allocate memory.

IPLFreeFunction freeCallback: (Optional) If non-NULL, Steam Audio will call this function whenever it needs to free memory.

IPLSIMDLevel simdLevel

The maximum SIMD instruction set level that Steam Audio should use.

Steam Audio automatically chooses the best instruction set to use based on the user’s CPU, but you can prevent it from using certain newer instruction sets using this parameter. For example, with some workloads, AVX512 instructions consume enough power that the CPU clock speed will be throttled, resulting in lower performance than expected. If you observe this in your application, set this parameter to IPL_SIMDLEVEL_AVX2 or lower.

IPLContextFlags flags: Additional flags for modifying the behavior of the created context.

Enumerations

enum IPLLogLevel

Severity levels of log messages generated by Steam Audio.

Values:

enumerator IPL_LOGLEVEL_INFO: A normal, informational message.

enumerator IPL_LOGLEVEL_WARNING

A warning.

The operation that generated this message may not work as expected.

enumerator IPL_LOGLEVEL_ERROR

An error.

The operation that generated this message failed.

enumerator IPL_LOGLEVEL_DEBUG: A detailed message intended for debugging purposes only.

enum IPLSIMDLevel

SIMD instruction sets that Steam Audio can attempt to use.

Values:

enumerator IPL_SIMDLEVEL_SSE2

Intel Streaming SIMD Extensions 2.

Up to 4 simultaneous floating-point operations.

enumerator IPL_SIMDLEVEL_SSE4

Intel Streaming SIMD Extensions 4.2 or older.

Up to 4 simultaneous floating-point operations.

enumerator IPL_SIMDLEVEL_AVX

Intel Advanced Vector Extensions or older.

Up to 8 simultaneous floating-point operations.

enumerator IPL_SIMDLEVEL_AVX2

Intel Advanced Vector Extensions 2 or older.

Up to 8 simultaneous floating-point operations.

enumerator IPL_SIMDLEVEL_AVX512

Intel Advanced Vector Extensions 512 or older.

Up to 16 simultaneous floating-point operations.

enumerator IPL_SIMDLEVEL_NEON

ARM NEON.

Up to 4 simultaneous floating-point operations.

enum IPLContextFlags

Additional flags for modifying the behavior of a Steam Audio context.

Values:

enumerator IPL_CONTEXTFLAGS_VALIDATION

All API functions perform extra validation checks.

NOTE: This imposes a significant performance penalty.

enumerator IPL_CONTEXTFLAGS_FORCE_32BIT: Force this enum to be 32 bits in size.

Callbacks

typedef void (*IPLLogFunction)(IPLLogLevel level, const char *message)

Prototype of a callback that logs a message generated by Steam Audio.

This may be implemented in any suitable way, such as appending to a log file, displaying a dialog box, etc. The default behavior is to print to stdout.

Param level:: The severity level of the message.
Param message:: The message to log.

typedef void *(*IPLAllocateFunction)(IPLsize size, IPLsize alignment)

Prototype of a callback that allocates memory.

This is usually specified to let Steam Audio use a custom memory allocator. The default behavior is to use the OS-dependent aligned version of malloc.

Param size:: The number of bytes to allocate.
Param alignment:: The alignment (in bytes) of the start address of the allocated memory.
Return:: Pointer to the allocated block of memory, or NULL if allocation failed.

typedef void (*IPLFreeFunction)(void *memoryBlock)

Prototype of a callback that frees a block of memory.

This is usually specified when using a custom memory allocator with Steam Audio. The default behavior is to use the OS-dependent aligned version of free.

Param memoryBlock:: Pointer to the block of memory.