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* const moGraphCloner = doc->GetActiveObject();
if (moGraphCloner == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
if (moGraphCloner->IsInstanceOf(1018544) == false)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// select sound file
Filename soundFile;
if (!soundFile.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Load Sound File"_s))
return maxon::OK;
// create effector
BaseObject* const soundEffector = BaseObject::Alloc(440000255);
if (soundEffector == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// insert sound effector
doc->InsertObject(soundEffector, nullptr, nullptr);
// add effector to the effectors list
GeData clonerData;
{
InExcludeData* const ieData = static_cast<InExcludeData*>(customData);
if (ieData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ieData->InsertObject(soundEffector, 1 << 0);
}
// use selected sound file
const DescLevel soundTrackID = DescLevel(CTsound, CTsound, 0);
CTrack* const soundTrack = CTrack::Alloc(soundEffector, soundTrackID);
if (soundTrack == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
soundTrack->SetName("New Sound Track"_s);
soundEffector->InsertTrackSorted(soundTrack);
// set track active sound track
GeData data;
{
SoundEffectorData* const soundData = static_cast<SoundEffectorData*>(customData);
if (soundData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
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* const soundEffector = doc->GetActiveObject();
if (soundEffector == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
if (soundEffector->IsInstanceOf(440000255) == false)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
GeData data;
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const SoundEffectorData* const soundData = static_cast<SoundEffectorData*>(customData);
if (soundData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Int probeCnt = soundData->GetProbeCount();
ApplicationOutput("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 (Classic).

Sound

A SoundEffectorData is referencing a CTrack of the type CTsound. The sound file used in that CTrack is the sound file used by a SoundEffectorData, which is sampled and displayed 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* const 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;
const Filename soundFile = parameterData.GetFilename();
const String soundFileStr = soundFile.GetString();
ApplicationOutput("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* const probe = soundData->GetProbe(probeIndex);
if (probe == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
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* const gradient = soundData->GetGradient();
if (gradient == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
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))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
const Int32 sampleCount = 100;
for (Int32 i = 0; i < sampleCount; ++i)
{
Float value;
Vector color;
soundData->Sample(i, sampleCount, value, color);
}
soundData->FreeSampling();

Copy

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

Further Reading

String::FloatToString
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:529
CTrack::Alloc
static CTrack * Alloc(BaseList2D *bl, const DescID &id)
GradientKnot::pos
Float pos
Position.
Definition: customgui_gradient.h:138
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
SoundEffectorData::SetActiveSoundTrack
Bool SetActiveSoundTrack(CTrack *track, BaseDocument *doc)
Int
maxon::Int Int
Definition: ge_sys_math.h:64
BaseObject
Definition: c4d_baseobject.h:224
SoundEffectorData::SetLinLog
void SetLinLog(Float value)
DescID
Definition: lib_description.h:328
GradientKnot
Represents a knot in a gradient.
Definition: customgui_gradient.h:134
Float
maxon::Float Float
Definition: ge_sys_math.h:66
CUSTOMDATATYPE_SOUNDEFFECTOR
#define CUSTOMDATATYPE_SOUNDEFFECTOR
SoundData ID.
Definition: customgui_soundeffector.h:26
SoundEffectorData::GetProbeCount
Int GetProbeCount() const
SoundEffectorData::SetGradientDirection
void SetGradientDirection(Int32 direction)
Filename
Manages file and path names.
Definition: c4d_file.h:93
maxon::OK
return OK
Definition: apibase.h:2546
CTrack::GetDescriptionID
const DescID & GetDescriptionID() const
Definition: c4d_canimation.h:722
FILESELECTTYPE::ANYTHING
@ ANYTHING
Any file.
Probe::SetTop
Bool SetTop(Float top)
BaseList2D::InsertTrackSorted
void InsertTrackSorted(CTrack *track)
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
ID_MG_MOTIONGENERATOR_EFFECTORLIST
@ ID_MG_MOTIONGENERATOR_EFFECTORLIST
Definition: obasemogen.h:16
SoundEffectorData::GetActiveSoundTrack
CTrack * GetActiveSoundTrack(BaseDocument *doc)
SoundEffectorData::GetProbe
Probe * GetProbe(Int index) const
DESCFLAGS_SET::NONE
@ NONE
None.
Probe::SetLeft
Bool SetLeft(Float left)
Probe::_color
Vector _color
Color of the probe used when the probe's color mode is Custom Color.
Definition: customgui_soundeffector.h:132
CTrack
Definition: c4d_canimation.h:659
SoundEffectorData::Sample
Bool Sample(Int index, Int count, Float &value, Vector &color)
GradientKnot::col
Vector col
Color.
Definition: customgui_gradient.h:136
CUSTOMDATATYPE_INEXCLUDE_LIST
#define CUSTOMDATATYPE_INEXCLUDE_LIST
InExclude custom data type ID.
Definition: customgui_inexclude.h:25
InExcludeData
InExclude custom data type (CUSTOMDATATYPE_INEXCLUDE_LIST).
Definition: customgui_inexclude.h:111
Filename::GetString
String GetString(void) const
String
Definition: c4d_string.h:38
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:495
Probe::_samplingMode
Int32 _samplingMode
The probe mode.
Definition: customgui_soundeffector.h:130
SoundEffectorData::CreateProbe
Int CreateProbe(Float left=1.0, Float right=22050.0, Float top=1.0, Float bottom=0.0, Bool selected=false)
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
InExcludeData::InsertObject
Bool InsertObject(BaseList2D *pObject, Int32 lFlags)
Probe::SetRight
Bool SetRight(Float right)
maxon::Vec3< maxon::Float64, 1 >
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:287
Gradient
Definition: customgui_gradient.h:149
Probe::_colorMode
Int32 _colorMode
The color mode.
Definition: customgui_soundeffector.h:129
SoundEffectorData::FreeSampling
Bool FreeSampling()
GeData
Definition: c4d_gedata.h:82
GeData::GetFilename
const Filename & GetFilename(void) const
Definition: c4d_gedata.h:475
BaseList2D::SetName
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2354
Gradient::InsertKnot
Int32 InsertKnot(const GradientKnot &knot)
SoundEffectorData
Definition: customgui_soundeffector.h:146
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
Gradient::FlushKnots
void FlushKnots()
Flushes all the knots.
MGSOUNDEFFECTOR_GADGET
@ MGSOUNDEFFECTOR_GADGET
Definition: oesound.h:6
CID_SOUND_NAME
@ CID_SOUND_NAME
Definition: ctsound.h:7
SoundEffectorData::InitSampling
Bool InitSampling(BaseDocument *doc)
Probe::SetBottom
Bool SetBottom(Float bottom)
CustomDataType
Base class for custom data types.
Definition: c4d_customdatatype.h:50
FILESELECT::LOAD
@ LOAD
Load dialog.
SoundEffectorData::GetGradient
Gradient * GetGradient() const
SoundEffectorData::SetRange
void SetRange(Float xmin, Float xmax, Float ymin, Float ymax)
BaseObject::Alloc
static BaseObject * Alloc(Int32 type)
DESCFLAGS_GET::NONE
@ NONE
None.
SoundEffectorData::UpdateProbeOrder
void UpdateProbeOrder()
GeData::GetCustomDataType
CustomDataType * GetCustomDataType(Int32 datatype) const
Definition: c4d_gedata.h:507
BaseDocument::GetActiveObject
BaseObject * GetActiveObject(void)
C4DAtom::IsInstanceOf
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1403
Probe
Definition: customgui_soundeffector.h:39
String::VectorToString
static String VectorToString(const Vector32 &v, Int32 nnk=-1)
Definition: c4d_string.h:571
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
MAXON_SCOPE
#define MAXON_SCOPE
Definition: apibase.h:2659
CTsound
#define CTsound
Sound.
Definition: ge_prepass.h:1328
Filename::FileSelect
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())