c4d.modules.mograph.C4D_Falloff

class c4d.modules.mograph.C4D_Falloff
Represents a falloff and allows to sample falloffs.
It is very simple in use: allocate it, call C4D_Falloff.InitFalloff() first then C4D_Falloff.Sample() or C4D_Falloff.MultiSample().

New in version R19.

Many of the methods are there for use within NodeData/ObjectData/ToolData plugins and should be called within their likewise counterparts.
For instance C4D_Falloff.Draw() should be called from within the corresponding ObjectData/ToolData Draw() implementation, then the falloff will be drawn in the viewport.

C4D_Falloff normally needs a container, this is usually the object’s container. From this container it gets and sets its own parameters for the description, though they can be set directly using the helper functions.

Methods Signatures

C4D_Falloff.__init__()

Creates a new C4D_Falloff.

C4D_Falloff.InitFalloff()

Initializes the falloff.

C4D_Falloff.Sample()

Samples the falloff for any point in space.

C4D_Falloff.MultiSample()

Samples the falloff for an array of points in space.

C4D_Falloff.AddFalloffToDescription()

Adds the falloff to a description.

C4D_Falloff.Message()

Sends messages to the falloff.

C4D_Falloff.GetHandleCount()

Returns the number of handles for the falloff.

C4D_Falloff.GetHandle()

Returns a handle for the falloff.

C4D_Falloff.SetHandle()

Set a handle for the falloff.

C4D_Falloff.Draw()

Draws the falloff into a view.

C4D_Falloff.CopyTo()

Copies the falloff to another falloff.

C4D_Falloff.SetDirty()

Sets the falloff dirty.

C4D_Falloff.GetDirty()

Returns the falloff dirty value.

C4D_Falloff.SetMg()

Sets the falloff’s matrix.

C4D_Falloff.GetMg()

Returns the falloff’s matrix.

C4D_Falloff.SetData()

Sets the falloff’s data directly.

C4D_Falloff.GetData()

Returns the falloff’s data.

C4D_Falloff.GetContainerInstance()

Returns the last container the falloff should try to use.

C4D_Falloff.SetMode()

Sets the falloff mode.

C4D_Falloff.GetMode()

Returns the falloff mode.

C4D_Falloff.SetTime()

Sets the current falloff time.

Methods Documentation

C4D_Falloff.__init__(self, parentBc=None, cType=0)

Creates a new C4D_Falloff.

Parameters

  • parentBc – Optional[c4d.BaseContainer]

  • cType – int

C4D_Falloff.InitFalloff(self, bc=None, doc=None, op=None, data=None)

Initializes the falloff.

Warning

Always call before the sample routines.

Note

It is recommended to pass at least one of the parameters, however not compulsory.

Parameters

  • bc (Optional[c4d.BaseContainer]) –

    Deprecated since version 2024.0.0:
    Not used anymore and going to be removed in 2025.0.
    Optional container of the object owning the falloff. If given the FalloffDataData is extracted from this container.

  • doc (Optional[c4d.documents.BaseDocument]) – Optional document used to retrieve the current time for the animation of the Spline GUI offset.

  • op (Optional[c4d.BaseObject]) – Optional object used to set the matrix. If no container is given for bc, this object’s container will be used instead.

  • data (Optional[c4d.modules.mograph.FalloffDataData]) –

    New in version 2024.0.0.

    The data to define the falloff.

Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.Sample(self, op, point, usespline=True, weight=0.0)

Samples the falloff for any point in space.

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • point (c4d.Vector) – The point to sample in world space.

  • usespline (bool) – Use the Spline GUI if it exists. Defaults to True.

  • weight (float) – An optional weight offset. Equivalent of adding this value to the falloff result before clamping.

Return type

float

Returns

The sampled value.

C4D_Falloff.MultiSample(self, op, points, usespline=True, weight=0.0)

Samples the falloff for an array of points in space.

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • points (List[c4d.Vector]) – The array of points to sample in world space.

  • usespline (bool) – Use the Spline GUI if it exists. Defaults to True.

  • weight (Optional[float]) – An optional weight offset. Equivalent of adding this value to the falloff result before clamping.

Return type

List[float]

Returns

The sampled values.

C4D_Falloff.AddFalloffToDescription(self, op, description, bc=None)

Adds the falloff to a description.

Note

Use this function within the implementation of NodeData.GetDDescription().

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • description (c4d.Description) – The description to add the falloff GUI to.

  • bc (Optional[c4d.BaseContainer]) – Optionally pass the container of the object owning the falloff.

Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.Message(self, op, id, bc=None, data=None)

Sends messages to the falloff.

Note

Use this function from within the implementation of NodeData.Message() to pass all messages to the falloff.

See also

