SoundEffectorData Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Sound
• Probes
• Data
• Sampling
• Copy
• Further Reading

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;
  moGraphCloner->GetParameter(ConstDescID(DescLevel(ID_MG_MOTIONGENERATOR_EFFECTORLIST)), clonerData, DESCFLAGS_GET::NONE);
 
  MAXON_SCOPE
  {
    InExcludeData* const ieData = clonerData.GetCustomDataTypeWritable<InExcludeData>();
    if (ieData == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    ieData->InsertObject(soundEffector, 1 << 0);
    moGraphCloner->SetParameter(ConstDescID(DescLevel(ID_MG_MOTIONGENERATOR_EFFECTORLIST)), clonerData, DESCFLAGS_SET::NONE);
  }
 
  // use selected sound file
  const DescID  soundTrackID = ConstDescID(DescLevel(CTsound, CTsound, 0));
  CTrack*         const soundTrack = CTrack::Alloc(soundEffector, soundTrackID);
  if (soundTrack == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  soundTrack->SetParameter(ConstDescID(DescLevel(CID_SOUND_NAME)), soundFile, DESCFLAGS_SET::NONE);
  soundTrack->SetName("New Sound Track"_s);
  soundEffector->InsertTrackSorted(soundTrack);
 
  // set track active sound track
 
  GeData data;
  soundEffector->GetParameter(ConstDescID(DescLevel(MGSOUNDEFFECTOR_GADGET)), data, DESCFLAGS_GET::NONE);
 
  MAXON_SCOPE
  {
    SoundEffectorData* const soundData = data.GetCustomDataTypeWritable<SoundEffectorData>();
    if (soundData == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    soundData->SetActiveSoundTrack(soundTrack, doc);
    soundEffector->SetParameter(ConstDescID(DescLevel(MGSOUNDEFFECTOR_GADGET)), data, DESCFLAGS_SET::NONE);
  }

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;
  if (!soundEffector->GetParameter(ConstDescID(DescLevel(MGSOUNDEFFECTOR_GADGET)), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const SoundEffectorData* const soundData = data.GetCustomDataType<SoundEffectorData>();
  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 (Cinema API).

• SoundEffectorData::Alloc(): Creates a new SoundEffectorData object.
• SoundEffectorData::Free(): Deletes the given SoundEffectorData object.

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.

• SoundEffectorData::GetActiveSoundTrack(): Returns the active CTrack.
• SoundEffectorData::SetActiveSoundTrack(): Sets the active CTrack.

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;
      track->GetParameter(ConstDescID(DescLevel(CID_SOUND_NAME)), parameterData, DESCFLAGS_GET::NONE);
 
      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:

• SoundEffectorData::CreateProbe(): Creates a new probe and returns its index.
• SoundEffectorData::CreateDefaultProbe(): Creates the default probe.
• SoundEffectorData::GetProbeCount(): Returns the number of probes.
• SoundEffectorData::GetProbe(): Returns the Probe of the given index.
• SoundEffectorData::DeleteProbe(): Deletes the probe of the given index.
• SoundEffectorData::UpdateProbeOrder(): Updates the probe order. Must be called after any change to a probe position.

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.

• Probe::GetRight(): Returns the right value.
• Probe::SetRight(): Sets the right value.
• Probe::GetLeft(): Returns the left value.
• Probe::SetLeft(): Sets the left value.
• Probe::GetBottom(): Returns the bottom value.
• Probe::SetBottom(): Sets the bottom value.
• Probe::GetTop(): Returns the top value.
• Probe::SetTop(): Sets the top value.
• Probe::ValidateDimensions(): Swaps the left/right and top/bottom values if they are inverted.

The Probe class also has these public attributes:

• Probe::_clamp: Clamps the output from 0.0 to 1.0.
• Probe::_colorMode: The color mode (Default, Custom Color, Custom Gradient).
• Probe::_samplingMode: The sampling mode (Peak, Average, Step).
• Probe::_strength: Overall strength multiplier.
• Probe::_color: Color for the "Custom Color" mode.
• Probe::_gradient: Gradient for the "Custom Gradient" mode.
• Probe::_fadePercentage: Fade percentage for decay.
• Probe::_freeze: Freeze state of the output.
• Probe::_freezeArray: Freeze value of the output.

  // 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).

• SoundEffectorData::GetRange(): Returns the currently displayed range.
• SoundEffectorData::SetRange(): Sets the currently displayed range.

Further functions are:

• SoundEffectorData::GetLinLog(): Returns the blend value of the linear/logarithmic slider.
• SoundEffectorData::SetLinLog(): Sets the blend value of the linear/logarithmic slider.
• SoundEffectorData::GetFreeze(): Returns the freeze state.
• SoundEffectorData::SetFreeze(): Sets the freeze state.

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

• SoundEffectorData::GetGradient(): Returns the global Gradient.
• SoundEffectorData::GetGradientDirection(): Returns the gradient direction.
• SoundEffectorData::SetGradientDirection(): Sets the gradient direction.

  // 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 = MAXON_REMOVE_CONST(soundData->GetGradient());
  if (gradient == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  gradient->FlushKnots();
 
  maxon::GradientKnot red;
  red.pos = 0.0;
  red.col = maxon::Color{ 1.0, 0, 0 };  // red
  gradient->InsertKnot(red);
 
  maxon::GradientKnot green;
  green.pos = 1.0;
  green.col = maxon::Color { 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).

• SoundEffectorData::IsFFTSamplingCacheDirty(): Returns true if the cache is up-to-date.
• SoundEffectorData::InitSampling(): Initializes the sampling functionality.
• SoundEffectorData::Sample(): Samples the sound file at the current frame.
• SoundEffectorData::SampleArray(): Samples whole array of elements simultaneously.
• SoundEffectorData::FreeSampling(): Frees the memory used for sampling.

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);
 
    ApplicationOutput("Value: " + String::FloatToString(value));
    ApplicationOutput("Color: " + String::VectorToString(color));
  }
  soundData->FreeSampling();

Copy

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

• SoundEffectorData::CopyTo(): Copies the sound data into the given SoundEffectorData.

Further Reading

• MoGraph Overview
• CTrack Manual
• CustomDataType