6. Studio API Reference | Studio::Bank

Banks made in FMOD Studio contain the metadata and audio sample data required for runtime mixing and playback. Audio sample data may be packed into the same bank as the event metadata which references it, or it may be packed into separate banks.

Loading:

Studio::Bank::getLoadingState Retrieves the loading state.
Studio::Bank::loadSampleData Loads non-streaming sample data for all events in the bank.
Studio::Bank::unloadSampleData Unloads non-streaming sample data for all events in the bank.
Studio::Bank::getSampleLoadingState Retrieves the loading state of the samples in the bank.
Studio::Bank::unload Unloads the bank.

Buses:

Studio::Bank::getBusCount Retrieves the number of buses in the bank. This is only relevant for master banks, as other banks do not contain buses.
Studio::Bank::getBusList Retrieves a list of the buses in the bank. This is only relevant for master banks, as other banks do not contain buses.

Events:

Studio::Bank::getEventCount Retrieves the number of event descriptions in the bank.
Studio::Bank::getEventList Retrieves a list of the event descriptions in the bank.

String Table:

Studio::Bank::getStringCount Retrieves the number of string table entries in the bank. This is only relevant for studio string banks, as other banks do not contain string tables.
Studio::Bank::getStringInfo Retrieves a string table entry. This is only relevant for studio string banks, as other banks do not contain string tables.

VCAs:

Studio::Bank::getVCACount Retrieves the number of VCAs in the bank.
Studio::Bank::getVCAList Retrieves a list of the VCAs in the bank.

General:

Studio::Bank::getID Retrieves the bank's GUID.
Studio::Bank::getPath Retrieves the path.
Studio::Bank::setUserData Sets the bank's user data.
Studio::Bank::getUserData Retrieves the bank's user data.
Studio::Bank::isValid Checks that the bank reference is valid.

See Also:

Studio::System::loadBankFile Loads the metadata of a bank. This does not load the bank's sample data.
Studio::System::loadBankMemory Loads the metadata of a bank from memory. Does not load the bank's sample data.
Studio::System::loadBankCustom Loads the metadata of a bank using custom read callbacks.
Studio::System::getBank Retrieves a loaded bank with the specified file path.
Studio::System::getBankById Retrieves a loaded bank with the specified ID.
Studio::System::getBankList Retrieves a list of the currently-loaded banks.

Studio::Bank::getBusCount

Retrieves the number of buses in the bank. This is only relevant for master banks, as other banks do not contain buses.

C++

