9. Plug-in API Reference | Output

An interface that manages output plug-ins.

Object 3D:

• FMOD_OUTPUT_OBJECT3DINFO Output 3D Object Info.

• FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK Output 3D Object alloc callback.
• FMOD_OUTPUT_OBJECT3DFREE_CALLBACK Output 3D Object free callback.
• FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK Output 3D Object get info callback.
• FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK Output 3D Object update callback.

General:

• FMOD_OUTPUT_DESCRIPTION Output description.
• FMOD_OUTPUT_STATE Output object state passed into every callback provides access to plug-in developers data and system functionality.

• FMOD_OUTPUT_CLOSE_CALLBACK Output close callback.
• FMOD_OUTPUT_CLOSEPORT_CALLBACK Output close port callback.
• FMOD_OUTPUT_DEVICELISTCHANGED_CALLBACK Output device list change callback.
• FMOD_OUTPUT_GETDRIVERINFO_CALLBACK Output get driver info callback.
• FMOD_OUTPUT_GETHANDLE_CALLBACK Output get output handle callback.
• FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK Output get number of drivers callback.
• FMOD_OUTPUT_INIT_CALLBACK Output initialization callback.
• FMOD_OUTPUT_MIXER_CALLBACK Output mixer callback.
• FMOD_OUTPUT_OPENPORT_CALLBACK Output open port callback.
• FMOD_OUTPUT_START_CALLBACK Output start callback.
• FMOD_OUTPUT_STOP_CALLBACK Output stop callback.
• FMOD_OUTPUT_UPDATE_CALLBACK Output update callback.

• FMOD_OUTPUT_ALLOC_FUNC Output allocate memory function.
• FMOD_OUTPUT_COPYPORT_FUNC Output copy port function.
• FMOD_OUTPUT_FREE_FUNC Output free memory function.
• FMOD_OUTPUT_LOG_FUNC Output log function.
• FMOD_OUTPUT_READFROMMIXER_FUNC Output read from mixer function.
• FMOD_OUTPUT_REQUESTRESET_FUNC Output request reset function.

• FMOD_OUTPUT_METHOD Output method used to interact with the mixer.
• FMOD_OUTPUT_PLUGIN_VERSION The output plug-in API version the plug-in was created with.

FMOD_OUTPUT_ALLOC_FUNC

Output allocate memory function.

void * F_CALL FMOD_OUTPUT_ALLOC_FUNC(
  unsigned int size,
  unsigned int align,
  const char *file,
  int line
);

size

Allocation size.

• Units: Bytes

align

Memory alignment.

• Units: Bytes

file

Source code file name where the allocation was requested.

line

Line of allocation in file.

See Also: FMOD_OUTPUT_STATE

FMOD_OUTPUT_CLOSEPORT_CALLBACK

Output close port callback.

FMOD_RESULT F_CALL FMOD_OUTPUT_CLOSEPORT_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  int portId
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

portId

Port ID.

Main thread callback to close an auxiliary output port on the device.

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_CLOSE_CALLBACK

Output close callback.

This callback is called to shut down and release the output driver's audio interface.

FMOD_RESULT F_CALL FMOD_OUTPUT_CLOSE_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

Invoked by:

• System::close.
• System::release calls System::close internally.

To stop the output stream, rather than closing and shutting it down, FMOD_OUTPUT_STOP_CALLBACK would be used.

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_COPYPORT_FUNC

Output copy port function.

Function to copy the output from the mixer for the given auxiliary port.

