# 1. Welcome to FMOD API | New in FMOD API 2.02

## What's New in 2.02?

This section describes the major features introduced in the 2.02 release. See the Detailed Revision History for information regarding each patch release.

### Minimum / Maximum Distance

Events (rather than spatializer DSPs) now encapsulate the functionality of minimum and maximum distance.

As a result, `Studio::EventDescription::getMinimumDistance` and `Studio::EventDescription::getMaximumDistance` have been removed. Those APIs which returned values reported by FMOD spatializers have been replaced with the new Studio::EventDescription::getMinMaxDistance. The new API returns the initial values specified for minimum and maximum distance as set in FMOD Studio. If the minimum or maximum distance have been automated you can query the runtime value per EventInstance using Studio::EventInstance::getMinMaxDistance.

DSP plugins interested in receiving the new Event level min/max distance information can now add a data parameter of data type FMOD_DSP_PARAMETER_ATTENUATION_RANGE. For compatibility with the old behavior of each spatializer DSP having its own min/max distance, FMOD_DSP_TYPE_PAN and FMOD_DSP_TYPE_OBJECTPAN now have override properties that ignore the Event level values. Resonance Audio has been updated to use the new method, so if the old method is desired please use the Resonance plugin from v2.01.xx.

Using the new Event level min/max we are able to provide a new built-in parameter, FMOD_STUDIO_PARAMETER_AUTOMATIC_DISTANCE_NORMALIZED, that presents the range from min to max as 0 to 1.

### Labeled Parameters

Labeled or enumerated parameters have existed in FMOD Studio for a while, however until now they have been unavailable in the API.

With this release we have introduced a way to query all of the labels associated with one of these parameters. You can fetch labels for global parameters via Studio::System::getParameterLabelByID or Studio::System::getParameterLabelByName and you can fetch labels for local parameter via Studio::EventDescription::getParameterLabelByID, Studio::EventDescription::getParameterLabelByName or Studio::EventDescription::getParameterLabelByIndex. The main purpose of this API is to expose these strings to your level editor for ease of value selection. We recommend still storing the related index in you level data for best performance at runtime when setting enumerated parameters.

Despite this advice, we also provide some new APIs for setting enumerated parameter with their string value. For global parameters you can use Studio::System::setParameterByIDWithLabel or Studio::System::setParameterByNameWithLabel to lookup the parameter by ID or name respectively then set the value string. For local parameters you can use Studio::EventInstance::setParameterByIDWithLabel or Studio::EventInstance::setParameterByNameWithLabel to lookup the parameter by ID or name respectively then set the value string.

### Ports

To accompany the addition of Ports into the FMOD Studio tool an additional API was necessary for setting the port index. In the Core API, System::attachChannelGroupToPort would accept both a port type and an index in order to disambiguate between multiple ports targeting the same device type, for example controller speakers. In the Studio API the port type is set on a bus at design time, for ports that require disambiguation you can now use Studio::Bus::setPortIndex to provide that value and Studio::Bus::getPortIndex to query it back.

With this change we have now unified all port types previously spread over platform specific APIs in the form of `FMOD_<PLATFORM>_PORT_TYPE`. Now you can find the complete set in the FMOD_PORT_TYPE enumeration with information of availability in each platforms getting started guide.

### Platform Notes

- Added support for Windows N versions by separating MediaFoundation into a separate DLL
- Linux is now built with LLVM / Clang 10, lifting 32bit min-spec to ARMv7 (with NEON) and adding 64bit support
- Android minimum API version raised to 16 for 32bit
- Renamed PS5 specific APIs and headers from codename to official name

### API Differences

APIs that have changed with this release that haven't been called out explicitly above.

#### Studio API

- Renamed `Studio::EventInstance::triggerCue` to Studio::EventInstance::keyOff
- Renamed `Studio::EventDescription::hasCue` to Studio::EventDescription::hasSustainPoint
- Modified FMOD_STUDIO_PARAMETER_DESCRIPTION to add `guid`
- Modified Studio::System::getCPUUsage to take `usage_core` as FMOD_CPU_USAGE
- Modified FMOD_STUDIO_CPU_USAGE to remove `dspusage`, `streamusage`, `geometryusage` and `updateusage`
- Modified FMOD_STUDIO_CPU_USAGE to rename `studiousage` to `update`

