VolumeSet Manual

Table of Contents

• About
  • Creation
  • Handling Volumes
• Further Reading

About

A VolumeSet is a BaseObject that stores a collection of volume objects (VolumeObject).

A VolumeSet object is an instance of Ovolumeset.

Creation

A VolumeSet object is created as usual (see Entity Creation and Destruction Manual (Cinema API)):

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

  // This example creates a VolumeSet object
  // and inserts it into the given BaseDocument.
 
  VolumeSet* const volumeSet = VolumeSet::Alloc();
  if (volumeSet == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(volumeSet, nullptr, nullptr);

Handling Volumes

A VolumeSet contains multiple VolumeObject elements. These elements are edited with:

• VolumeSet::AddVolume(): Adds the given VolumeObject to the VolumeSet.
• VolumeSet::DetachVolume(): Detaches the given VolumeObject from the VolumeSet.
• VolumeSet::DetachVolumeAtIndex(): Detaches the VolumeObject with the given index from the VolumeSet.
• VolumeSet::GetVolumeAtIndex(): Returns the VolumeObject at the given index.

  // This example reads the grids stored in the given vdb file.
  // A VolumeSet object is created and the grid with a given name
  // is inserted as a VolumeObject.
 
  // get grid names
  const maxon::BaseArray<maxon::String> gridNames = maxon::VolumeToolsInterface::GetGridNamesFromFile(volumeUrl) iferr_return;
  const maxon::Int gridCnt = gridNames.GetCount();
  if (gridCnt == 0)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // create volume set
  VolumeSet* const volumeSet = VolumeSet::Alloc();
  if (volumeSet == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(volumeSet, nullptr, nullptr);
 
  // check all grids
  for (maxon::Int gridIndex = 0; gridIndex < gridCnt; ++gridIndex)
  {
    // get grid name
    const maxon::String& gridName = gridNames[gridIndex];
 
    // check grid name
    if (gridName == "cube_volume"_s)
    {
      // load volume data
      const maxon::Volume volume = maxon::VolumeInterface::CreateFromFile(volumeUrl, 1.0, gridIndex) iferr_return;
 
      // make volume object
      VolumeObject* const volumeObject = VolumeObject::Alloc();
      if (volumeObject == nullptr)
        return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
      volumeObject->SetName(gridName);
 
      // store volume data
      volumeObject->SetVolume(volume);
 
      // insert
      volumeSet->AddVolume(volumeObject);
    }
  }

Further Reading

• Volumes Overview
• VolumeObject Manual
• BaseObject Manual