Struct SoundBuilder

pub struct SoundBuilder<'a> { /* private fields */ }

A builder for creating a Sound.

Implementations

impl<'a> SoundBuilder<'a>

pub const fn open(filename: &'a Utf8CStr) -> Self

Open a file or url.

pub const fn open_user( length: c_uint, channel_count: c_int, default_frequency: c_int, format: SoundFormat, ) -> Self

Open a user-created static sample or stream.

pub const unsafe fn open_memory(data: &'a [u8]) -> Self

Open the sound using a byte slice.

Safety

The slice must remain valid until the sound has been loaded. See the Mode docs for more information.

pub const unsafe fn open_memory_point(data: &'a [u8]) -> Self

Open the sound using a byte slice.

Safety

The slice must remain valid until the sound has been released. Unlike Self::open_memory this function does not copy the data, so it is even more unsafe!

pub const fn with_filesystem<F: FileSystemSync + FileSystemAsync>( self, userdata: *mut c_void, ) -> Self

Specify a custom filesystem to open the Sound.

pub const fn with_filesystem_sync<F: FileSystemSync>( self, userdata: *mut c_void, ) -> Self

Specify a custom sync filesystem to open the Sound.

pub const fn with_filesystem_async<F: FileSystemAsync>( self, userdata: *mut c_void, ) -> Self

Specify a custom async filesystem to open the Sound.

pub const unsafe fn with_raw_ex_info( self, ex_info: FMOD_CREATESOUNDEXINFO, ) -> Self

Safety

The FMOD_CREATESOUNDEXINFO must be valid.

pub const fn with_file_offset(self, file_offset: c_uint) -> Self

File offset to start reading from.

pub const fn with_open_raw( self, channel_count: c_int, default_frequency: c_int, format: SoundFormat, ) -> Self

Ignore the file format and treat as raw PCM.

pub const fn with_mode(self, mode: Mode) -> Self

Set the Mode flags for this builder.

Mode::OPEN_MEMORY, Mode::OPEN_MEMORY_POINT, Mode::OPEN_USER, and Mode::OPEN_RAW cannot be set using this function.

Please use constructors on this type to use those modes.

pub const fn with_decode_buffer_size(self, size: c_uint) -> Self

Size of the decoded buffer for Mode::CREATE_STREAM, or the block size used with pcmreadcallback for SoundBuilder::open_user.

pub const fn with_initial_subsound(self, initial_subsound: c_int) -> Self

Initial subsound to seek to for Mode::CREATE_STREAM.

pub const fn with_subsound_count(self, count: c_int) -> Self

Number of subsounds available for SoundBuilder::open_user, or maximum subsounds to load from file.

pub const fn with_inclusion_list(self, list: &'a [c_int]) -> Self

List of subsound indices to load from file.

pub const fn with_dls_name(self, dls_name: &'a Utf8CStr) -> Self

File path for a SoundType::DLS sample set to use when loading a SoundType::MIDI file, see below for defaults.

pub const fn with_encryption_key(self, key: &'a Utf8CStr) -> Self

Key for encrypted SoundType::FSB file, cannot be used in conjunction with Self::open_memory_point.

pub fn with_max_polyphony(self, max_polyphony: c_int) -> Self

Maximum voice count for SoundType::MIDI / SoundType::IT.

pub const fn with_suggested_sound_type(self, sound_type: SoundType) -> Self

Attempt to load using the specified type first instead of loading in codec priority order.

pub const fn with_file_buffer_size(self, size: c_int) -> Self

Buffer size for reading the file, -1 to disable buffering.

pub const fn with_channel_order(self, order: ChannelOrder) -> Self

Custom ordering of speakers for this sound data.

pub fn with_initial_sound_group(self, group: SoundGroup) -> Self

SoundGroup to place the created Sound in once created.

pub const fn with_initial_seek_position( self, position: c_uint, unit: TimeUnit, ) -> Self

Initial position to seek to for Mode::CREATE_STREAM.

pub const fn with_ignore_set_filesystem(self, ignore: bool) -> Self

Ignore System::set_filesystem_sync and this SoundBuilder’s file callbacks.

pub const fn with_audioqueue_policy(self, policy: c_uint) -> Self

Hardware / software decoding policy for SoundType::AudioQueue.

pub const fn with_min_midi_granularity(self, granularity: c_uint) -> Self

Mixer granularity for SoundType::MIDI sounds, smaller numbers give a more accurate reproduction at the cost of higher CPU usage.

pub const fn with_non_block_thread_id(self, id: c_int) -> Self

Thread index to execute Mode::NONBLOCKING loads on for parallel Sound loading.

pub const fn with_fsb_guid(self, guid: &'a Guid) -> Self

On input, GUID of already loaded SoundType::FSB file to reduce disk access, on output, GUID of loaded FSB.

pub const fn with_pcm_callback<C: PcmCallback>(self) -> Self

Specify a PCM callback.

pub const fn with_nonblock_callback<C: NonBlockCallback>(self) -> Self

Callback to notify completion for Mode::NONBLOCKING, occurs during creation and seeking / restarting streams.

pub fn build(&self, system: System) -> Result<Sound>

Helper method that forwards to System::create_sound.

pub fn build_stream(&self, system: System) -> Result<Sound>

Helper method that forwards to System::create_stream.

impl<'a> SoundBuilder<'a>

pub const fn mode(&self) -> Mode

Get the mode of this SoundBuilder.

pub const fn raw_ex_info(&self) -> FMOD_CREATESOUNDEXINFO

Get the raw ex info of this SoundBuilder.

pub const fn raw_name_or_data(&self) -> *const c_char

Get the raw name/data/url of this SoundBuilder.

pub fn name_or_url(&self) -> Option<&Utf8CStr>

Get the name or url of this SoundBuilder.

Returns None if Mode::OPEN_MEMORY or Mode::OPEN_MEMORY_POINT or Mode::OPEN_USER are set.

pub fn data(&self) -> Option<&[u8]>

Get the data of this SoundBuilder.

Returns Some if Mode::OPEN_MEMORY or Mode::OPEN_MEMORY_POINT are set.

pub const fn length(&self) -> c_uint

Get the length of data of this SoundBuilder.

pub const fn file_offset(&self) -> c_uint

Get the file offset of this SoundBuilder.

pub const fn channel_count(&self) -> c_int

Get the channel count of this SoundBuilder.

pub const fn default_frequency(&self) -> c_int

Get the default frequency of this SoundBuilder.

pub fn format(&self) -> SoundFormat

Get the sound format of this SoundBuilder.

pub const fn decode_buffer_size(&self) -> c_uint

Get the decode buffer size of this SoundBuilder.

pub const fn initial_subsound(&self) -> c_int

Get the initial subsound of this SoundBuilder.

pub const fn subsound_count(&self) -> c_int

Get the subsound count of this SoundBuilder.

pub fn inclusion_list(&self) -> Option<&'a [c_int]>

Get the inclusion list of this SoundBuilder.

pub fn dls_name(&self) -> Option<&Utf8CStr>

Get the DLS name of this SoundBuilder.

pub fn encryption_key(&self) -> Option<&Utf8CStr>

Get the encryption key of this SoundBuilder.

pub const fn max_polyphony(&self) -> c_int

Get the max polyphony of this SoundBuilder.

pub fn suggested_sound_type(&self) -> SoundType

Get the suggested sound type of this SoundBuilder.

pub const fn file_buffer_size(&self) -> c_int

Get the file buffer size of this SoundBuilder.

pub fn channel_order(&self) -> ChannelOrder

Get the channel order of this SoundBuilder.

pub fn initial_sound_group(&self) -> Option<SoundGroup>

Get the initial sound group of this SoundBuilder.

pub fn initial_seek_position(&self) -> (c_uint, TimeUnit)

Get the initial seek position of this SoundBuilder.

pub const fn ignore_set_filesystem(&self) -> bool

Get the ignore set filesystem flag of this SoundBuilder.

pub const fn min_midi_granularity(&self) -> c_uint

Get the min midi granularity of this SoundBuilder.

pub const fn non_block_thread_id(&self) -> c_int

Get the nonblock thread id of this SoundBuilder.

pub const fn fsb_guid(&self) -> Option<Guid>

Get the FSB guid of this SoundBuilder.

impl SoundBuilder<'_>

pub unsafe fn from_ffi( name_or_data: *const c_char, mode: FMOD_MODE, create_sound_ex_info: FMOD_CREATESOUNDEXINFO, ) -> Self

Safety

The mode must match the required fields of the FMOD_CREATESOUNDEXINFO struct. The FMOD_CREATESOUNDEXINFO struct’s cbsize field must be set to the size of the struct.

If the mode is not Mode::OPEN_MEMORY or Mode::OPEN_MEMORY_POINT name_or_data pointer must be valid for reads of bytes up to and including the nul terminator.

If the mode is Mode::OPEN_MEMORY or Mode::OPEN_MEMORY_POINT the data pointer must be valid for reads of bytes up to FMOD_CREATESOUNDEXINFO::length.

The lifetime of the builder is unbounded and MUST be constrained!

Trait Implementations

impl<'a> Debug for SoundBuilder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.