3. Core API Getting Started

This chapter describes how to start up, configure, run, and shut down the FMOD Engine using only the Core API. It frequently references concepts explained in the Core API: Key Concepts chapter.

At the most basic level, all that is needed to configure the Core API is creating the System object and calling System::init on it. The sound card can be manually selected using the System::setDriver function. More settings can be configured, such as the mixing rate of the FMOD system, the resampling method, or the speaker mode with System::setSoftwareFormat. Modifying the mixer settings only adjusts the internal mixing format; at the end, the audio stream is always converted to the settings that are set by the player (e.g.: the settings in the control panel in Windows, or the standard 7.1/48khz output mode on Xbox One or PS4).

3.1 Initializing the Core API

The Core API can be used without needing to use the Studio API at all. Using the Core API gives access to the fundamental abilities of loading and playing sounds, creating DSP effects, setting up ChannelGroups, and setting sample-accurate fade points and start/stop times. However, when just using the Core API, it is not possible to load FMOD Studio banks or load and play events that sound artists have designed in FMOD Studio. To initialize the Core API directly:

FMOD_RESULT result;
FMOD::System *system = NULL;

result = FMOD::System_Create(&system);      // Create the main system object.
if (result != FMOD_OK)
{
    printf("FMOD error! (%d) %s\n", result, FMOD_ErrorString(result));
    exit(-1);
}

result = system->init(512, FMOD_INIT_NORMAL, 0);    // Initialize FMOD.
if (result != FMOD_OK)
{
    printf("FMOD error! (%d) %s\n", result, FMOD_ErrorString(result));
    exit(-1);
}

FMOD System object is returned to you directly as a pointer. Once you destroy the Core API System, it is no longer safe to call FMOD functions with that pointer.

The Core API can be customized with advanced settings by calling System::setAdvancedSettings before initialization.

3.2 Configuring the Core API

The output hardware, FMOD's resource usage, and other types of configuration options can be set if you desire behavior differing from the default. These are generally called before System::init. For more information about these, see System::setAdvancedSettings, Studio::System::setAdvancedSettings.

3.3 Updating the FMOD Engine

The FMOD Engine should be ticked once per game update. To tick it when using the Core API, call System::update. (If you're using the Studio API, you should instead call Studio::System::update.)

3.4 Shutting Down the FMOD Engine

To shut down the Core API, call System::release.