FMOD_RESULT Studio::Bank::getBusCount(
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetBusCount(
  FMOD_STUDIO_BANK *bank,
  int *count
);

RESULT Studio.Bank.getBusCount(
  out int count
);

Bank.getBusCount(
  count
);

count Out: Bus count.

May be used in conjunction with Studio::Bank::getBusList to enumerate the buses in the bank.

Studio::Bank::getBusList

Retrieves a list of the buses in the bank. This is only relevant for master banks, as other banks do not contain buses.

C++

FMOD_RESULT Studio::Bank::getBusList(
  Studio::Bus **array,
  int capacity,
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetBusList(
  FMOD_STUDIO_BANK *bank,
  FMOD_STUDIO_BUS **array,
  int capacity,
  int *count
);

RESULT Studio.Bank.getBusList(
  out Bus[] array
);

Bank.getBusList(
  array,
  capacity,
  count
);

array Out: Array to receive the list. (Studio::Bus)
capacity: Capacity of array.
count Out Opt: Number of buses written to array.

May be used in conjunction with Studio::Bank::getBusCount to enumerate the buses in the bank.

This function returns a maximum of capacity buses from the bank. If the bank contains more than capacity buses additional buses will be silently ignored.

Studio::Bank::getEventCount

Retrieves the number of event descriptions in the bank.

C++

FMOD_RESULT Studio::Bank::getEventCount(
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetEventCount(
  FMOD_STUDIO_BANK *bank,
  int *count
);

RESULT Studio.Bank.getEventCount(
  out int count
);

Bank.getEventCount(
  count
);

count Out: Event description count.

May be used in conjunction with Studio::Bank::getEventList to enumerate the events in the bank.

This function counts the events which were added to the bank by the sound designer. The bank may contain additional events which are referenced by event instruments but were not added to the bank, and those referenced events are not counted.

Studio::Bank::getEventList

Retrieves a list of the event descriptions in the bank.

C++

FMOD_RESULT Studio::Bank::getEventList(
  Studio::EventDescription **array,
  int capacity,
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetEventList(
  FMOD_STUDIO_BANK *bank,
  FMOD_STUDIO_EVENTDESCRIPTION **array,
  int capacity,
  int *count
);

RESULT Studio.Bank.getEventList(
  out EventDescription[] array
);

Bank.getEventList(
  array,
  capacity,
  count
);

array Out: Array to receive the list. (Studio::EventDescription)
capacity: Capacity of array.
count Out Opt: Number of event descriptions written to array.

This function returns a maximum of capacity events from the bank. If the bank contains more than capacity events then additional events will be silently ignored.

May be used in conjunction with Studio::Bank::getEventCount to enumerate the events in the bank.

This function retrieves the events which were added to the bank by the sound designer. The bank may contain additional events which are referenced by event instruments but were not added to the bank, and those referenced events are not retrieved.

Studio::Bank::getID

Retrieves the bank's GUID.

C++

FMOD_RESULT Studio::Bank::getID(
  FMOD_GUID *id
);

FMOD_RESULT FMOD_Studio_Bank_GetID(
  FMOD_STUDIO_BANK *bank,
  FMOD_GUID *id
);

RESULT Studio.Bank.getID(
  out Guid id
);

Bank.getID(
  id
);

id Out: Bank GUID. (FMOD_GUID)

Studio::Bank::getLoadingState

Retrieves the loading state.

C++

FMOD_RESULT Studio::Bank::getLoadingState(
  FMOD_STUDIO_LOADING_STATE *state
);

FMOD_RESULT FMOD_Studio_Bank_GetLoadingState(
  FMOD_STUDIO_BANK *bank,
  FMOD_STUDIO_LOADING_STATE *state
);

RESULT Studio.Bank.getLoadingState(
  out LOADING_STATE state
);

Bank.getLoadingState(
  state
);

state Out: Loading state. (FMOD_STUDIO_LOADING_STATE)

This function may be used to check the loading state of a bank which has been loaded asynchronously using the FMOD_STUDIO_LOAD_BANK_NONBLOCKING flag, or is pending unload following a call to Studio::Bank::unload.

If an asynchronous load failed due to a file error state will contain FMOD_STUDIO_LOADING_STATE_ERROR and the return code from this function will be the error code of the bank load function.

Studio::Bank::getPath

Retrieves the path.

C++

FMOD_RESULT Studio::Bank::getPath(
  char *path,
  int size,
  int *retrieved
);

FMOD_RESULT FMOD_Studio_Bank_GetPath(
  FMOD_STUDIO_BANK *bank,
  char *path,
  int size,
  int *retrieved
);

RESULT Studio.Bank.getPath(
  out string path
);

Bank.getPath(
  path,
  size,
  retrieved
);

path Out Opt: Buffer to receive the path. (UTF-8 string)
size: Size of the path buffer in bytes. Must be 0 if path is null.
retrieved Out Opt: Length of the path in bytes, including the terminating null character.

The strings bank must be loaded prior to calling this function, otherwise FMOD_ERR_EVENT_NOTFOUND is returned.

If the path is longer than size then it is truncated and this function returns FMOD_ERR_TRUNCATED.

The retrieved parameter can be used to get the buffer size required to hold the full path

Studio::Bank::getSampleLoadingState

Retrieves the loading state of the samples in the bank.

C++

FMOD_RESULT Studio::Bank::getSampleLoadingState(
  FMOD_STUDIO_LOADING_STATE *state
);

FMOD_RESULT FMOD_Studio_Bank_GetSampleLoadingState(
  FMOD_STUDIO_BANK *bank,
  FMOD_STUDIO_LOADING_STATE *state
);

RESULT Studio.Bank.getSampleLoadingState(
  out LOADING_STATE state
);

Bank.getSampleLoadingState(
  state
);

state Out: Loading state. (FMOD_STUDIO_LOADING_STATE)

May be used for tracking the status of the Studio::Bank::loadSampleData operation.

If Studio::Bank::loadSampleData has not been called for the bank then this function will return FMOD_STUDIO_LOADING_STATE_UNLOADED even though sample data may have been loaded by other API calls.

Studio::Bank::getStringCount

Retrieves the number of string table entries in the bank. This is only relevant for studio string banks, as other banks do not contain string tables.

C++

FMOD_RESULT Studio::Bank::getStringCount(
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetStringCount(
  FMOD_STUDIO_BANK *bank,
  int *count
);

RESULT Studio.Bank.getStringCount(
  out int count
);

Bank.getStringCount(
  count
);

count Out: String table entry count.

May be used in conjunction with Studio::Bank::getStringInfo to enumerate the string table in a bank.

See Also: strings bank

Studio::Bank::getStringInfo

Retrieves a string table entry. This is only relevant for studio string banks, as other banks do not contain string tables.

C++

FMOD_RESULT Studio::Bank::getStringInfo(
  int index,
  FMOD_GUID *id,
  char *path,
  int size,
  int *retrieved
);

FMOD_RESULT FMOD_Studio_Bank_GetStringInfo(
  FMOD_STUDIO_BANK *bank,
  int index,
  FMOD_GUID *id,
  char *path,
  int size,
  int *retrieved
);

RESULT Studio.Bank.getStringInfo(
  int index,
  out Guid id,
  out string path
);

Bank.getStringInfo(
  index,
  id,
  path,
  size,
  retrieved
);

index: String table entry index.
id Out Opt: GUID. (FMOD_GUID)
path Out Opt: Path. (UTF-8 string)
size: Size of the path buffer in bytes. Must be 0 if path is null.
retrieved Out Opt: Length of the retrieved path in bytes, including the terminating null character.

May be used in conjunction with Studio::Bank::getStringCount to enumerate the string table in a bank.

If the path is longer than size then it is truncated and this function returns FMOD_ERR_TRUNCATED.

The retrieved parameter can be used to get the buffer size required to hold the full path

Studio::Bank::getUserData

Retrieves the bank's user data.

C++

FMOD_RESULT Studio::Bank::getUserData(
  void **userdata
);

FMOD_RESULT FMOD_Studio_Bank_GetUserData(
  FMOD_STUDIO_BANK *bank,
  void **userdata
);

RESULT Studio.Bank.getUserData(
  out IntPtr userdata
);

Bank.getUserData(
  userdata
);

userdata Out: User data set by calling Studio::Bank::setUserData.

This function allows arbitrary user data to be retrieved from this object. For information about setting a bank's user data, see Studio::Bank::getUserData. For an example of how to get and set user data, see the User Data section of the glossary.

Studio::Bank::getVCACount

Retrieves the number of VCAs in the bank.

C++

FMOD_RESULT Studio::Bank::getVCACount(
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetVCACount(
  FMOD_STUDIO_BANK *bank,
  int *count
);

RESULT Studio.Bank.getVCACount(
  out int count
);

Bank.getVCACount(
  count
);

count Out: VCA count.

May be used in conjunction with Studio::Bank::getVCAList to enumerate the VCAs in a bank.

Studio::Bank::getVCAList

Retrieves a list of the VCAs in the bank.

C++

FMOD_RESULT Studio::Bank::getVCAList(
  Studio::VCA **array,
  int capacity,
  int *count
);

FMOD_RESULT FMOD_Studio_Bank_GetVCAList(
  FMOD_STUDIO_BANK *bank,
  FMOD_STUDIO_VCA **array,
  int capacity,
  int *count
);

RESULT Studio.Bank.getVCAList(
  out VCA[] array
);

Bank.getVCAList(
  array,
  capacity,
  count
);

array Out: Array to receive the list. (Studio::VCA)
capacity: Capacity of array.
count Out Opt: Number of VCAs written to array.

May be used in conjunction with Studio::Bank::getVCACount to enumerate the VCAs in a bank.

This function returns a maximum of capacity VCAs from the bank. If the bank contains more than capacity VCAs additional VCAs will be silently ignored.

Studio::Bank::isValid

Checks that the bank reference is valid.

C++

bool Studio::Bank::isValid()

bool FMOD_Studio_Bank_IsValid(FMOD_STUDIO_BANK *bank)

bool Studio.Bank.isValid()

Studio.Bank.isValid()

Studio::Bank::loadSampleData

Loads non-streaming sample data for all events in the bank.

C++

FMOD_RESULT Studio::Bank::loadSampleData();

FMOD_RESULT FMOD_Studio_Bank_LoadSampleData(FMOD_STUDIO_BANK *bank);

RESULT Studio.Bank.loadSampleData();

Bank.loadSampleData();

Use this function to preload sample data ahead of time so that the events in the bank can play immediately when started.

This function is equivalent to calling Studio::EventDescription::loadSampleData for all events in the bank, including referenced events.

Studio::Bank::setUserData

Sets the bank's user data.

C++

FMOD_RESULT Studio::Bank::setUserData(
  void *userdata
);

FMOD_RESULT FMOD_Studio_Bank_SetUserData(
  FMOD_STUDIO_BANK *bank,
  void *userdata
);

RESULT Studio.Bank.setUserData(
  IntPtr userdata
);

Bank.setUserData(
  userdata
);

userdata: User data.

This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.

See Also: Studio::Bank::getUserData

Studio::Bank::unload

Unloads the bank.

C++

FMOD_RESULT Studio::Bank::unload();

FMOD_RESULT FMOD_Studio_Bank_Unload(FMOD_STUDIO_BANK *bank);

RESULT Studio.Bank.unload();

Bank.unload();

This will destroy all objects created from the bank, unload all sample data inside the bank, and invalidate all API handles referring to the bank.

If the bank was loaded from user-managed memory, e.g. by Studio::System::loadBankMemory with the FMOD_STUDIO_LOAD_MEMORY_POINT mode, then the memory must not be freed until the unload has completed. Poll the loading state using Studio::Bank::getLoadingState or use the FMOD_STUDIO_SYSTEM_CALLBACK_BANK_UNLOAD system callback to determine when it is safe to free the memory.

Studio::Bank::unloadSampleData

Unloads non-streaming sample data for all events in the bank.

C++

FMOD_RESULT Studio::Bank::unloadSampleData();

FMOD_RESULT FMOD_Studio_Bank_UnloadSampleData(FMOD_STUDIO_BANK *bank);

RESULT Studio.Bank.unloadSampleData();

Bank.unloadSampleData();

Sample data loading is reference counted and the sample data will remain loaded until unload requests corresponding to all load requests are made, or until the bank is unloaded. For more details see Sample Data Loading.

See Also: Studio::Bank::loadSampleData