C4DAtom and Plugin Messages for information on the messages type, data and input/output.

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • id (int) – The message type.

  • bc (Optional[c4d.BaseContainer]) – Optionally pass the container of the object owning the falloff.

  • data (Optional[any]) – The message data.

Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.GetHandleCount(self, bc=None)

Returns the number of handles for the falloff.

Note

Use this function from within the implementation of ObjectData.GetHandleCount().

Parameters

bc (Optional[c4d.BaseContainer]) –

Optionally pass the container of the object owning the falloff.

Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.

Return type

int

Returns

The handle count.

C4D_Falloff.GetHandle(self, index, bc, info)

Returns a handle for the falloff.

Note

Use this function from within the implementation of ObjectData.GetHandle().

Parameters

  • index (int) – The handle index.

  • bc (c4d.BaseContainer) –

    The falloff’s container. Normally this is the owning object’s container.

    Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.

  • info (c4d.HandleInfo) – The information for the requested handle.

C4D_Falloff.SetHandle(self, index, point, bc, info)

Set a handle for the falloff.

Note

Use this function from within the implementation of ObjectData.SetHandle().

Parameters

  • index (int) – The handle index.

  • point (c4d.Vector) – The new position for the handle.

  • bc (c4d.BaseContainer) –

    The falloff’s container. Normally this is the owning object’s container.

    Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.

  • info (c4d.HandleInfo) – The information for the handle.

C4D_Falloff.Draw(self, op, bd, bh, drawpass, bc=None)

Draws the falloff into a view.

Note

Use this function from within the implementation of ObjectData.Draw() or ToolData.Draw().

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • bd (c4d.BaseDraw) – The editor’s view.

  • bh (c4d.plugins.BaseDrawHelp) – The editor’s view help.

  • drawpass (int) –

    The draw pass:

    DRAWPASS_OBJECT

    Object pass.

    DRAWPASS_BOX

    Box pass.

    DRAWPASS_HANDLES

    Handle pass.

    DRAWPASS_HIGHLIGHTS

    Highlights pass.

    DRAWPASS_XRAY

    X-Ray pass.

  • bc (Optional[c4d.BaseContainer]) – Optionally pass the container of the object owning the falloff.

Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.CopyTo(self, dest, op)

Copies the falloff to another falloff.

Note

Use this function from within the implementation of NodeData.CopyTo(). Necessary for handles to work correctly with the undo system.

Parameters
Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.SetDirty(self)

Sets the falloff dirty.

C4D_Falloff.GetDirty(self, op, bc=None, doc=None)

Returns the falloff dirty value.

Note

Useful to check if the falloff needs to be resampled.

Parameters

  • op (c4d.BaseList2D) –

    New in version 2024.0.0.

    The object (ignored with pre-sampling)

  • bc (Optional[c4d.BaseContainer]) –

    Optionally pass the container of the object owning the falloff.

    Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.

  • doc (Optional[c4d.documents.BaseDocument]) –

    New in version R20: The document.

Return type

int

Returns

The dirty value.

C4D_Falloff.SetMg(self, mg)

Sets the falloff’s matrix.

Parameters

mg (c4d.Matrix) – The new falloff’s matrix.

C4D_Falloff.GetMg(self)

Returns the falloff’s matrix.

Return type

c4d.Matrix

Returns

The matrix.

C4D_Falloff.SetData(self, data)

Sets the falloff’s data directly.

Parameters

data (c4d.modules.mograph.FalloffDataData) – The new falloff’s data.

C4D_Falloff.GetData(self)

Returns the falloff’s data.

Return type

c4d.modules.mograph.FalloffDataData

Returns

The falloff’s data.

C4D_Falloff.GetContainerInstance(self)

Returns the last container the falloff should try to use.

Note

If the falloff has not been given a container at any point it will generate one internally.

Return type

c4d.BaseContainer

Returns

The falloff’s container instance. Guaranteed to be always valid.

C4D_Falloff.SetMode(self, type, bc=None)

Sets the falloff mode.

Parameters

  • type (int) – The new falloff mode. See ofalloff_panel.h.

  • bc (Optional[c4d.BaseContainer]) –

    Optionally pass the container of the object owning the falloff.

    Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.

Return type

bool

Returns

True if successful, otherwise False.

C4D_Falloff.GetMode(self)

Returns the falloff mode.

Return type

int

Returns

The falloff’s mode. See ofalloff_panel.h.

C4D_Falloff.SetTime(self, time, bc=None)

Sets the current falloff time.

Note

Used only for the animated Spline GUI offset, not for any other values currently.

Parameters

  • time (c4d.BaseTime) – The new falloff time.

  • bc (Optional[c4d.BaseContainer]) –

    Optionally pass the container of the object owning the falloff.

    Deprecated since version 2024.0.0: Unused since 2024.0, this argument will be removed in 2025.0.0.