OmegaSound3D encapsulates the functionality of DirectMusicto play several sounds and music tracks simultaneously. DirectMusic works with an internal software synthesizer which mixes several so-called "AudioPaths" in both mono, stereo and 3D at the same time. A SoundPath is a collection of sounds being played, much like a channel on a mixer. Each SoundPath can have it's own volume, panning, XYZ-position etc. assigned.
OmegaSound3D allows you to define the sounds you want to play in a SoundItem collection. A sound can be a .mid, .wav and, still in development, a .mod file. Currently MP3 has to be played via the OmegaMusic component. With each sound you can specify how you want it to be played by default and in which AudioPath it should be played.
OmegaSound3D allows you to create one or more AudioPaths in a AudioPathItem collection. An AudioPath can have a frequency set at which audio is mixed, it can be set to mono, stereo or 3D and it can be part of a 'Pool' (about which more later). While sound is playing in the AudioPath you can dynamically set it's XYZ-position, it's volume, it's panning etc. Ofcourse it is possible to play one SoundItem several times in one or more AudioPaths.
The AudioPath pools are a special piece of code in this component: Each AudioPath has a 'Pool' boolean property. All AudioPaths that have Pool set to true, are part of the pool of their AudioType (which can be Mono, Stereo or 3D). In a SoundItem you can specify whether it should play in an AudioPath specified by Index, or whether it should search for a free Pool-item. A typical set-up for games would be one Stereo audiopath with just 2 channels for stereo-sound, and about 16 or 32 AudioPaths of AudioType 3D which have their Pool property set to True. You would play sound effects in the Pool 3D AudioPaths automatically by settings their SoundItem instances to play in the 3D pool and you would play the background-music in the Stereo AudioPath.
By right-clicking on the OmegaSound3D component on your form, you can access the Open and Save methods of the collections in the TOmegaSound3D component. These methods are also accessible in each collection's methods as a 'LoadFromFile' and 'SaveToFile' method, like you would expect. These files will then be saved and loaded:
AudioPathList Files (*.oapl)
SoundList Files (*.osl)
ModList Files (*.oml)
AudioPathList: The AudioPathList collection that contains
all the AudioPath items you will be using.
SoundList: The SoundList collection that contains all the Sound
items you will be playing
ListenerPositionX/Y/Z: The position of the 'Listener'. This
is the position which all 3D AudioPaths will be mixed to. 3D positions in sound
are always measured in meters, so beware with large values!
Init(): Always call this method before doing any Play() calls
Stop(): Stops all sounds that are currently playing in all
AudioPaths
IsPlaying(): Boolean: Returns True if one or more AudioPaths
are currently playing any sounds.
Name: A name to give to this sound item. The SoundList can
be searched by this name.
FileName: The path to the file to load for this sound (can
be .mid, .wav etc.)
Loop: True of this sound should be played again and again
RepeatCount: The number of times to repeat this sound if Loop
is False
Volume: The volume to play this sound at (0 to 100 from silence
to loud)
Pan: The stereo-position to play this sound in (-100 to 100
from left to right). Only applies to sounds played in stereo AudioPaths!
SoundPositionX/Y/Z: The 3D-position to play this sound in (measured
in meters). Only applies to sounds played in 3D AudioPaths!
AudioPathIndex: The index of the AudioPath to use in the AudioPathList
to play this sound in.
AudioPathPool: Can be: appUseIndex, sound will be
played in the AudioPath specified by AudioPathIndex only, app3D, sound
will be played in one of the free AudioPaths with AudioType 3D and Pool set
to True, appMono, same as app3D but now for mono AudioPaths, appStereo,
same as app3D but now for stereo AudioPaths.
Load(): Loads the sound from the FileName property and readies
it for play. This method is called by the Play() method automatically if needed,
but this prevents the delay upon first play.
Unload(): Frees the memory associated with the loaded sound.
Play(): TAudioPathListItem: Starts playing the sound in the
associated AudioPath. The actual AudioPath used is returned.
Stop(): Stops this sound. Note, that this means, that all
instances of this sound will be stopped. So, if you had it playing in 6 AudioPaths,
all of these would be stopped at once.
IsPlaying(): Boolean: Returns True if this sound is playing
in one or more AudioPaths.
SetSoundPosition(AX, AY, AZ: Single): A quick method of setting
the default 3D play location of a sound, instead of using the separate properties.
Name: A name to give to this AudioPath. The AudioPathList
can be searched bythis name.
AudioPathType: The type of audio this AudioPath will play.
Possible values: apt3D, aptMono, aptStereo. If Pool is set to True, this also
indicates the pool-type at the same time.
Pool: If True, this AudioPath is part of a pool. See the introduction
above for a short explanation.
Channels: The number of channels (sounds played at the same
time) to allocate for this AudioPath. A typical MIDI song will require 16 channels,
a typical sound-fx AudioPath will require no more than 4 or something. A .mod
file will never require more than 2 channels since it's pre-mixed already.
Frequency: The frequency at which to mix this AudioPath. Normal
value for this is 22050.
PositionX/Y/Z: The position at which this AudioPath is played.
Changes to these properties are effective immediately.
Volume: The volume at which this AudioPath is played. Effective
immediately. (0 till 100)
Pan: The panning-position of this AudioPath. Effective immediately.
(-100 till 100)
Init(): Initialized this AudioPath. This method is already
called by the TOmegaSound3D.Init() method.
Play(): Resumes play of this AudioPath if
it was stopped before
Stop(): Stops this AudioPath. It can be resumed with Play()
SetSoundPosition(AX, AY, AZ: Single): A quick method of setting
the 3D play location, instead of using the separate properties.