FMOD_RESULT F_CALL FMOD_OUTPUT_COPYPORT_FUNC(
  FMOD_OUTPUT_STATE *output_state,
  int portId,
  void *buffer,
  unsigned int length
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

portId

Auxiliary port.

buffer

Output buffer.

length

Length of buffer

See Also: FMOD_OUTPUT_STATE

FMOD_OUTPUT_DESCRIPTION

Output description.

This description structure allows the plug-in writer to define all functionality required for a user-defined output device.

typedef struct FMOD_OUTPUT_DESCRIPTION {
  unsigned int                           apiversion;
  const char                            *name;
  unsigned int                           version;
  FMOD_OUTPUT_METHOD                     method;
  FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK     getnumdrivers;
  FMOD_OUTPUT_GETDRIVERINFO_CALLBACK     getdriverinfo;
  FMOD_OUTPUT_INIT_CALLBACK              init;
  FMOD_OUTPUT_START_CALLBACK             start;
  FMOD_OUTPUT_STOP_CALLBACK              stop;
  FMOD_OUTPUT_CLOSE_CALLBACK             close;
  FMOD_OUTPUT_UPDATE_CALLBACK            update;
  FMOD_OUTPUT_GETHANDLE_CALLBACK         gethandle;
  FMOD_OUTPUT_MIXER_CALLBACK             mixer;
  FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK   object3dgetinfo;
  FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK     object3dalloc;
  FMOD_OUTPUT_OBJECT3DFREE_CALLBACK      object3dfree;
  FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK    object3dupdate;
  FMOD_OUTPUT_OPENPORT_CALLBACK          openport;
  FMOD_OUTPUT_CLOSEPORT_CALLBACK         closeport;
  FMOD_OUTPUT_DEVICELISTCHANGED_CALLBACK devicelistchanged;
} FMOD_OUTPUT_DESCRIPTION;

FMOD_OUTPUT_DESCRIPTION
{
  apiversion,
  name,
  version,
  method,
  getnumdrivers,
  getdriverinfo,
  init,
  start,
  stop,
  close,
  update,
  gethandle,
  mixer,
  object3dgetinfo,
  object3dalloc,
  object3dfree,
  object3dupdate,
  openport,
  closeport,
  devicelistchanged
};

apiversion

The output plug-in API version this plug-in is built for. Set to this to FMOD_OUTPUT_PLUGIN_VERSION.

name

The name of the output plug-in, encoded as a UTF-8 string.

version

The version of the output plug-in.

method

The method by which the mixer is executed and buffered. (FMOD_OUTPUT_METHOD)

getnumdrivers

A user thread callback to provide the number of attached sound devices. Called from System::getNumDrivers. (FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK)

getdriverinfo

A user thread callback to provide information about a particular sound device. Called from System::getDriverInfo. (FMOD_OUTPUT_GETDRIVERINFO_CALLBACK)

init

A user thread callback to allocate resources and provide information about hardware capabilities. Called from System::init. (FMOD_OUTPUT_INIT_CALLBACK)

start Opt

A user thread callback just before mixing should begin, calls to FMOD_OUTPUT_MIXER_CALLBACK will start, you may call FMOD_OUTPUT_READFROMMIXER_FUNC after this point. Called from System::init. (FMOD_OUTPUT_START_CALLBACK)

stop Opt

A user thread callback just after mixing has finished, calls to FMOD_OUTPUT_MIXER_CALLBACK have stopped, you may not call FMOD_OUTPUT_READFROMMIXER_FUNC after this point. Called from System::close. (FMOD_OUTPUT_STOP_CALLBACK)

close Opt

A user thread callback to clean up resources allocated during FMOD_OUTPUT_INIT_CALLBACK. Called from System::init and System::close. (FMOD_OUTPUT_CLOSE_CALLBACK)

update Opt

A user thread callback once per frame to update internal state. Called from System::update. (FMOD_OUTPUT_UPDATE_CALLBACK)

gethandle Opt

A user thread callback to provide a pointer to the internal device object used to share with other audio systems. Called from System::getOutputHandle. (FMOD_OUTPUT_GETHANDLE_CALLBACK)

mixer Opt

A mixer thread callback called repeatedly to give a thread for waiting on an audio hardware synchronization primitive (see remarks for details). Ensure you have a reasonable timeout (~200ms) on your synchronization primitive and allow this callback to return once per wakeup to avoid deadlocks. (FMOD_OUTPUT_MIXER_CALLBACK)

object3dgetinfo Opt

A mixer thread callback to provide information about the capabilities of 3D object hardware. Called during a mix. (FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK)

object3dalloc Opt

A mixer thread callback to reserve a hardware resources for a single 3D object. Called during a mix. (FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK)

object3dfree Opt

A mixer thread callback to release a hardware resource previously acquired with FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK. Called during a mix. (FMOD_OUTPUT_OBJECT3DFREE_CALLBACK)

object3dupdate Opt

A mixer thread callback once for every acquired 3D object every mix to provide 3D information and buffered audio. Called during a mix. (FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK)

openport Opt

A main thread callback to open an auxiliary output port on the device. (FMOD_OUTPUT_OPENPORT_CALLBACK)

closeport Opt

A main thread callback to close an auxiliary output port on the device. (FMOD_OUTPUT_CLOSEPORT_CALLBACK)

devicelistchanged Opt

A main thread callback to notify that a change to the device list may have occurred. (FMOD_OUTPUT_DEVICELISTCHANGED_CALLBACK)

Pass this structure to System::registerOutput to create a new output type, or if defining a dynamically loadable plug-in, return it in a function called FMODGetOutputDescription. FMOD's plug-in loader will look for this function in a dynamic library.

/*
    Plug-in setup example
*/
extern "C" FMOD_OUTPUT_DESCRIPTION* F_CALL FMODGetOutputDescription()
{
    static FMOD_OUTPUT_DESCRIPTION desc;

    /*
        Fill members of structure
    */

    return &desc;
}

There are several methods for driving the FMOD mixer to service the audio hardware.

• Callback: if the audio hardware provides a callback where you must provide a buffer of samples then set 'method' to FMOD_OUTPUT_METHOD_MIX_BUFFERED and directly call FMOD_OUTPUT_READFROMMIXER_FUNC.
• Synchronization: if the audio hardware provides a synchronization primitive to wait on then set 'method' to FMOD_OUTPUT_METHOD_MIX_DIRECT and give a FMOD_OUTPUT_MIXER_CALLBACK pointer. FMOD will create a mixer thread and call you repeatedly once FMOD_OUTPUT_START_CALLBACK has finished, you must wait on your primitive in this callback and upon wake call FMOD_OUTPUT_READFROMMIXER_FUNC.
• Non-realtime: if you are writing a file or driving a non-realtime output call FMOD_OUTPUT_READFROMMIXER_FUNC from FMOD_OUTPUT_UPDATE_CALLBACK.

Callbacks marked with 'user thread' will be called in response to the user of the Core API. In the case of the Studio API, the user is the Studio update thread.

See Also: FMOD_OUTPUT_STATE

FMOD_OUTPUT_DEVICELISTCHANGED_CALLBACK

Output device list change callback.

FMOD_RESULT F_CALL FMOD_OUTPUT_DEVICELISTCHANGED_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_FREE_FUNC

Output free memory function.

void F_CALL FMOD_OUTPUT_FREE_FUNC(
  void *ptr,
  const char *file,
  int line
);

ptr

Allocation pointer.

file

Source code file name where the allocation is freed.

line

Line of free call in file.

See Also: FMOD_OUTPUT_STATE

FMOD_OUTPUT_GETDRIVERINFO_CALLBACK

Output get driver info callback.

This callback is called to provide the user with information about the selected audio driver.

FMOD_RESULT F_CALL FMOD_OUTPUT_GETDRIVERINFO_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  int id,
  char *name,
  int namelen,
  FMOD_GUID *guid,
  int *systemrate,
  FMOD_SPEAKERMODE *speakermode,
  int *speakermodechannels
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

id

The index into the total number of outputs possible, provided by the FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK callback.

name

The driver name relevant to the index passed in. Fill this in. (UTF-8 string)

namelen

The length of name buffer being passed in by the user.

• Units: Bytes

guid

The GUID structure. (FMOD_GUID)

systemrate Opt

The rate the output device prefers. Leave 0 to remain flexible.

• Units: Hertz

speakermode Opt

The speaker mode the output device prefers. Leave FMOD_SPEAKERMODE_DEFAULT to remain flexible. (FMOD_SPEAKERMODE)

speakermodechannels Opt

The speaker mode associated channels the output device prefers. Leave at 0 to remain flexible. Only used for FMOD_SPEAKERMODE_RAW.

Invoked by:

• System::getDriverInfo

See Also: System::getNumDrivers, FMOD_OUTPUT_DESCRIPTION, System::getNumDrivers, FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK

FMOD_OUTPUT_GETHANDLE_CALLBACK

Output get output handle callback.

This callback is called to provide the user with a low level audio interface handle that may be used to pass to other middleware.

FMOD_RESULT F_CALL FMOD_OUTPUT_GETHANDLE_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  void **handle
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

handle Out

Plug-in's output 'handle'.

Invoked by:

• System::getOutputHandle

This callback is only needed if the plug-in writer wants to allow the user access to the main handle behind the plug-in (for example the file handle in a file writer plug-in). The plug-in writer needs to document and publish the type of the handle, as is done in the documentation for System::getOutputHandle.

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK

Output get number of drivers callback.

This callback is called to provide the user with the number of devices usable for the output mode.

FMOD_RESULT F_CALL FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  int *numdrivers
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

numdrivers

Number of output drivers in your plug-in.

Invoked by:

• System::getNumDrivers

Optional. FMOD will assume 0 if this is not specified.

See Also: FMOD_OUTPUT_DESCRIPTION, System::getDriverInfo, FMOD_OUTPUT_GETDRIVERINFO_CALLBACK

FMOD_OUTPUT_INIT_CALLBACK

Output initialization callback.

This callback is called to allow initialization of the output stream for mixing.

FMOD_RESULT F_CALL FMOD_OUTPUT_INIT_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  int selecteddriver,
  FMOD_INITFLAGS flags,
  int *outputrate,
  FMOD_SPEAKERMODE *speakermode,
  int *speakermodechannels,
  FMOD_SOUND_FORMAT *outputformat,
  int dspbufferlength,
  int *dspnumbuffers,
  int *dspnumadditionalbuffers,
  void *extradriverdata
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

selecteddriver

Selected driver id that the user chose from calling System::setDriver.

flags

Initialization flags passed in by the user. (FMOD_INITFLAGS)

outputrate

Output rate selected by the user. If not possible, change the rate to the closest match. FMOD will resample from the rate requested to your rate if they do not match.

• Units: Hertz

speakermode

Speaker mode selected by the user. If not possible, change the speaker mode to the closest match. FMOD will upmix or downmix to the requested speaker mode if they do not match. (FMOD_SPEAKERMODE)

speakermodechannels

Speaker mode channel count selected by the user. For example 1 = mono output. 2 = stereo output. Needed if supporting FMOD_SPEAKERMODE_RAW, otherwise it is informational.

outputformat

Sound format supported by output mode. For example, FMOD_SOUND_FORMAT_PCM16 would be normal. FMOD will convert from FMOD_SOUND_FORMAT_PCMFLOAT (the mixer buffer format) to whatever you specify. (FMOD_SOUND_FORMAT)

dspbufferlength

Size of the buffer fmod will mix to in one mix update.

• Units: Samples

dspnumbuffers

The number of buffers the FMOD Engine mixes the signal to in a circular fashion. Multiply this by dspbufferlength to get the total size of the output sound buffer to allocate. This can be set by the plug-in when FMOD_OUTPUT_DESCRIPTION::method is set to FMOD_OUTPUT_METHOD_MIX_BUFFERED.

dspnumadditionalbuffers Out

Number of additional buffers that a plug-in with FMOD_OUTPUT_DESCRIPTION::method set to FMOD_OUTPUT_METHOD_MIX_BUFFERED requires. These will be allocated up front to allow the number of used buffers to grow when an internal buffer starvation is detected.

extradriverdata

Data passed in by the user specific to this driver.

Invoked by:

• System::init
• System::setOutput, if the output is set after System::init.

See Also: FMOD_OUTPUT_DESCRIPTION, System::setDriver

FMOD_OUTPUT_LOG_FUNC

Output log function.

Call this function in an output plug-in context to utilize the FMOD Engine's debugging system.

void F_CALL FMOD_OUTPUT_LOG_FUNC(
  FMOD_DEBUG_FLAGS level,
  const char *file,
  int line,
  const char *function,
  const char *string,
  ...
);

level

Log type or level. (FMOD_DEBUG_FLAGS)

file

Source code file name from where the log is called. (UTF-8 string)

line

Line of log call in file.

function

Name of the logging function. (UTF-8 string)

string

Log output string. (UTF-8 string)

See Also: FMOD_OUTPUT_STATE

FMOD_OUTPUT_METHOD

Output method used to interact with the mixer.

#define FMOD_OUTPUT_METHOD_MIX_DIRECT    0
#define FMOD_OUTPUT_METHOD_MIX_BUFFERED  2

OUTPUT_METHOD_MIX_DIRECT    = 0
OUTPUT_METHOD_MIX_BUFFERED  = 1

FMOD_OUTPUT_METHOD_MIX_DIRECT

When calling FMOD_OUTPUT_READFROMMIXER_FUNC, the mixer executes directly. Buffering must be performed by plug-in code.

FMOD_OUTPUT_METHOD_MIX_BUFFERED

Mixer will execute and buffer automatically (on a separate thread) and can be read from with FMOD_OUTPUT_READFROMMIXER_FUNC.

For hardware that presents a callback that must be filled immediately FMOD_OUTPUT_METHOD_MIX_BUFFERED is recommended as buffering occurs in a separate thread, reading from the mixer is simply a memcpy. Using FMOD_OUTPUT_METHOD_MIX_DIRECT is recommended if you want to take direct control of how and when the mixer runs.

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_MIXER_CALLBACK

Output mixer callback.

This callback can be used to stall the FMOD mixer thread until it is ready to call the FMOD mixer directly.

FMOD_RESULT F_CALL FMOD_OUTPUT_MIXER_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

Invoked by:

• The FMOD mixer thread, only when the 'method' member of FMOD_OUTPUT_DESCRIPTION is set to FMOD_OUTPUT_METHOD_MIX_DIRECT or FMOD_OUTPUT_METHOD_MIX_BUFFERED.

This callback must use the FMOD_OUTPUT_READFROMMIXER_FUNC function to produce the audio stream needed by the output.

This callback is optional in FMOD_OUTPUT_METHOD_MIX_DIRECT or FMOD_OUTPUT_METHOD_MIX_BUFFERED mode. An output mode may avoid this callback, and instead use its own timing system to call the FMOD mixer with FMOD_OUTPUT_READFROMMIXER_FUNC.

If this callback is used, it will be triggered immediately from the FMOD mixer thread. The callback can then stall with its own synchronization primitive (ie a wait on a semaphore), until something else signals the primitive to execute a mix with FMOD_OUTPUT_READFROMMIXER_FUNC.

Ensure you have a reasonable timeout (~200ms) on your synchronization primitive and allow this callback to return regularly, to avoid deadlocks.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_STATE

FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK

Output 3D Object alloc callback.

This callback is called to reserve hardware resources for a single 3D object.

FMOD_RESULT F_CALL FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  void **object3d
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

object3d

3D audio object.

Invoked by:

• FMOD mixer thread.

This callback is used for 'Object based audio' where sound hardware can receive individual audio streams and position them in 3D space natively, separate from the FMOD mixer. A typical implementation would be something like Dolby Atmos or Playstation VR.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK, FMOD_OUTPUT_OBJECT3DFREE_CALLBACK, FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

FMOD_OUTPUT_OBJECT3DFREE_CALLBACK

Output 3D Object free callback.

This callback is called to release a hardware resource previously acquired with FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK.

FMOD_RESULT F_CALL FMOD_OUTPUT_OBJECT3DFREE_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  void *object3d
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

object3d

3D audio object.

Invoked by:

• FMOD mixer thread.

This callback is used for 'Object based audio' where sound hardware can receive individual audio streams and position them in 3D space natively, separate from the FMOD mixer. A typical implementation would be something like Dolby Atmos or Atmos or Playstation VR.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK, FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK, FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK

Output 3D Object get info callback.

Called from the mixer thread to provide information about the capabilities of 3D object hardware.

FMOD_RESULT F_CALL FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  int *maxhardwareobjects
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

maxhardwareobjects

Maximum number of 3D objects supported.

Invoked by:

• FMOD mixer thread.

This callback is used for 'Object based audio' where sound hardware can receive individual audio streams and position them in 3D space natively, separate from the FMOD mixer. A typical implementation would be something like Dolby Atmos or Atmos or Playstation VR.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK, FMOD_OUTPUT_OBJECT3DFREE_CALLBACK, FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

FMOD_OUTPUT_OBJECT3DINFO

Output 3D Object Info.

typedef struct FMOD_OUTPUT_OBJECT3DINFO {
  float         *buffer;
  unsigned int   bufferlength;
  FMOD_VECTOR    position;
  float          gain;
  float          spread;
  float          priority;
} FMOD_OUTPUT_OBJECT3DINFO;

FMOD_OUTPUT_OBJECT3DINFO
{
  buffer,
  bufferlength,
  position,
  gain,
  spread,
  priority,
};

buffer R/O

Mono PCM floating point buffer. This buffer needs to be scaled by the gain value to get distance attenuation.

bufferlength R/O

Length in PCM samples of buffer.

position R/O

Vector relative between object and listener. (FMOD_VECTOR)

gain R/O

0.0 to 1.0 - 1 = 'buffer' is not attenuated, 0 = 'buffer' is fully attenuated.

spread R/O

0 - 360 degrees. 0 = point source, 360 = sound is spread around all speakers

priority R/O

0.0 to 1.0 - 0 = most important, 1 = least important. Based on height and distance (height is more important).

This callback is used for 'Object mixing' where sound hardware can receive individual audio streams and position them in 3D space natively, separate from the FMOD mixer. A typical implementation would be something like Dolby Atmos or Atmos or Playstation VR.

This structure is passed to the plug-in via FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK, so that any object-based panning solution available can position it in the speakers correctly.
Object based panning is a 3D panning solution that sends a mono-only signal to a hardware device, such as Dolby Atmos or other similar panning solutions.

FMOD does not attenuate the buffer, but provides a 'gain' parameter that the user must use to scale the buffer by. Rather than pre-attenuating the buffer, the plug-in developer can access untouched data for other purposes, like reverb sending for example.
The 'gain' parameter is based on the user's 3D custom roll-off model.

See Also: FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

Output 3D Object update callback.

Called from the mixer thread once for every acquired 3D object every mix to provide 3D information and buffered audio.

FMOD_RESULT F_CALL FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  void *object3d,
  const FMOD_OUTPUT_OBJECT3DINFO *info
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

object3d

3D audio object.

info

3D object characteristics. (FMOD_OUTPUT_OBJECT3DINFO)

Invoked by:

• FMOD mixer

This callback is used for 'Object based audio' where sound hardware can receive individual audio streams and position them in 3D space natively, separate from the FMOD mixer. A typical implementation would be something like Dolby Atmos or Atmos or Playstation VR.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK, FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK, FMOD_OUTPUT_OBJECT3DFREE_CALLBACK

FMOD_OUTPUT_OPENPORT_CALLBACK

Output open port callback.

FMOD_RESULT F_CALL FMOD_OUTPUT_OPENPORT_CALLBACK(
  FMOD_OUTPUT_STATE *output_state,
  FMOD_PORT_TYPE portType,
  FMOD_PORT_INDEX portIndex,
  int *portId,
  int *portRate,
  int *portChannels,
  FMOD_SOUND_FORMAT *portFormat
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

portType

Port type. (FMOD_PORT_TYPE)

portIndex

Port index. (FMOD_PORT_INDEX)

portId Out

Port ID.

portRate Out

Port rate.

• Units: Hertz

portChannels Out

Number of channels.

portFormat

Port sound format. (FMOD_SOUND_FORMAT)

Main thread callback to open an auxiliary output port on the device.

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_PLUGIN_VERSION

The output plug-in API version the plug-in was created with.

#define FMOD_OUTPUT_PLUGIN_VERSION   5

FMOD.OUTPUT_PLUGIN_VERSION

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_READFROMMIXER_FUNC

Output read from mixer function.

FMOD_RESULT F_CALL FMOD_OUTPUT_READFROMMIXER_FUNC(
  FMOD_OUTPUT_STATE *output_state,
  void *buffer,
  unsigned int length
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

buffer

Memory for the Studio API mixer to write to, provided by the plug-in writer.

length

Length of the buffer in samples.

Called by the plug-in. Use this function from your own driver irq/timer to read some data from FMOD's DSP engine. All of the resulting output caused by playing sounds and specifying effects by the user of the plug-in is mixed here and written to the memory provided by you.

FMOD_OUTPUT_REQUESTRESET_FUNC

Output request reset function.

Request the output to shut down and restart.

FMOD_RESULT F_CALL FMOD_OUTPUT_REQUESTRESET_FUNC(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

If this is issued, the output will not reset immediately, but on the next udpate the output will first shut down with a call to the FMOD_OUTPUT_STOP_CALLBACK then FMOD_OUTPUT_CLOSE_CALLBACK, followed by a restart with FMOD_OUTPUT_INIT_CALLBACK and FMOD_OUTPUT_START_CALLBACK

FMOD_OUTPUT_START_CALLBACK

Output start callback.

Called just before mixing should begin. This callback is called to start the output driver's audio stream.

FMOD_RESULT F_CALL FMOD_OUTPUT_START_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

Invoked by:

• System::init
• System::setOutput, if the output is set after System::init.
• System::setDriver, if the driver is set after System::init.

This function is meant for starting the output audio rather than allocating memory and initializing interfaces like FMOD_OUTPUT_INIT_CALLBACK would.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_STOP_CALLBACK

FMOD_OUTPUT_STATE

Output object state passed into every callback provides access to plug-in developers data and system functionality.

typedef struct FMOD_OUTPUT_STATE {
  void                            *plugindata;
  FMOD_OUTPUT_READFROMMIXER_FUNC   readfrommixer;
  FMOD_OUTPUT_ALLOC_FUNC           alloc;
  FMOD_OUTPUT_FREE_FUNC            free;
  FMOD_OUTPUT_LOG_FUNC             log;
  FMOD_OUTPUT_COPYPORT_FUNC        copyport;
  FMOD_OUTPUT_REQUESTRESET_FUNC    requestreset;
} FMOD_OUTPUT_STATE;

FMOD_OUTPUT_STATE
{
  plugindata,
};

plugindata

Plug-in state data.

readfrommixer R/O

Function to read a buffer of audio from the mixer. Used to control when the mix occurs manually when FMOD_OUTPUT_DESCRIPTION::method set to FMOD_OUTPUT_METHOD_MIX_DIRECT. (FMOD_OUTPUT_READFROMMIXER_FUNC)

alloc R/O

Function to allocate memory using the FMOD memory system. (FMOD_OUTPUT_ALLOC_FUNC)

free R/O

Function to free memory allocated with FMOD_OUTPUT_ALLOC. (FMOD_OUTPUT_FREE_FUNC)

log R/O

Function to write to the FMOD logging system. (FMOD_OUTPUT_LOG_FUNC)

copyport R/O

Function to copy the output from the mixer for the given auxiliary port. (FMOD_OUTPUT_COPYPORT_FUNC)

requestreset R/O

Function to request the output plug-in be shutdown then restarted during the next System::update. (FMOD_OUTPUT_REQUESTRESET_FUNC)

See Also: FMOD_OUTPUT_DESCRIPTION

FMOD_OUTPUT_STOP_CALLBACK

Output stop callback.

Called just after mixing has ended. This callback is called to stop the output driver's audio stream.

FMOD_RESULT F_CALL FMOD_OUTPUT_STOP_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

Invoked by:

• System::close (which can be invoked by [System::release])
• System::release.
• System::setOutput, if the output is set after System::init.
• System::setDriver, if the driver is set after System::init.

This function is meant for stopping the output audio rather than freeing memory and shutting down audio interfaces like FMOD_OUTPUT_CLOSE_CALLBACK would.

See Also: FMOD_OUTPUT_DESCRIPTION, FMOD_OUTPUT_START_CALLBACK

FMOD_OUTPUT_UPDATE_CALLBACK

Output update callback.

FMOD_RESULT F_CALL FMOD_OUTPUT_UPDATE_CALLBACK(
  FMOD_OUTPUT_STATE *output_state
);

output_state

Plug-in state. (FMOD_OUTPUT_STATE)

Invoked by:

• System::update

This callback is invoked from the main application update which allows the output to process data in sync with the application, rather than the mixer thread.

See Also: FMOD_OUTPUT_DESCRIPTION, System::update