FieldObject Manual

Table of Contents

• About
• FieldObject
• Sampling Fields
  • FieldInfo
  • FieldShared
  • FieldInput
  • FieldOutput
  • FieldCallerStack
• Further Reading

About

A FieldObject represents a field in the Cinema 4D scene. Such a field can be sampled in 3D space to obtain values and colors. Field objects are typically used with MoGraph effectors.

A FieldObject is an instance of Ofield.

FieldObject

A new FieldObjects is created with the usual tools:

• FieldObject::Alloc(): Creates a new FieldObject. See c4d_fielddata.h for IDs.
• FieldObject::Free(): Deletes the given FieldObject.

  // This example creates a new "Random" field object.
 
  // allocate random field object
  FieldObject* const fieldObject = FieldObject::Alloc(Frandom);
  if (fieldObject == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // insert into the document
  doc->InsertObject(fieldObject, nullptr, nullptr);

Sampling Fields

A FieldObject can be sampled using FieldObject::Sample(). How the field is sampled is defined using the classes FieldInfo, FieldShared, FieldInput and FieldOutput.

• FieldObject::GetFieldFlags(): Returns the FIELDOBJECT_FLAG flags.
• FieldObject::InitSampling(): Prepares the sampling.
• FieldObject::Sample(): Samples the FieldObject.
• FieldObject::FreeSampling(): Frees internal memory after sampling.

  // This example samples the given FieldObject.
 
  // prepare arrays for sample points
  maxon::BaseArray<maxon::Vector> positions;
  positions.Resize(sampleCnt) iferr_return;
 
  maxon::BaseArray<maxon::Vector> uvws;
  uvws.Resize(sampleCnt) iferr_return;
 
  maxon::BaseArray<maxon::Vector> directions;
  directions.Resize(sampleCnt) iferr_return;
 
  // set positions
  Float64 xOffset = 0.0;
  for (maxon::Vector& pos : positions)
  {
    pos.x = xOffset;
    xOffset += stepSize;
  }
 
  // prepare results
  FieldOutput results;
  results.Resize(sampleCnt, FIELDSAMPLE_FLAG::VALUE) iferr_return;
 
  FieldOutputBlock block = results.GetBlock();
 
  // define points to sample
  FieldInput points(positions.GetFirst(),
                    directions.GetFirst(),
                    uvws.GetFirst(),
                    sampleCnt,
                    Matrix());
 
  // context
  const FieldInfo info = FieldInfo::Create(caller, points, FIELDSAMPLE_FLAG::VALUE) iferr_return;
  maxon::GenericData extraData;
  // sample the object
  fieldObject->InitSampling(info) iferr_return;
  fieldObject->Sample(points, block, info, extraData) iferr_return;
  fieldObject->FreeSampling(info, extraData);

FieldInfo

A FieldInfo object provides information on the context of the sampling operation.

A FieldInfo object is created with:

• FieldInfo::Create(): Creates a new FieldInfo object.
• FieldInfo::CopyFrom(): Copies the data from the given FieldInfo.

Members:

• FieldInfo::_flags: FIELDSAMPLE_FLAG flags.
• FieldInfo::_threadIndex: Index of the current thread.
• FieldInfo::_totalThreadCount: Number of threads.
• FieldInfo::_callerThread: Calling thread.
• FieldInfo::_doc: Calling document.
• FieldInfo::_inputData: FieldInput input data.
• FieldInfo::_callerStack: Calling BaseList2D objects.

Flags FIELDSAMPLE_FLAG:

• FIELDSAMPLE_FLAG::VALUE : Samples only the value.
• FIELDSAMPLE_FLAG::DIRECTION : Samples only the direction.
• FIELDSAMPLE_FLAG::COLOR : Samples only the color.
• FIELDSAMPLE_FLAG::ALL : Samples all properties.

FieldShared

FieldShared is the object reponsible to share data between fields.

• FieldShared::Flush(): Flushes the data.
• FieldShared::CopyFrom(): Copies the data from the given FieldShared object.
• FieldShared::ResetDirty(): Resets the dirty count.

The public members are:

• FieldShared::_finalOutput
• FieldShared::_finalOutputDirty
• FieldShared::_customData: Custom data (BaseContainer) to be used.
• FieldShared::_customDataDirty: Dirty state of the custom data.

FieldInput

A FieldInput object defines points in space that should be sampled. Optionally further data like directions or UV-coordinates can be added.

• FieldInput::CopyFromRaw(): Copies the data from the given FieldInput.
• FieldInput::GetSubBlock(): Returns a FieldInput filled with a subset of the original data.

The public members are:

• FieldInput::_position: An array of points.
• FieldInput::_direction: An array of directions.
• FieldInput::_uvw: An array of UVW coordinates.
• FieldInput::_blockCount: The number of elements to be processed.
• FieldInput::_blockOffset: The offset of the elements to be processed.
• FieldInput::_fullArraySize: The size of the source data.
• FieldInput::_transform: Transformation matrix into world space.

FieldOutput

A FieldOutput object stores the data generated by the sampling process.

A FieldOutput can be created with:

• FieldOutput::Alloc(): Creates a new FieldOutput object.
• FieldOutput::Free(): Deletes the given FieldOutput object.
• FieldOutput::Create(): Creates a new FieldOutput object.
• FieldOutput::Resize(): Resizes the object.
• FieldOutput::CopyFrom(): Copies the data from the given FieldOutput object.
• FieldOutput::CopyArrayContentFrom(): Copies from the array content from given source.

These functions are provided:

• FieldOutput::GetBlock(): Returns the FieldOutputBlock.
• FieldOutput::GetSubBlock(): Returns a FieldOutputBlock filled with a subset of the data.
• FieldOutput::Flush(): Flushes all data.
• FieldOutput::GetCount(): Returns the number of elements.
• FieldOutput::ClearDeactivated(): Clears the deactivated array.
• FieldOutput::ClearMemory(): Resets the data.
• FieldOutput::CalculateCrc(): Returns a maxon::Crc32C for the internal data.
• FieldOutput::Reset(): Resets the object to an empty state.
• FieldOutput::IsValid(): Returns true if allocations and sizes are valid.

The public members are:

• FieldOutput::_value: An array of weights.
• FieldOutput::_alpha: An array of alpha values.
• FieldOutput::_color: An array of colors.
• FieldOutput::_direction: An array of directions.
• FieldOutput::_deactivated: An array of activation states.
• FieldOutput::_rotation: An array of directions.
• FieldOutput::_pivot: The rotational velocity.

FieldCallerStack

The FieldCallerStack defines the list of BaseList2D objects calling the sampling function. If no object is calling the sampling function, an unique ID (UInt) must be provided.

• FieldCallerStack::FieldCallerStack(): Default constructor.
• FieldCallerStack::Create(): Creates a new FieldCallerStack object.
• FieldCallerStack::Add(): Adds a BaseList2D object to the caller stack.
• FieldCallerStack::CopyFrom(): Copies the data of the given FieldCallerStack object.

The stack data is accessed with:

• FieldCallerStack::GetCount(): Returns the number of stack elements.
• FieldCallerStack::operator[](): Accesses the stack at the given index.
• FieldCallerStack::operator const UInt &(): Returns the value of the stack.
• FieldCallerStack::RecalcValue(): Calculates the ID of the caller stack.
• FieldCallerStack::UpdateValue(): Updates the ID of the caller stack.
• FieldCallerStack::GetValue(): Returns the stack ID.
• FieldCallerStack::IsValid(): Returns is true if the stack is not empty.

Public members are:

• FieldCallerStack::_value: Value.
• FieldCallerStack::_callers: Array of BaseList2D elements.

Further Reading

• MoGraph Overview
• BaseList2D Manual