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__(self) Creates a new C4D_Falloff.
C4D_Falloff.InitFalloff(self[, bc, doc, op]) Initializes the falloff.
C4D_Falloff.Sample(self, point[, ...]) Samples the falloff for any point in space.
C4D_Falloff.MultiSample(self, points[, ...]) Samples the falloff for an array of points in space.
C4D_Falloff.AddFalloffToDescription(self, description[, bc]) Adds the falloff to a description.
C4D_Falloff.Message(self, id[, bc, data]) Sends messages to the falloff.
C4D_Falloff.GetHandleCount(self[, bc]) Returns the number of handles for the falloff.
C4D_Falloff.GetHandle(self, index, bc, info) Returns a handle for the falloff.
C4D_Falloff.SetHandle(self, index, point, bc, ...) Set a handle for the falloff.
C4D_Falloff.Draw(self, bd, bh, drawpass) Draws the falloff into a view.
C4D_Falloff.CopyTo(self, dest) Copies the falloff to another falloff.
C4D_Falloff.SetDirty(self) Sets the falloff dirty.
C4D_Falloff.GetDirty(self[, bc, doc]) Returns the falloff dirty value.
C4D_Falloff.SetMg(self, mg) Sets the falloff’s matrix.
C4D_Falloff.GetMg(self) Returns the falloff’s matrix.
C4D_Falloff.SetData(self, data) Sets the falloff’s data directly.
C4D_Falloff.GetData(self) Returns the falloff’s data.
C4D_Falloff.GetContainerInstance(self) Returns the last container the falloff should try to use.
C4D_Falloff.SetMode(self, type[, bc]) Sets the falloff mode.
C4D_Falloff.GetMode(self) Returns the falloff mode.
C4D_Falloff.SetTime(self, time[, bc]) Sets the current falloff time.

Methods Documentation

C4D_Falloff.__init__(self)

Creates a new C4D_Falloff.

Return type:c4d.modules.mograph.C4D_Falloff
Returns:A new falloff.
C4D_Falloff.InitFalloff(self, bc=None, doc=None, op=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 (c4d.BaseContainer) – Optional container of the object owning the falloff. If given the FalloffDataData is extracted from this container.
  • doc (c4d.documents.BaseDocument) – Optional document used to retrieve the current time for the animation of the Spline GUI offset.
  • op (c4d.BaseObject) – Optional object used to set the matrix. If no container is given for bc, this object’s container will be used instead.
Return type:

bool
Returns:

True if successful, otherwise False.
C4D_Falloff.Sample(self, point, usespline=True, weight=0.0)

Samples the falloff for any point in space.

Parameters:
  • 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, points, usespline=True, weight=0.0)

Samples the falloff for an array of points in space.

Parameters:
  • points (list of c4d.Vector) – The array of points 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:

list of float
Returns:

The sampled values.
C4D_Falloff.AddFalloffToDescription(self, description, bc=None)

Adds the falloff to a description.

Note

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

Parameters:
  • description (c4d.Description) – The description to add the falloff GUI to.
  • bc (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, 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

MSG for the information on the messages type, data and input/output.

Parameters:
  • id (int) – The message type.
  • bc (c4d.BaseContainer) – Optionally pass the container of the object owning the falloff.
  • data (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 (c4d.BaseContainer) – Optionally pass the container of the object owning the falloff.
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.
  • 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.
  • info (c4d.HandleInfo) – The information for the handle.
C4D_Falloff.Draw(self, 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:
  • 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 (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)

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:dest (c4d.modules.mograph.C4D_Falloff) – The destination falloff.
Return type:bool
Returns:True if successful, otherwise False.
C4D_Falloff.SetDirty(self)

Sets the falloff dirty.

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

Returns the falloff dirty value.

Note

Useful to check if the falloff needs to be resampled.

Parameters:
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 (c4d.BaseContainer) – Optionally pass the container of the object owning the falloff.
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: