About

The SoundEffectorData stores multiple sound probes that are used to sample a given sound file (defined by a sound track). The class also allows to sample the sound file using the defined probes.

The SoundEffectorData class is defined in the customgui_soundeffector.h header file. The data type ID is CUSTOMDATATYPE_SOUNDEFFECTOR. Sub-channel IDs are defined in dsoundprobe.h.

// This example opens a file selection dialog to let the user select a sound file.
// If a file is selected a new Sound Effector using that sound file is added to the
// currently active MoGraph Cloner object.
// check if a Cloner is selected
BaseObject* moGraphCloner = doc->GetActiveObject();
if (!moGraphCloner || !moGraphCloner->IsInstanceOf(1018544))
return false;
// select sound file
Filename soundFile;
if (!soundFile.FileSelect(FILESELECTTYPE_ANYTHING, FILESELECT_LOAD, "Load Sound File"))
return false;
// create effector
BaseObject* soundEffector = BaseObject::Alloc(440000255);
if (!soundEffector)
return false;
// insert sound effector
doc->InsertObject(soundEffector, nullptr, nullptr);
// add effector to the effectors list
GeData clonerData;
{
InExcludeData* ieData = static_cast<InExcludeData*>(customData);
if (ieData)
{
ieData->InsertObject(soundEffector, 1 << 0);
}
}
// use selected sound file
const DescLevel soundTrackID = DescLevel(CTsound, CTsound, 0);
CTrack* soundTrack = CTrack::Alloc(soundEffector, soundTrackID);
if (soundTrack)
{
soundTrack->SetParameter(CID_SOUND_NAME, soundFile, DESCFLAGS_SET_0);
soundTrack->SetName("New Sound Track");
soundEffector->InsertTrackSorted(soundTrack);
// set track active sound track
GeData data;
if (customData)
{
SoundEffectorData* soundData = static_cast<SoundEffectorData*>(customData);
if (soundData)
{
soundData->SetActiveSoundTrack(soundTrack, doc);
}
}
}

Access

The SoundEffectorData is typically used with the "Sound" MoGraph effector. An instance of this class is obtained from this object. The parameter ID is defined in oesound.h.

// This example accesses the SoundEffectorData from the given Sound Effector object.
BaseObject* soundEffector = doc->GetActiveObject();
if (!soundEffector || !soundEffector->IsInstanceOf(440000255))
return false;
GeData data;
return false;
if (!customData)
return false;
SoundEffectorData* soundData = static_cast<SoundEffectorData*>(customData);
if (soundData)
{
const Int probeCnt = soundData->GetProbeCount();
GePrint("Sound Effector uses " + String::IntToString(probeCnt) + " probes.");
}

Allocation/Deallocation

A SoundEffectorData object can be created with the usual tools, see Entity Creation and Destruction Manual.

Sound

A SoundEffectorData is referencing a CTrack of the type CTsound. The sound file used in that CTrack is the sound file the SoundEffectorData will sample (and display in the Attribute Manager).

See also CTrack Manual.

// This example gets the file name of the sound file used with the given SoundEffectorData.
// get used sound track
CTrack* track = soundData->GetActiveSoundTrack(doc);
if (track)
{
const DescID id = track->GetDescriptionID();
// check if the track is a sound track
if (id[0].id == CTsound)
{
// get file name
GeData parameterData;
track->GetParameter(CID_SOUND_NAME, parameterData, DESCFLAGS_GET_0);
const Filename soundFile = parameterData.GetFilename();
const String soundFileStr = soundFile.GetString();
GePrint("Sound File: " + soundFileStr);
}
}

Probes

One or many probes can be used to sample the sound file. Such probes are edited with these functions:

A probe is represented with the Probe class. The "left" and "right" position is defined in Hz, the top and bottom values as a normalized scalar defined between 0.0 and 1.0.

The Probe class also has these public attributes:

// This example adds and configures a new probe.
const Int probeIndex = soundData->CreateProbe();
Probe* probe = soundData->GetProbe(probeIndex);
if (probe)
{
probe->SetLeft(300.0);
probe->SetRight(2000.0);
probe->SetTop(0.8);
probe->SetBottom(0.2);
probe->_samplingMode = 1; // average
probe->_colorMode = 1; // color
probe->_color = Vector(0.5, 0.5, 1.0);
}
soundData->UpdateProbeOrder();

Data

Additional settings allow to define the range of the frequency spectrum that is currently displayed in the Attribute Manager. These range functions are only valid if the sound data is displayed using the SoundDataCustomGui (e.g. in the Attribute Manager).

Further functions are:

The color used to colorize the sound is defined by a Gradient:

// This example configures the range and changes the global gradient.
soundData->SetRange(1000.0, 2000.0, 0.0, 1.0);
soundData->SetLinLog(0.5);
soundData->SetGradientDirection(0);
Gradient* gradient = soundData->GetGradient();
if (gradient)
{
gradient->FlushKnots();
red.pos = 0.0;
red.col = Vector(1.0, 0, 0); // red
gradient->InsertKnot(red);
GradientKnot green;
green.pos = 1.0;
green.col = Vector(0.0, 1.0, 0); // green
gradient->InsertKnot(green);
}

Sampling

The SoundEffectorData class can be used to sample a sound file. The sound file that is sampled is defined with the active CTrack (see Sound).

Note
The sound data is sampled using the existing probes and their settings.
// This example samples the sound data using the probes and their settings.
if (soundData->InitSampling(doc))
{
const Int32 sampleCount = 100;
for (Int32 i = 0; i < sampleCount; ++i)
{
Float value;
Vector color;
soundData->Sample(i, sampleCount, value, color);
GePrint("Value: " + String::FloatToString(value));
GePrint("Color: " + String::VectorToString(color));
}
soundData->FreeSampling();
}

Copy

The settings of a given SoundEffectorData object can be copied with:

Further Reading