OmegaSound3D

Introduction

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.

Loading and saving files

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)

TOmegaSound3D Properties

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!

TOmegaSound3D Methods

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.

TSoundListItem Properties

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.

TSoundListItem Methods

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.

TAudioPathListItem 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)

TAudioPathListItem Methods

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.



Back to the Index