Firelight Technologies FMOD Studio API

FMOD_OUTPUT_DESCRIPTION

When creating an output, declare one of these and provide the relevant callbacks and name for FMOD to use when it creates and uses an output of this type.

C/C++ Syntax

typedef struct {
  unsigned int apiversion;
  const char *name;
  unsigned int version;
  int polling;
  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_GETPOSITION_CALLBACK getposition;
  FMOD_OUTPUT_LOCK_CALLBACK lock;
  FMOD_OUTPUT_UNLOCK_CALLBACK unlock;
  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_DESCRIPTION;

JavaScript Syntax

struct FMOD_OUTPUT_DESCRIPTION
{
  apiversion,
  name,
  version,
  polling,
  getnumdrivers,
  getdriverinfo,
  init,
  start,
  stop,
  close,
  update,
  gethandle,
  getposition,
  lock,
  unlock,
  mixer,
  object3dgetinfo,
  object3dalloc,
  object3dfree,
  object3dupdate,
  openport,
  closeport,
};

Members

apiversion

[w] The output plugin API version this plugin is built for. Set to this to FMOD_OUTPUT_PLUGIN_VERSION.

name

[w] Name of the output plugin.

version

[w] Version of the output plugin.

polling

[w] If TRUE (non-zero) a mixer thread is created that calls FMOD_OUTPUT_GETPOSITION_CALLBACK / FMOD_OUTPUT_LOCK_CALLBACK / FMOD_OUTPUT_UNLOCK_CALLBACK to drive the mixer. If FALSE (zero) you must call FMOD_OUTPUT_READFROMMIXER to drive the mixer yourself.

getnumdrivers

[w] Required user thread callback to provide the number of attached sound devices. Called from System::getNumDrivers.

getdriverinfo

[w] Required user thread callback to provide information about a particular sound device. Called from System::getDriverInfo.

init

[w] Required user thread callback to allocate resources and provide information about hardware capabilities. Called from System::init.

start

[w] Optional user thread callback just before mixing should begin, calls to FMOD_OUTPUT_GETPOSITION_CALLBACK / FMOD_OUTPUT_LOCK_CALLBACK / FMOD_OUTPUT_UNLOCK_CALLBACK / FMOD_OUTPUT_MIXER_CALLBACK will start, you may call FMOD_OUTPUT_READFROMMIXER after this point. Called from System::init.

stop

[w] Optional user thread callback just after mixing has finished, calls to FMOD_OUTPUT_GETPOSITION_CALLBACK / FMOD_OUTPUT_LOCK_CALLBACK / FMOD_OUTPUT_UNLOCK_CALLBACK / FMOD_OUTPUT_MIXER_CALLBACK have stopped, you may not call FMOD_OUTPUT_READFROMMIXER after this point. Called from System::close.

close

[w] Required user thread callback to clean up resources allocated during FMOD_OUTPUT_INIT_CALLBACK. Called from System::init and System::close.

update

[w] Optional user thread callback once per frame to update internal state. Called from System::update.

gethandle

[w] Optional user thread callback to provide a pointer to the internal device object used to share with other audio systems. Called from System::getOutputHandle.

getposition

[w] Required mixer thread callback (if 'polling' is TRUE) to provide the hardware playback position in the output ring buffer. Called before a mix.

lock

[w] Required mixer thread callback (if 'polling' is TRUE) to provide a pointer the mixer can write to for the next block of audio data. Called before a mix.

unlock

[w] Optional mixer thread callback (if 'polling' is TRUE) to signify the mixer has finished writing to the pointer from FMOD_OUTPUT_LOCK_CALLBACK. Called after a mix.

mixer

[w] Optional mixer thread callback (if 'polling' is FALSE) 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.

object3dgetinfo

[w] Optional mixer thread callback to provide information about the capabilities of 3D object hardware. Called during a mix.

object3dalloc

[w] Optional mixer thread callback to reserve a hardware resources for a single 3D object. Called during a mix.

object3dfree

[w] Optional mixer thread callback to release a hardware resource previously acquired with FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK. Called during a mix.

object3dupdate

[w] Optional mixer thread callback once for every acquired 3D object every mix to provide 3D information and buffered audio. Called during a mix.

openport

[w] Optional main thread callback to open an auxiliary output port on the device.

closeport

[w] Optional main thread callback to close an auxiliary output port on the device.

Remarks

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

• Polled: if the audio hardware must be polled regularly set 'polling' to TRUE, FMOD will create a mixer thread that calls back via FMOD_OUTPUT_GETPOSITION_CALLBACK. Once an entire block of samples have played FMOD will call FMOD_OUTPUT_LOCK_CALLBACK to allow you to provide a destination pointer to write the next mix.
• Callback: if the audio hardware provides a callback where you must provide a buffer of samples then set 'polling' to FALSE and directly call FMOD_OUTPUT_READFROMMIXER.
• Synchronization: if the audio hardware provides a synchronization primitive to wait on then set 'polling' to FALSE 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.
• Non-realtime: if you are writing a file or driving a non-realtime output call FMOD_OUTPUT_READFROMMIXER from FMOD_OUTPUT_UPDATE_CALLBACK.

Callbacks marked with 'user thread' will be called in response to the user of the FMOD low level API, in the case of the Studio runtime API, the user is the Studio Update thread.

Members marked with [r] mean read only for the developer, read/write for the FMOD system.

Members marked with [w] mean read/write for the developer, read only for the FMOD system.

JavaScript only :

Not all fields are currently supported or may not work as expected at this time. To initialize an new instance in javascript use "FMOD.OUTPUT_DESCRIPTION()", no 'new' keyword is required.

See Also

• FMOD_OUTPUT_STATE
• FMOD_OUTPUT_GETNUMDRIVERS_CALLBACK
• FMOD_OUTPUT_GETDRIVERINFO_CALLBACK
• FMOD_OUTPUT_INIT_CALLBACK
• FMOD_OUTPUT_START_CALLBACK
• FMOD_OUTPUT_STOP_CALLBACK
• FMOD_OUTPUT_CLOSE_CALLBACK
• FMOD_OUTPUT_UPDATE_CALLBACK
• FMOD_OUTPUT_GETHANDLE_CALLBACK
• FMOD_OUTPUT_GETPOSITION_CALLBACK
• FMOD_OUTPUT_LOCK_CALLBACK
• FMOD_OUTPUT_UNLOCK_CALLBACK
• FMOD_OUTPUT_MIXER_CALLBACK
• FMOD_OUTPUT_OBJECT3DGETINFO_CALLBACK
• FMOD_OUTPUT_OBJECT3DALLOC_CALLBACK
• FMOD_OUTPUT_OBJECT3DFREE_CALLBACK
• FMOD_OUTPUT_OBJECT3DUPDATE_CALLBACK

Version 1.10.03 Built on Feb 1, 2018