HRTF

Typedefs

typedef struct _IPLHRTF_t *IPLHRTF

A Head-Related Transfer Function (HRTF).

HRTFs describe how sound from different directions is perceived by a each of a listener’s ears, and are a crucial component of spatial audio. Steam Audio includes a built-in HRTF, while also allowing developers and users to import their own custom HRTFs.

Functions

IPLerror iplHRTFCreate(IPLContext context, IPLAudioSettings *audioSettings, IPLHRTFSettings *hrtfSettings, IPLHRTF *hrtf)

Creates an HRTF.

Calling this function is somewhat expensive; avoid creating HRTF objects in your audio thread at all if possible.

This function is not thread-safe. Do not simultaneously call it from multiple threads.

Parameters
  • context – The context used to initialize Steam Audio.

  • audioSettings – Global audio processing settings.

  • hrtfSettings – The settings used to create the HRTF object.

  • hrtf – [out] The created HRTF object.

Returns

Status code indicating whether or not the operation succeeded.

IPLHRTF iplHRTFRetain(IPLHRTF hrtf)

Retains an additional reference to an HRTF object.

Parameters

hrtf – The HRTF object to retain a reference to.

Returns

The additional reference to the HRTF object.

void iplHRTFRelease(IPLHRTF *hrtf)

Releases a reference to an HRTF object.

Parameters

hrtf – The HRTF object to release a reference to.

Structures

struct IPLHRTFSettings

Settings used to create an HRTF object.

Public Members

IPLHRTFType type

The type of HRTF to create.

const char *sofaFileName

SOFA file from which to load HRTF data.

Either sofaFileName or sofaData should be non-NULL. Only for IPL_HRTFTYPE_SOFA.

const IPLuint8 *sofaData

Pointer to a buffer containing SOFA file data from which to load HRTF data.

Either sofaFileName or sofaData should be non-NULL. Only for IPL_HRTFTYPE_SOFA.

int sofaDataSize

Size (in bytes) of the buffer pointed to by sofaData.

Only for IPL_HRTFTYPE_SOFA.

float volume

Volume correction factor to apply to the loaded HRTF data.

A value of 1.0 means the HRTF data will be used without any change.

IPLHRTFNormType normType

Normalization setting.

No normalization will be applied when choosing IPL_HRTFNORMTYPE_NONE.

Enumerations

enum IPLHRTFType

The type of HRTF to use.

Values:

enumerator IPL_HRTFTYPE_DEFAULT

The built-in HRTF.

enumerator IPL_HRTFTYPE_SOFA

An HRTF loaded from a SOFA file.

enum IPLHRTFNormType

Volume normalization types to use.

Values:

enumerator IPL_HRTFNORMTYPE_NONE

No normalization.

enumerator IPL_HRTFNORMTYPE_RMS

Root-mean squared normalization.

Normalize HRTF volume to ensure similar volume from all directions based on root-mean-square value of each HRTF.