FieldLayerData Manual

Table of Contents

• About
• FieldLayerData
• Register
• Example
• Further Reading

About

FieldLayerData is the base class for custom field layers (FieldLayer)

A new FieldLayerData based class is registered with RegisterFieldLayerPlugin().

FieldLayerData

In a FieldLayerData based class the following functions can be implemented:

• FieldLayerData::InitSampling(): Prepares data for sampling.
• FieldLayerData::Sample(): Samples the layer.
• FieldLayerData::Aggregate(): Called after each thread/block if FIELDLAYER_AGGREGATE is set.
• FieldLayerData::FreeSampling(): Frees data after sampling.
• FieldLayerData::IsEqual(): Returns true if the layer is equal to the given layer.
• FieldLayerData::GetLinkedObject(): Returns a referenced object.
• FieldLayerData::SetLinkedObject(): Sets a referenced object.
• FieldLayerData::CheckDirty(): Updates the dirtiness.

Register

A FieldLayerData based class has to be registered with RegisterFieldLayerPlugin(). The flags are:

• FIELDLAYER_DIRECT: The FieldLayer will have access to directly manipulate the 'result' data in ModifyValues rather than purely overwrite it.
• FIELDLAYER_CHILDREN: The FieldLayer accepts child layers (which it then must evaluate itself in it's Sample function).
• FIELDLAYER_NOVALUEOUT: The FieldLayer doesn't calculate values.
• FIELDLAYER_NOCOLOROUT: The FieldLayer doesn't calculate colors.
• FIELDLAYER_NODIRECTIONOUT: The FieldLayer doesn't calculate slopes.
• FIELDLAYER_AGGREGATE: FieldLayerData::Aggregate() should be called after each block.

Note

Modifier layers are registered with FIELDLAYER_DIRECT.

Example

// This example shows the implementation of a custom field layer.

// ------------------------------------------------------------------------------
// This example field layer shifts the hue of the sample color.
// ------------------------------------------------------------------------------
class HueShiftFieldLayer : public FieldLayerData
{
  INSTANCEOF(HueShiftFieldLayer, FieldLayerData)

public:
  // ------------------------------------------------------------------------------
  // Allocation of a new instance
  // @return    New HueShiftFieldLayer instance or nullptr.
  // ------------------------------------------------------------------------------
  static NodeData* Alloc()
  {
    iferr (NodeData * const result = NewObj(HueShiftFieldLayer))
    {
      DebugStop();
      return nullptr;
    }
    return result;
  }

  virtual maxon::Result<void> InitSampling(FieldLayer& layer, const FieldInfo& info, FieldShared& shared)
  {
    // store data for faster access during sampling

    const BaseContainer& layerBc = layer.GetDataInstanceRef();

    GeData data;
    if (!layerBc.GetParameter(FIELDLAYER_HUESHIFT_OFFSET, data))
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);

    _offset = data.GetFloat();

    return maxon::OK;
  }

  virtual maxon::Result<void> Sample(const FieldLayer& layer, const FieldInput& inputs, FieldOutputBlock& outputs, const FieldInfo& info) const
  {
    // handle each input position
    for (Int i = inputs._blockCount - 1; i >= 0; --i)
    {
      // get the color hue
      const Vector color = outputs._color[i];
      Vector       hsv = RGBToHSV(color);
      Float        hue = hsv.x;

      // hue shift
      hue = FMod(hue + _offset, 1.0);

      // store new color
      hsv.x = hue;
      outputs._color[i] = HSVToRGB(hsv);
    }

    return maxon::OK;
  }

  virtual void FreeSampling(FieldLayer& layer, const FieldInfo& info, FieldShared& shared)
  {
    // free internal data after sampling
  }

  virtual Bool IsEqual(const FieldLayer& layer, const FieldLayerData& comp) const
  {
    return true;
  }

private:
  Float _offset = 0.0_f;  
};

  // This example registeres the given FieldLayerData plugin.

  const Bool registerFieldLayerSuccess = RegisterFieldLayerPlugin(fieldLayerPluginID,
    "Hue Shift Layer"_s,
    "Changes the color hue."_s,
    "Hue Shift Layer"_s,
    FIELDLAYER_PREMULTIPLIED | FIELDLAYER_DIRECT | FIELDLAYER_NOVALUEOUT | FIELDLAYER_NODIRECTIONOUT | FIELDLAYER_NOROTATIONOUT,
    HueShiftFieldLayer::Alloc,
    "Flhueshift"_s,
    nullptr,
    0,
    nullptr);

  if (registerFieldLayerSuccess == false)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);

Further Reading

• MoGraph Overview
• FieldLayer
• General Plugin Information Manual