FieldList Manual

Table of Contents

• About
• FieldList
  • Sampling
  • Layers
  • Settings
• FieldLayer
  • Types
  • Creation
  • Properties
  • Sampling
• FieldListGui
• Further Reading

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 { FIELDS };
 
  GeData data;
  if (plainEffector->GetParameter(fieldParameterID, data, DESCFLAGS_GET::NONE) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get FieldList
  CustomDataType* const customData = data.GetCustomDataType(CUSTOMDATATYPE_FIELDLIST);
  FieldList* const      fieldList  = static_cast<FieldList*>(customData);
  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 { FIELDS };
 
  GeData data;
  if (plainEffector->GetParameter(fieldParameterID, data, DESCFLAGS_GET::NONE) == false)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get FieldList
  CustomDataType* const customData = data.GetCustomDataType(CUSTOMDATATYPE_FIELDLIST);
  FieldList* const      fieldList  = static_cast<FieldList*>(customData);
  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(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.

Further Reading

• MoGraph Overview
• FieldObject Manual
• GeListHead Manual