FMOD Engine User Manual 2.03

5. White Papers | Handle System

Handle System

The Studio API and Core API return pointers to types. Some of these types are actually implemented as an underlying handle, but represent the handle data as a pointer type. This section explains the underlying representation and lifetime of these objects.

General Information

All FMOD types, whether they are represented internally via pointer or handle, look like a pointer type. No matter the type, a null pointer will never be returned as a valid result, but it is not safe to assume anything else about the pointer value. Do not assume that the pointer value falls in any particular address range, or that it has any zero bits in the bottom of the pointer value address.

All FMOD types are equivalent for both the C and C++ API. It is possible to cast between the appropriate types by re-interpreting the pointer type directly.

Core API Channels

FMOD Channels are returned to you as a pointer, but actually consist of 32 bits of packed integer handle data. This allows Channels to be re-used safely.

If a Channel is stopped with ChannelControl::stop or ends naturally, the Channel handle will become invalid and return FMOD_ERR_INVALID_HANDLE.

If not enough Channels are specified at System::init and an existing virtual Channel is stolen by the FMOD priority system, then the handle to the stolen Channel becomes 'invalid'. Subsequent Channel commands to a stolen handle will return FMOD_ERR_CHANNEL_STOLEN.

Core API Channel Groups

FMOD ChannelGroups are returned to you directly as a pointer. Once you destroy a ChannelGroup, it is no longer safe to call FMOD functions with that pointer.

Core API System

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.

Studio API Types

Studio API types are returned as pointers, but actually consist of packed handle data. If the underlying type has been destroyed then the API will return FMOD_ERR_INVALID_HANDLE. An example of this would be unloading a Studio::Bank and then referencing a Studio::EventDescription belonging to that bank.