C4D_Falloff Class Reference

#include <c4d_falloffdata.h>

Detailed Description

Represents a falloff. Allows to sample falloffs.
It is very simple in use: allocate it, call InitFalloff() first then Sample() giving it a point in world space.

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

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

Note
To add a falloff to a description use AddFalloffToDescription.

Public Member Functions

BaseContainerGetContainerInstance (void)
 
void SetTime (BaseTime time, BaseContainer *bc=nullptr)
 
Bool InitFalloff (BaseContainer *bc=nullptr, BaseDocument *doc=nullptr, BaseObject *op=nullptr)
 
Bool PreSample (BaseDocument *doc, BaseList2D *op, const FieldInput &inputs, FIELDSAMPLE_FLAG flags)
 
const FieldOutputGetSamples ()
 
void Sample (const Vector &p, Float *result, Bool usespline=true, Float weight=0.0_f, BaseList2D *op=nullptr, Int index=-1)
 
void MultiSample (const Vector *p, Float *result, Int count, Bool usespline=true, Float weight=0.0_f, BaseList2D *op=nullptr)
 
Bool HasContent (BaseContainer *bc) const
 
Bool AddFalloffToDescription (Description *description, BaseContainer *bc, DESCFLAGS_DESC flags, Bool showValue=true, Bool showColor=false, Bool showDirection=false, Bool showRotation=false)
 
Bool Message (Int32 id, BaseContainer *bc=nullptr, void *m_data=nullptr)
 
Bool Draw (BaseDraw *bd, BaseDrawHelp *bh, DRAWPASS drawpass, BaseContainer *bc=nullptr)
 
Bool CopyTo (C4D_Falloff *dest) const
 
Bool GetDEnabling (const DescID &id, const BaseContainer &bc, Bool &enabled)
 
Bool IsFields () const
 
FIELDLIST_FLAGS GetChannelFlags () const
 
void SetChannelFlags (FIELDLIST_FLAGS flags, BaseContainer *bc)
 

Private Member Functions

 C4D_Falloff ()
 
 ~C4D_Falloff (void)
 

Alloc/Free

static C4D_FalloffAlloc (Int cType=0)
 
static void Free (C4D_Falloff *&node)
 

Dirty

void SetDirty (void)
 
Int32 GetDirty (BaseDocument *doc, BaseContainer *bc=nullptr)
 

Matrix

void SetMg (Matrix mg)
 
Matrix GetMg (void)
 

Data

void SetData (FalloffDataData falldata)
 
FalloffDataData GetData (void)
 

Mode

Bool SetMode (Int32 type, BaseContainer *bc=nullptr)
 
Int32 GetMode (void)
 

Handle

Int32 GetHandleCount (BaseContainer *bc=nullptr)
 
void GetHandle (Int32 i, BaseContainer *bc, HandleInfo &info)
 
void SetHandle (Int32 i, Vector p, BaseContainer *bc, const HandleInfo &info)
 

Constructor & Destructor Documentation

◆ C4D_Falloff()

C4D_Falloff ( )
private

◆ ~C4D_Falloff()

~C4D_Falloff ( void  )
private

Member Function Documentation

◆ Alloc()

static C4D_Falloff* Alloc ( Int  cType = 0)
static

Allocates a falloff. Destroy the allocated falloff with Free(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in]cType(Optional) the type.
Returns
The allocated falloff, or nullptr if the allocation failed.

◆ Free()

static void Free ( C4D_Falloff *&  node)
static

Destructs falloffs allocated with Alloc(). Use AutoAlloc to automate the allocation and destruction based on scope.

Parameters
[in,out]nodeThe falloff to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

◆ GetContainerInstance()

BaseContainer* GetContainerInstance ( void  )

Gets 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.
Warning
Can be nullptr. If the falloff has been initialized at some point with a container, but subsequently the original container is no longer available this could be a bad pointer.
Returns
The container instance.

◆ SetDirty()

void SetDirty ( void  )

Sets the falloff dirty.

◆ GetDirty()

Int32 GetDirty ( BaseDocument doc,
BaseContainer bc = nullptr 
)

Gets the falloff dirty value.

Note
Useful for checking if the falloff needs to be resampled.
Parameters
[in]docThe document.
[in]bcOptionally pass the container of the object owning the falloff (recommended).
Returns
The dirty value.

◆ SetMg()

void SetMg ( Matrix  mg)

Sets the falloff's matrix.

Parameters
[in]mgThe new matrix.

◆ GetMg()

Matrix GetMg ( void  )

Gets the falloff's matrix.

Returns
The matrix.

◆ SetData()

void SetData ( FalloffDataData  falldata)

Sets the falloff's data directly.

