c4d.modules.mograph.C4D_Falloff

New in version R19.

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().

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.

Members

C4D_Falloff.__init__()

Creates a new C4D_Falloff.

Return type:c4d.modules.mograph.C4D_Falloff
Returns:A new falloff.
C4D_Falloff.InitFalloff([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(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(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(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(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.

Parameters:
  • id (int) –

    The message type:

    MSG_POINTS_CHANGED The points have changed. The corresponding data is VariableChanged.
    MSG_POLYGONS_CHANGED The polygons have changed. The corresponding data is VariableChanged.
    MSG_UPDATE Must be sent if the bounding box has to be recalculated. (Otherwise you can use MSG_CHANGE.)
    MSG_SMALLUPDATE Part of the object has changed that needs no cache rebuilding. Note: This message should be used very carefully, it is there for (small) performance enhancements, for example if a polygon selection is changed then the caches needn’t be rebuilt, so MSG_SMALLUPDATE can be sent.
    MSG_CHANGE Must be sent if any object data (except for the matrix) has been changed.
    MSG_BASECONTAINER Message with a container, for example from a C.O.F.F.E.E. plugin. The corresponding data is BaseContainer.
    MSG_SEGMENTS_CHANGED The segments have changed. The corresponding data is VariableChanged.
    MSG_FILTER A message filter that lets you block C4DAtom.MultiMessage() calls. The corresponding data is MessageFilter. Return True to let the message pass and False to block it!
    MSG_TRANSFERGOALS Internal message!
    MSG_DESCRIPTION_INITUNDO Allows elements to create undo actions for the following parameter changes in the attributes manager. This is already automatically handled for keys, tags, objects etc. The corresponding data is DescriptionInitUndo.
    MSG_DESCRIPTION_CHECKUPDATE Allows elements to determine the type of refresh after a parameter has been changed in the Active manager. This is already automatically handled for keys, tags, objects etc. The corresponding data is DescriptionCheckUpdate. Note: Currently this message is completely handled by all baseclasses. Most plugins won’t need to modify the message data. it is more interesting to start some update action - e.g. deleting data that will be rebuilt with the next access.
    MSG_DESCRIPTION_CHECKUPDATE_AUTOTAKE

    New in version R17.032.

    Element supports automatic Take overrides.

    MSG_DESCRIPTION_CHECKUPDATE_BASELISTEDIT

    New in version R17.032.

    Edit node is updating the current Take override value.

    MSG_DESCRIPTION_COMMAND Sent by for example BUTTON (description element). See example below.
    MSG_DESCRIPTION_POPUP Allows popup menu handling in the Attribute Manager. The corresponding data is DescriptionPopup.
    MSG_DESCRIPTION_POSTSETPARAMETER After a SetParameter() call to an atom element this message is sent to the object. The corresponding data is DescriptionPostSetValue.
    MSG_DESCRIPTION_VALIDATE Allows you to update dependencies or to check for invalid values after a parameter has been changed (For example: the light’s inner radius always must be smaller than the light’s outer radius - so this routine checks for it and corrects it). The corresponding data is DescriptionValidate.
    MSG_EDIT Allows elements to do some action if the user edits the element (doubleclick e.g. in object manager).
    MSG_MENUPREPARE Allows tags, objects, shaders etc. to do some setup work when called from the menu. The corresponding data is the current BaseDocument.
    MSG_RETRIEVEPRIVATEDATA A generic private message to retrieve data from an object. Specific for every type of object so no public documentation available. The corresponding data is RetrievePrivateData.
    MSG_DESCRIPTION_REMOVE_ENTRY Tells the node to remove a description entry. The corresponding data is DescriptionCommand.
    MSG_DESCRIPTION_EDIT_ENTRY Tells the node to edit a description entry. The corresponding data is DescriptionCommand.
    MSG_DESCRIPTION_CHECKDRAGANDDROP Asks the node if a drag and drop onto for example a LINK (description element) field should be accepted. The corresponding data is DescriptionCheckDragAndDrop.
    MSG_DESCRIPTION_GETBITMAP Queries the object for updated bitmaps for BitmapButtonCustomGui elements in the description. (E.g. the lens flare preview.) The corresponding data is DescriptionGetBitmap.
    MSG_DESCRIPTION_GETOBJECTS Private.
    MSG_DESCRIPTION_USERINTERACTION_END End of user interaction.
    MSG_DESCRIPTION_GETINLINEOBJECT Sent by the Attribute Manager to the object. The object can check for a description ID and return the linked objects in the atom array. The corresponding data is DescriptionInlineObjectMsg.
    MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION

    New in version R19.

    Sent by a custom GUI to the parent NodeData.

    MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_ID

    New in version R19.

    The custom GUI ID in the message container for MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION.

    MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION_CONTENT

    New in version R19.

    The user data in the message container for MSG_DESCRIPTION_CUSTOMGUI_NOTIFICATION.

    MSG_DESCRIPTION_ALLOWOVERRIDE

    New in version R17.032.

    Sent before a Take override is added to allow it or not. The corresponding data is DescriptionAllowOverride.

    MSG_DESCRIPTION_TAKECHANGED

    New in version R17.032.

    Sent to each overridden node when the user changes the current Take. Sent to both the node storing the data in the Take and the node releasing the data to the document. The corresponding data is DescriptionTakeChanged.

    MSG_MOVE_FINISHED Sent after a handle or the object has been moved.
    MSG_MOVE_START Sent before a handle or the object has been moved.
    MSG_EDITABLE_END Private.
    MSG_GETCUSTOMICON Every atom can return a custom icon with this message. The corresponding data is GetCustomIconData.
    MSG_MATERIALDRAGANDDROP Received by a material upon dropping an instance of the material onto an object. The material can choose to create a tag of its own, or trigger other actions, instead of letting Cinema 4D create a normal material assignment. The corresponding data is MaterialDragAndDrop. For example Sketch and Toon creates its own type of tag and returns it in result. Cinema 4D creates the undo for it and activates it. Inserting the tag is done by the material.
    MSG_DRAGANDDROP Received when something is dropped on it. The corresponding data is DragAndDrop.
    MSG_INITIALCHANNEL See HandleInitialChannel().
    MSG_DOCUMENTINFO Sent as broadcast message to the document when it its loaded, saved etc. The corresponding data is DocumentInfoData. (See the type member for more information about when the message is sent.)
    MSG_GETSELECTION Private.
    MSG_MULTI_RENDERNOTIFICATION A document and all of its elements receive this message before a render starts. The corresponding data is RenderNotificationData.
    MSG_MULTI_MARKMATERIALS When data is None this is sent to plugin nodes to let them mark the materials that they use. Otherwise the message is sent to let you translate you material links, for example when a material is replaced, and then the corresponding structure is MarkMaterials. (An example for both cases is included on the MarkMaterials page.)
    MSG_MULTI_DOCUMENTCLONED The document has been cloned.
    MSG_MULTI_DOCUMENTIMPORTED After a Cinema 4D document has been loaded this message is sent to the document (and all children structures). The corresponding data is DocumentImported.
    MSG_MULTI_SETNEWMARKERS Private.
    MSG_MULTI_CLEARSUGGESTEDFOLDER Objects have to remove absolute paths (only if they support MSG_GETALLASSETS). Both are important for SaveProject to work and to collect all items.
    MSG_TOOL_SWITCHACTION

    New in version R17.032.

    Sent to tools on mouse input and cursor info if they have the flag PLUGINFLAG_TOOL_SWITCHACTION set to allow to change action on modifier key.

    MSG_TRANSLATE_POINTS Sent by the modeling core to let tags etc. update after point changes. The corresponding data is TranslationMaps.
    MSG_TRANSLATE_POLYGONS Sent by the modeling core to let tags etc. update after polygon changes. The corresponding data is TranslationMaps.
    MSG_TRANSLATE_NGONS Sent by the modeling core to let tags etc. update after N-gon changes. The corresponding data is TranslationMaps.
    MSG_TRANSLATE_SEGMENTS Sent by the modeling core to let tags etc. update after segment changes. The corresponding data is TranslationMaps.
    MSG_PRETRANSLATE_POINTS Sent before MSG_TRANSLATE_POINTS, before the changes are actually carried out. The corresponding data is TranslationMaps.
    MSG_PRETRANSLATE_POLYGONS Sent before MSG_TRANSLATE_POLYGONS, before the changes are actually carried out. The corresponding data is TranslationMaps.
    MSG_PRETRANSLATE_NGONS Sent before MSG_TRANSLATE_NGONS, before the changes are actually carried out. The corresponding data is TranslationMaps.
    MSG_PRETRANSLATE_SEGMENTS Sent before MSG_TRANSLATE_SEGMENTS, before the changes are actually carried out. The corresponding data is TranslationMaps.
    MSG_UPDATE_NGONS Should be sent if points are changed and any N-gons need updating. Cinema 4D will then update the N-gons, if the user has this option enabled.
    MSG_DOCUMENT_MODE_CHANGED Sent to the active tool plugin during BaseDocument.SetMode().
    MSG_TOOL_RESTART Private. (Handles the tool description apply behaviour after mouse clicks.)
    MSG_DEFORMMODECHANGED Private.
    MSG_ANIMATE Sent to objects after they have been animated.
    MSG_CALCMEMUSAGE Private.
    MSG_SCALEDOCUMENT Tells the document that another document with different scale has been merged. The corresponding data is MessageScaleDocument.
    MSG_GET_INHERITANCECONTAINER Private.
    MSG_SOFTTAG_UPDATE Private.
  • 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([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(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(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(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(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()

Sets the falloff dirty.

C4D_Falloff.GetDirty([bc=None])

Returns the falloff dirty value.

Note

Useful to check if the falloff needs to be resampled.

Parameters:bc (c4d.BaseContainer) – Optionally pass the container of the object owning the falloff.
Return type:int
Returns:The dirty value.
C4D_Falloff.SetMg(mg)

Sets the falloff’s matrix.

Parameters:mg (c4d.Matrix) – The new falloff’s matrix.
C4D_Falloff.GetMg()

Returns the falloff’s matrix.

Return type:c4d.Matrix
Returns:The matrix.
C4D_Falloff.SetData(data)

Sets the falloff’s data directly.

Parameters:data (c4d.modules.mograph.FalloffDataData) – The new falloff’s data.
C4D_Falloff.GetData()

Returns the falloff’s data.

Return type:c4d.modules.mograph.FalloffDataData
Returns:The falloff’s data.
C4D_Falloff.GetContainerInstance()

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(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()

Returns the falloff mode.

Return type:int
Returns:The falloff’s mode. See ofalloff_panel.h.
C4D_Falloff.SetTime(time[, bc=None])

Sets the current falloff time.

Note

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

Parameters: