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) == false)
 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