About

FieldList is a custom data type that stores field layers (FieldLayer). Such a field layer represents a certain function or is referencing a FieldObject (::FLfield). Typically one samples this FieldList and not the layers themselves.

A FieldList parameter can be found on MoGraph effectors or the "Falloff" shader.

The data type ID is CUSTOMDATATYPE_FIELDLIST.

FieldList

Sampling

The FieldList is easily sampled using these functions. The "Sample" functions sample the field in a multi-threaded context. If it is needed to control the sampling process use the "Direct" functions.

FieldList::SampleListSimple(): Samples a block of values with default FieldInfo parameters.
FieldList::SampleList(): Samples a block of values with full FieldInfo parameter control.
FieldList::SampleListWithLambda(): Samples a block calling the given lambda functions.
FieldList::DirectInitSampling(): Initializes direct sampling.
FieldList::DirectSample(): Performs direct sampling.
FieldList::DirectFreeSampling(): Frees direct sampling data.

For information on FieldInfo and FieldOutput see FieldObject Manual.

  // This example reads the "FIELDS" parameter of the given "Plain" effector
  // to obtain the FieldList custom data. The FieldList is then sampled.
 
  // get FieldList data
 
  const DescID fieldParameterID = ConstDescID(DescLevel(FIELDS));
 
  GeData data;
  if (plainEffector->GetParameter(fieldParameterID, data, DESCFLAGS_GET::NONE) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get FieldList
  FieldList* const fieldList = data.GetCustomDataTypeWritable<FieldList>();
  if (fieldList == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // prepare arrays
 
  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;
  }
 
  // define points to sample
  FieldInput points(positions.GetFirst(),
                    directions.GetFirst(),
                    uvws.GetFirst(),
                    sampleCnt,
                    Matrix());
 
  // sample
  FieldOutput results = fieldList->SampleListSimple(*plainEffector, points) iferr_return;

Layers

The layers stored in the FieldList are accessed through:

FieldList::GetCount(): Returns the number of fields and groups.
FieldList::InsertLayer(): Inserts the given layer into the list.
FieldList::GetLayersRoot(): Returns the GeListHead of the layers.
FieldList::GetSelected(): Gets a list of all selected layers.
FieldList::FindByReference(): Gets the layers that match the given FieldLayerLink.

Settings

::FIELDLIST_FLAGS: are accessed through:

FieldList::GetFlags(): Returns the flags.
FieldList::SetFlags(): Sets the flags.
FieldList::CheckFlag(): Returns true if the given flag is set.

Further functions are:

FieldList::GetDirty(): Returns the dirty state of the GUI and the host object.
FieldList::Flush(): Frees the internal memory.
FieldList::HasContent(): Returns true if the list has any content.

FieldLayer

A FieldLayer represents a certain function or is referencing a FieldObject. To implement custom layers see FieldLayerData Manual.

Types

Existing layer types are:

::FLplugin: FieldLayer plugin.
::FLfolder: Folder.
::FLbase: FieldLayer base.
::FLfield: Field object based layer.
::FLsolid: Solid value/color layer.
::FLdescid: DescID based layer.
::FLnoise: Noise remapping layer.
::FLclamp: Clamping remapping layer.
::FLremap: Between values remapping layer.
::FLcurve: Curve remapping layer.
::FLgradient: Gradient remapping layer.
::FLquantize: Quantize remapping layer.
::FLinvert: Invert remapping layer.
::FLcolorize: Colorize remapping layer.
::FLrangemap: Colorize remapping layer.
::FLspline: Spline mapping layer.
::FLdelay: Delay layer.
::FLdecay: Decay layer.
::FLstep: Step layer.
::FLweight: Weight layer.
::FLproximity: Proximity layer.
::FLformula: Formula Layer.
::FLtime: Time layer.
::FLpython: Python layer.
::FLmograph: MoGraph layer.
::FLpolygonobject: Polygon object.
::FLvolumeobject: Volume object, see VolumeObject Manual.

Creation

A new layer is created with:

FieldLayer::Alloc(): Returns a new FieldLayer.
FieldLayer::Free(): Deletes the given FieldLayer.

The FieldLayer tree can be navigated with:

FieldLayer::GetUp(): Returns the parent layer.
FieldLayer::GetDown(): Returns the child layer.
FieldLayer::GetNext(): Returns the next layer in the list.
FieldLayer::GetPred(): Returns the previous layer in the list.
FieldLayer::GetDownLast(): Returns the last layer.

  // This example creates a new "Quantize" layer and inserts it into the FieldList of the given "Plain" effector.
 
  const DescID fieldParameterID = ConstDescID(DescLevel(FIELDS));
 
  GeData data;
  if (plainEffector->GetParameter(fieldParameterID, data, DESCFLAGS_GET::NONE) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get FieldList
  FieldList* const fieldList = data.GetCustomDataTypeWritable<FieldList>();
  if (fieldList == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // create new "Quantize" layer
  FieldLayer* const layer = FieldLayer::Alloc(FLquantize);
  if (layer == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // configure new layer
  layer->SetParameter(ConstDescID(DescLevel(FIELDLAYER_QUANTIZE_STEPS)), 10, DESCFLAGS_SET::NONE);
  layer->SetStrength(0.5);
 
  // insert layer
  fieldList->InsertLayer(layer, nullptr, nullptr) iferr_return;
 
  // store data
  plainEffector->SetParameter(fieldParameterID, data, DESCFLAGS_SET::NONE);

Properties

If the layer links to another element in the scene this element can be accessed through:

FieldLayer::GetLinkedObject(): Returns the FieldLayerLink to the scene element.
FieldLayer::SetLinkedObject(): Set the reference to the scene element.

The strength of a layer is defined by:

FieldLayer::GetStrength(): Returns the strength applied to the layer.
FieldLayer::SetStrength(): Sets the strength applied to the layer.

The blending mode (see flbase.h) is set/get by:

FieldLayer::SetBlendingMode(): Sets the current blending mode.
FieldLayer::GetBlendingMode(): Returns the current blending mode.

The channel flags (::FIELDLAYER_CHANNELFLAG) are accessed through:

FieldLayer::GetChannelFlags(): Returns the channel flags.
FieldLayer::SetChannelFlags(): Sets the channel flags.
FieldLayer::GetChannelFlag(): Returns true if the given flag is set.
FieldLayer::SetChannelFlag(): Sets the state of the given flag.

The channel flags are:

FIELDLAYER_CHANNELFLAG::ENABLE : Layer enabled.
FIELDLAYER_CHANNELFLAG::VALUE : Value sampling enabled.
FIELDLAYER_CHANNELFLAG::COLOR : Color sampling enabled.
FIELDLAYER_CHANNELFLAG::DIRECTION : Slope sampling enabled.

The layer flags (::FIELDLAYER_FLAG) are set/get by:

FieldLayer::SetLayerFlags(): Sets the layer flags.
FieldLayer::GetLayerFlags(): Returns the layer flags.

The layer flags are:

FIELDLAYER_FLAG::NONE : Default state.
FIELDLAYER_FLAG::SKIP : Layer calculation is disabled, e.g. the linked object on a standard layer's deform mode is false.
FIELDLAYER_FLAG::ERRORSKIP : Layer calculation is disabled due to a non critical error in InitializeSampling or as user specified in GetFieldLayerFalgs.
FIELDLAYER_FLAG::HIDE : Layer should be completely ignored from both calculation and GUI display, e.g. the linked object has been deleted.
FIELDLAYER_FLAG::MODIFYDATA : The layer modifies existing data and needs the values from layers beneath it in the layer list in the "results" array inside of Sample.
FIELDLAYER_FLAG::PRESERVEALPHA : The layer does not change the alpha value.
FIELDLAYER_FLAG::NOCHILDVALUE : Children's layer won't output their value.
FIELDLAYER_FLAG::NOCHILDCOLOR : Children's layer won't output their color.
FIELDLAYER_FLAG::NOCHILDDIRECTION : Children's layer won't output their slope.
FIELDLAYER_FLAG::NOCHILDROTATION : Children's layer won't output their rotation.
FIELDLAYER_FLAG::TEMPORARY : This layer should not be saved or copied.

Mask layers are handled with:

FieldLayer::GetMaskHead(): Returns the GeListHead containing the mask layers.
FieldLayer::AddMask(): Adds a mask.
FieldLayer::RemoveMask(): Removes the mask.

Sampling

A layer can directly be sampled by these functions:

FieldLayer::InitSampling(): Initializes the sampling
FieldLayer::Sample(): Samples the layer.
FieldLayer::Aggregate(): Used to call FieldLayerData::Aggregate().
FieldLayer::FreeSampling(): Frees internal data after sampling.

FieldListGui

FieldListGui is the custom GUI element to display FieldList data. The GUI ID is CUSTOMGUI_FIELDLIST.

Table of Contents

About

FieldList

Sampling

Layers

Settings

FieldLayer

Types

Creation

Properties

Sampling

FieldListGui

Further Reading