#### Core API

- Added FMOD_CPU_USAGE
- Removed `System::getCPUUsageEx`
- Modified System::getCPUUsage to take `usage` as FMOD_CPU_USAGE
- Modified the type of FMOD_PORT_TYPE
- Modified the type of FMOD_THREAD_AFFINITY
- Modified the value of FMOD_THREAD_AFFINITY_GROUP_DEFAULT, FMOD_THREAD_AFFINITY_GROUP_A, FMOD_THREAD_AFFINITY_GROUP_B and FMOD_THREAD_AFFINITY_GROUP_C
- Modified System_Create to take `headerversion`

#### Output Plugin API

- Removed `FMOD_OUTPUT_METHOD_POLLING`
- Removed `FMOD_OUTPUT_GETPOSITION_CALLBACK`, `FMOD_OUTPUT_LOCK_CALLBACK` and `FMOD_OUTPUT_UNLOCK_CALLBACK`
- Modified FMOD_OUTPUT_DESCRIPTION to remove `getposition`, `lock` and `unlock`
- Modified FMOD_OUTPUT_INIT_CALLBACK to allow output via `dspnumbuffers`
- Modified FMOD_OUTPUT_INIT_CALLBACK to take `dspnumadditionalbuffers`
- Modified the value of FMOD_OUTPUT_PLUGIN_VERSION
- Modified the value of FMOD_OUTPUT_METHOD_MIX_BUFFERED

#### Codec Plugin API

- Added FMOD_CODEC_STATE_FUNCTIONS
- Added FMOD_CODEC_PLUGIN_VERSION
- Added FMOD_CODEC_SEEK_METHOD with `SET`, `CURRENT` and `END` values
- Added FMOD_CODEC_ALLOC_FUNC, FMOD_CODEC_FREE_FUNC and FMOD_CODEC_LOG_FUNC
- Added FMOD_CODEC_FILE_READ_FUNC, FMOD_CODEC_FILE_SEEK_FUNC, FMOD_CODEC_FILE_TELL_FUNC and FMOD_CODEC_FILE_SIZE_FUNC
- Added `FMOD_CODEC_METADATA`, `FMOD_CODEC_ALLOC`, `FMOD_CODEC_FREE`, `FMOD_CODEC_LOG`, `FMOD_CODEC_FILE_READ`, `FMOD_CODEC_FILE_SEEK`, `FMOD_CODEC_FILE_TELL`, `FMOD_CODEC_FILE_SIZE`
- Removed `FMOD_CODEC_WAVEFORMAT_VERSION`
- Modified FMOD_CODEC_DESCRIPTION to add `apiversion`
- Modified FMOD_CODEC_STATE to remove `filehandle`, `filesize`, `fileread`, `fileseek`, `metadata`, `waveformatversion`
- Modified FMOD_CODEC_STATE to add `functions`

#### FSBank API

- Modified FSBANK_FORMAT to remove `FSBANK_FORMAT_PCM_BIGENDIAN` and `FSBANK_FORMAT_AT9_PSVITA` and `FSBANK_FORMAT_AT9_PS4`
- Modified FSBANK_FORMAT to add FSBANK_FORMAT_AT9

## What's new since 2.01 initial release?

This section describes any major changes that occurred in 2.01.xx leading up to the release of 2.02.

### Platforms

- Added Apple Silicon, PS5 and Game Core platforms
- Added microphone recording support to Stadia
- Optimized convolution reverb performance and memory usage

### API differences

APIs that have changed with this release that haven't been called out explicitly above.

#### Studio API

- Added FMOD_STUDIO_SYSTEM_CALLBACK_LIVEUPDATE_CONNECTED and FMOD_STUDIO_SYSTEM_CALLBACK_LIVEUPDATE_DISCONNECTED
- Added Studio::EventDescription::isDopplerEnabled
- Modified FMOD_STUDIO_PARAMETER_FLAGS to add `FMOD_STUDIO_PARAMETER_DISCRETE`

#### Core API

- Added FMOD_SYSTEM_CALLBACK_OUTPUTUNDERRUN
- Added FMOD_SYSTEM_CALLBACK_DEVICEREINITIALIZE
- Added FMOD_SYSTEM_CALLBACK_BUFFEREDNOMIX
- Added System::getDSPInfoByType