Parameters
[in]falldataThe new falloff's data.

◆ GetData()

FalloffDataData GetData ( void  )

Gets the falloff's data.

Returns
The falloff's data.

◆ SetMode()

Bool SetMode ( Int32  type,
BaseContainer bc = nullptr 
)

Sets the falloff mode.

Note
The falloff mode is normally the falloff's ID (see ofalloff_panel.h).
Parameters
[in]typeThe new falloff mode.
[in]bcOptionally pass the container of the object owning the falloff (recommended).
Returns
true if the mode was set, otherwise false.

◆ GetMode()

Int32 GetMode ( void  )

Gets the falloff mode.

Note
The fallof's mode is normally the falloff's ID (see ofalloff_panel.h).
Returns
The falloff's mode.

◆ SetTime()

void SetTime ( BaseTime  time,
BaseContainer bc = nullptr 
)

Sets the current falloff time.
Used for the animated Spline GUI offset, not for any other values currently.

Parameters
[in]timeThe new falloff time.
[in]bcOptionally pass the container of the object owning the falloff (recommended).

◆ InitFalloff()

Bool InitFalloff ( BaseContainer bc = nullptr,
BaseDocument doc = nullptr,
BaseObject op = nullptr 
)

Initializes the falloff.

Warning
Always call before the sample routines.
Note
It is recommended to fill at least one of the settings, however not compulsory.
Parameters
[in]bcOptional container of the object owning the falloff. If given the FalloffDataData will be extracted from this container.
[in]docOptional document used to retrieve the current time for the animation of the Spline GUI offset.
[in]opOptional object used to set the matrix if given, and if no container is given for bc, its container will be used instead.
Returns
true if successful, otherwise false.

◆ PreSample()

Bool PreSample ( BaseDocument doc,
BaseList2D op,
const FieldInput inputs,
FIELDSAMPLE_FLAG  flags 
)

Pre-samples an array of points for much faster usage with fields. Sampling result will be stored internally until the next call to PreSample. Use GetSamples() to read pre-sampling result. Only used with fields. If falloff is in legacy mode, PreSample will return true and do mothing. Use PreSample to allow calls to Sample within parallel for loops.

Parameters
[in]docThe document.
[in]opThe object.
[in]inputsThe point array to sample.
[in]flagsThe sampling flags.
Returns
true if it succeeds, false if it fails.

◆ GetSamples()

const FieldOutput* GetSamples ( )

Gets the samples calculated by PreSample.

Returns
null if there are no samples, else the samples.

◆ Sample()

void Sample ( const Vector p,
Float result,
Bool  usespline = true,
Float  weight = 0.0_f,
BaseList2D op = nullptr,
Int  index = -1 
)

Samples the falloff for any point in space. NOTE: Do not call Sample within a parallel for loop when using fields without PreSample called first. When using fields: -If user calls PreSample first, Sample will quickly return the pre-sampled result. This case is thread safe. -If PreSample was not called, Sample will sample the fields. This case is not thread safe. When using legacy falloffs: -Sample supports parallel for loops.

Parameters
[in]pThe point to sample in global space (ignored with pre-sampling).
[out]resultAssigned the sampled value.
[in]usesplineUse the GUI spline if it exists (default, ignored with pre-sampling).
[in]weightWeight offset. Equivalent of adding this value to the falloff result before clamping (optional, ignored with fields).
[in]opthe object (ignored with pre-sampling).
[in]indexzero-based index of the sample (when using pre-sampling).

◆ MultiSample()

void MultiSample ( const Vector p,
Float result,
Int  count,
Bool  usespline = true,
Float  weight = 0.0_f,
BaseList2D op = nullptr 
)

Samples the falloff for an array of points in space. The result will be returned in the Float array but also stored internally, overwriting the last PreSample call result.

Parameters
[in]pThe array of points to sample. The caller owns the pointed array.
[out]resultAssigned the sampled values.
[in]countThe size of array p.
[in]usesplineUse the GUI spline if it exists (default).
[in]weightAn optional weight offset. Equivalent of adding this value to the falloff result before clamping.
[in]op(Optional) the object.

◆ HasContent()

Bool HasContent ( BaseContainer bc) const

Checks to see whether the Falloff has any sampling content.

Parameters
[in]bcThe basecontainer of the owning object.
Returns
True if content, false if not.

◆ AddFalloffToDescription()

Bool AddFalloffToDescription ( Description description,
BaseContainer bc,
DESCFLAGS_DESC  flags,
Bool  showValue = true,
Bool  showColor = false,
Bool  showDirection = false,
Bool  showRotation = false 
)

Adds the falloff to a description.

