VolumeInterface Manual

About

A maxon::VolumeInterface is used to store and handle volume data. It is typically obtained from a VolumeObject, see VolumeObject Manual.

VolumeInterface

Volume information can be stored in a file:

// This example loads a grid from the given vdb file
// and inserts it into the BaseDocument using a VolumeObject.
const maxon::Int gridIndex = 0;
const maxon::Volume volume = maxon::VolumeInterface::CreateFromFile(volumeUrl, 1.0, gridIndex) iferr_return;
// create VolumeObject
VolumeObject* const volumeObj = VolumeObject::Alloc();
if (volumeObj == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->InsertObject(volumeObj, nullptr, nullptr);
// insert volume
volumeObj->SetVolume(volume);

The grid settings are accessed with:

// This example prints some data on the volumes grid.
// get volume
const maxon::Volume volume = volumeObject->GetVolume();
// check grid
if (volume.HasGrid())
{
const maxon::String gridName = volume.GetGridName();
const GRIDCLASS gridClass = volume.GetGridClass();
DiagnosticOutput("@ (@)", gridName, gridClass);
}

Iterator

The data stored in a volume is accessed with the maxon::GridIteratorInterface iterator:

// This example iterates over the active cells of the given volume.
// get volume
const maxon::Volume volume = volumeObject->GetVolume();
// get matrix
const maxon::Matrix transform = volume.GetGridTransform();
// create iterator
iterator.Init(volume) iferr_return;
// iterate
for (; iterator.IsNotAtEnd(); iterator.StepNext())
{
// get value
const Float32 value = iterator.GetValue();
// get coordinates
const maxon::IntVector32 coord = iterator.GetCoords();
DiagnosticOutput("@: @", coord, value);
// get world space coordinates
Vector pos;
pos.x = coord.x;
pos.y = coord.y;
pos.z = coord.z;
pos = transform * pos;
DiagnosticOutput("World space coordinates: @", pos);
}

Accessor

The grid accessor can be used to both retrieve and set the volume data:

Volume data is accessed with:

// This example creates a new VolumeObject and a new volume.
// It uses the GridAccessor to set values of the volume.
// create VolumeObject
VolumeObject* const volumeObj = VolumeObject::Alloc();
if (volumeObj == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->InsertObject(volumeObj, nullptr, nullptr);
// create volume
volume.SetGridClass(GRIDCLASS::FOG) iferr_return;
volume.SetGridName("Example Grid"_s);
const Vector scaleFactor { 10.0 };
const maxon::Matrix scaleMatrix = MatrixScale(scaleFactor);
volume.SetGridTransform(scaleMatrix) iferr_return;
// create accessor
access.InitWithWriteAccess(volume, maxon::VOLUMESAMPLER::NEAREST) iferr_return;
// set values in the shape of a helix
Float offset = 0.0;
const Float scale = 100.0;
const Float scaleY = 10.0;
while (offset < 50.0)
{
Float64 sin;
Float64 cos;
maxon::SinCos(offset, sin, cos);
pos.x = maxon::Int32(sin * scale);
pos.z = maxon::Int32(cos * scale);
pos.y = maxon::Int32(offset * scaleY);
// set value
access.SetValue(pos, 10.0) iferr_return;
offset = offset + 0.01;
}
// insert volume
volumeObj->SetVolume(volume);

Further Reading

MatrixScale
Matrix MatrixScale(const Vector &s)
VolumeObject
Definition: lib_volumeobject.h:36
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
maxon::Mat3< Vector >
maxon
The maxon namespace contains all declarations of the MAXON API.
Definition: c4d_basedocument.h:27
FOG
FOG
Definition: ge_prepass.h:1358
GRIDCLASS
GRIDCLASS
Volume Classes.
Definition: ge_prepass.h:1662
Float
maxon::Float Float
Definition: ge_sys_math.h:51
maxon::String
Definition: string.h:1197
maxon::SinCos
MAXON_ATTRIBUTE_FORCE_INLINE void SinCos(Float32 val, Float32 &sn, Float32 &cs)
Calculates both sine and cosine of a value.
Definition: apibasemath.h:495
Float32
maxon::Float32 Float32
Definition: ge_sys_math.h:53
VolumeObject::Alloc
static VolumeObject * Alloc()
Definition: lib_volumeobject.h:49
iferr_return
#define iferr_return
Definition: resultbase.h:1434
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
maxon::GridAccessorRef
Definition: volumeaccessors.h:25
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:168
maxon::VolumeToolsInterface::CreateNewFloat32Volume
static MAXON_METHOD Result< Volume > CreateNewFloat32Volume(Float32 background)
maxon::Vec3::z
T z
Definition: vec.h:34
VolumeObject::GetVolume
const maxon::VolumeInterface * GetVolume() const
maxon::Vec3
A vector consisting of three components X, Y and Z.
Definition: vec.h:14
maxon::Int32
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:172
maxon::Vec3::x
T x
Definition: vec.h:32
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
maxon::Vec3::y
T y
Definition: vec.h:33
maxon::VOLUMESAMPLER
VOLUMESAMPLER
Definition: volumeaccessors.h:16
maxon::VolumeInterface::CreateFromFile
static MAXON_METHOD Result< Volume > CreateFromFile(const Url &url, Float scale, Int gridIndex)
maxon::GridIteratorRef
Definition: volumeiterators.h:29
VolumeObject::SetVolume
void SetVolume(const maxon::VolumeInterface *volumeObj)
Float64
maxon::Float64 Float64
Definition: ge_sys_math.h:52