Note
Use this function within the implementation of NodeData::GetDDescription.
Parameters
[in]descriptionThe description to add the falloff GUI to.
[in]bcOptionally pass the container of the object owning the falloff.
[in]flagsGetDescription flags.
[in]showValue(Optional) True to show, false to hide the value channel of the FieldList.
[in]showColor(Optional) True to show, false to hide the color channel of the FieldList.
[in]showDirection(Optional) True to show, false to hide the direction channel of the FieldList.
[in]showRotation(Optional) True to show, false to hide the rotation channel of the FieldList.
Returns
true if successful, otherwise false.

◆ Message()

Bool Message ( Int32  id,
BaseContainer bc = nullptr,
void *  m_data = nullptr 
)

Sends messages to the falloff.

Note
Use this function from within the implementation of NodeData::Message to pass all messages on to the falloff, or just send a message with it normally as needed.
Parameters
[in]idThe message type: MSG
[in]bcOptionally pass the container of the object owning the falloff.
[in,out]m_dataThe message data. The sender owns the pointed data.
Returns
true if successful, otherwise false.

◆ GetHandleCount()

Int32 GetHandleCount ( BaseContainer bc = nullptr)

Gets the number of handles for the falloff.

Note
Use this function from within the implementation of ObjectData::GetHandleCount.
Parameters
[in]bcOptionally pass the container of the object owning the falloff (recommended). Necessary to have user controllable handles.
Returns
The handle count.

◆ GetHandle()

void GetHandle ( Int32  i,
BaseContainer bc,
HandleInfo info 
)

Gets a handle for the falloff.

Note
Use this function from within the implementation of ObjectData::GetHandle.
Parameters
[in]iThe handle index.
[in]bcThe falloff's container; normally this is the owning object's container.
[out]infoFilled with the information for handle i.

◆ SetHandle()

void SetHandle ( Int32  i,
Vector  p,
BaseContainer bc,
const HandleInfo info 
)

Called to set a handle for the falloff.

Note
Use this function from within the implementation of ObjectData::SetHandle.
Parameters
[in]iThe handle index.
[in]pThe new position for handle i.
[in]bcThe falloff's container; normally this is the owning object's container.
[out]infoThe information for handle i.

◆ Draw()

Bool Draw ( BaseDraw bd,
BaseDrawHelp bh,
DRAWPASS  drawpass,
BaseContainer bc = nullptr 
)

Draws the falloff in the viewport.

Note
Use this function from within the implementation of ObjectData::Draw or ToolData::Draw.
Parameters
[in]bdThe editor's view. The caller owns the pointed base draw.
[in]bhThe editor's view help. The caller owns the pointed base draw help.
[in]drawpassThe draw pass: DRAWPASS
[in]bcOptionally pass the container of the object owning the falloff (recommended).
Returns
true if successful, otherwise false.

◆ CopyTo()

Bool CopyTo ( C4D_Falloff dest) const

Copies the falloff.

Note
Use this function from within the implementation of NodeData::CopyTo; necessary for handles to work correctly with the undo system in Cinema 4D.
Parameters
[out]destThe destination falloff.
Returns
true if successful, otherwise false.

◆ GetDEnabling()

Bool GetDEnabling ( const DescID id,
const BaseContainer bc,
Bool enabled 
)

Disables falloff parameters when falloff type is infinite.

Since
R19.SP2
Note
Use this function within the implementation of NodeData::GetDEnabling():
Bool MyNodeDataObject::GetDEnabling(GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer *itemdesc)
{
if (!node)
return true;
if (_fallOff) // _fallOff is C4D_Falloff* type
{
BaseObject* op = (BaseObject*)node;
if (op)
{
if (bc)
{
Bool enabled = true;
Bool handled = m_pFallOff->GetDEnabling(id, *bc, enabled);
if (handled)
return enabled;
}
}
}
return SUPER::GetDEnabling(node, id, t_data, flags, itemdesc);
}
Parameters
[in]idThe parameter id.
[in]bcThe falloff's container; normally this is the owning object's container.
[out]enabledThe parameter enabled state.
Returns
true if handled, otherwise false.

◆ IsFields()

Bool IsFields ( ) const

Checks whether the Falloff is using fields or not.

Returns
if the falloff is using fields rather than old falloffs}

◆ GetChannelFlags()

FIELDLIST_FLAGS GetChannelFlags ( ) const

When working with Fields this retrieves the current display channel flags for the FieldList

Returns
The channel flags.

◆ SetChannelFlags()

void SetChannelFlags ( FIELDLIST_FLAGS  flags,
BaseContainer bc 
)

When working with Fields this sets the channel flags that control how the FieldLIst will display.

Parameters
[in]flagsThe flags to set.
[in,out]bcIf non-null the container of the object the C4D_Falloff belongs to.