Snapping

Detailed Description

Snap system has been completely redesigned and rewritten in R14.
The new snapping API is made of powerful classes and structs:

Data structures:

Here is how we could use the old snapping API, i.e. DetectSnapping class:

if (!snap)
return false;
snap->Init(doc, bd, nullptr, Vector(), 0, false, true, true);
Vector delta;
if(snap->IsEnabled(doc))
{
if (snap->SnapTo(pos, &delta))
{
pos += delta;
}
}

DetectSnapping has been removed and now the interface class for snapping is SnapCore.
Here is the above code converted to use the new snapping API in R14:

if (!snap)
return false;
snap->Init(doc, bd);
if (IsSnapEnabled(doc))
{
if (snap->Snap(pos, res))
{
pos += res.delta;
}
}

Groups

 PLUGINFLAG_SNAP
 
 SNAPFLAGS
 
 SNAPPRIORITY
 

Classes

struct  SnapPoint
 
struct  SnapResult
 
struct  SnapExclude
 
struct  SnapStruct
 
class  SnapData
 
class  SnapCore
 

Macros

#define ID_SNAPCORE_LIB
 

Typedefs

typedef SnapDataSnapDataAllocator(void)
 

Functions

Bool IsSnapEnabled (BaseDocument *doc, Int32 mode=-1)
 
void EnableSnap (Bool state, BaseDocument *doc, Int32 mode=-1)
 
BaseContainer SnapSettings (BaseDocument *doc, Int32 snapmode=-1)
 
void SnapSettings (BaseDocument *doc, const BaseContainer &bc, Int32 snapmode=-1)
 
Bool IsQuantizeEnabled (BaseDocument *doc)
 
Float QuantizeStep (BaseDocument *doc, BaseDraw *bd, Int32 quantize_mode)
 
void QuantizeStep (BaseDocument *doc, BaseDraw *bd, Int32 quantize_mode, Float val)
 
Bool GetConstructionPlane (BaseDraw *bd, Matrix *mg, Vector *scale, BaseObject **op)
 
BaseObjectGetWorkplaneObject (BaseDocument *doc)
 
Bool WorkplaneLock (BaseDocument *doc)
 
void WorkplaneLock (BaseDraw *bd, Int32 locked)
 
Matrix GetWorkplaneMatrix (BaseDocument *doc, BaseDraw *bd)
 
Bool RegisterSnapPlugin (Int32 id, const maxon::String &str, const maxon::String &help, Int32 snapinfo, SnapDataAllocator *npalloc, BaseBitmap *icon, SNAPPRIORITY priority=SNAPPRIORITY::EDGE, Int32 parent_mode=-1)
 

Variables

struct SnapPoint MAXON_ENUM_LIST
 

Macro Definition Documentation

◆ ID_SNAPCORE_LIB

#define ID_SNAPCORE_LIB

SnapCore library ID.

Typedef Documentation

◆ SnapDataAllocator

typedef SnapData* SnapDataAllocator(void)

Snap allocator type, used purely in RegisterSnapPlugin().

Function Documentation

◆ IsSnapEnabled()

Bool IsSnapEnabled ( BaseDocument doc,
Int32  mode = -1 
)

Checks if snap is enabled for the document doc or for a specific mode.

Parameters
[in]docThe document to check. The caller owns the pointed document.
[in]modeOptionally set a snap mode instead of checking snap for the document.
For example SNAPMODE_GUIDE. See description\dmodeling.h for snap mode IDs.
Returns
true if snap is enabled, otherwise false.

◆ EnableSnap()

void EnableSnap ( Bool  state,
BaseDocument doc,
Int32  mode = -1 
)

Sets the snap enabled state for the document doc or a particular mode.

Parameters
[in]stateThe state to set: true to enable, false to disable.
[in]docThe document to set the snap mode state for. The caller owns the pointed document.
[in]modeOptionally set a snap mode instead of enabling snap for the document.
For example SNAPMODE_GUIDE. See description\dmodeling.h for snap mode IDs.

◆ SnapSettings() [1/2]

BaseContainer SnapSettings ( BaseDocument doc,
Int32  snapmode = -1 
)

Gets the snap settings for the document doc or a specific mode.

Parameters
[in]docThe document related snap settings to get. The caller owns the pointed document.
[in]snapmodeOptionally specify a snap mode to get or modify its specific settings instead of the global settings.
For example SNAPMODE_GUIDE. See description\dmodeling.h for snap mode IDs.
Returns
A copy of the snap settings container. See description\dmodeling.h for more information on the returned container.

◆ SnapSettings() [2/2]

void SnapSettings ( BaseDocument doc,
const BaseContainer bc,
Int32  snapmode = -1 
)

Sets the snap settings for the document doc or a specific snapmode.

Note
After changing the snap settings, call SpecialEventAdd() with ID 440000118 for the snap system to recognize the change.
Parameters
[in]docThe document to set the snap settings for. The caller owns the pointed document.
[in]bcThe container with the snap settings for the document doc and/or snapmode. See description\dmodeling.h for more information on the container.
[in]snapmodeOptionally specify the snap mode to set the settings for instead of the global settings.
For example SNAPMODE_GUIDE. See description\dmodeling.h for snap mode IDs.

◆ IsQuantizeEnabled()

Bool IsQuantizeEnabled ( BaseDocument doc)

Checks if quantizing is enabled.

Parameters
[in]docThe document to check for. The caller owns the pointed document.
Returns
true if quantizing is enabled, otherwise false.

◆ QuantizeStep() [1/2]

Float QuantizeStep ( BaseDocument doc,
BaseDraw bd,
Int32  quantize_mode 
)

Gets the quantize step values from QUANTIZE_MOVE, QUANTIZE_SCALE etc.

Parameters
[in]docThe document to get the quantize step values. The caller owns the pointed document.
[in]bdThe view to retrieve the quantize values. Not relevant for other quantize modes (pass nullptr).
[in]quantize_modeThe mode to retrieve the values for, e.g. QUANTIZE_MOVE, QUANTIZE_ROTATE, QUANTIZE_SCALE or QUANTIZE_TEXTURE.
Returns
The real step value.

◆ QuantizeStep() [2/2]

void QuantizeStep ( BaseDocument doc,
BaseDraw bd,
Int32  quantize_mode,
Float  val 
)

Sets the quantize step values for QUANTIZE_MOVE, QUANTIZE_SCALE etc.

Parameters
[in]docThe document to set the quantize step values. The caller owns the pointed document.
[in]bdThe view to set the quantize step values. Not relevant for other quantize modes (pass nullptr).
[in]quantize_modeThe mode to set the values for, e.g. QUANTIZE_MOVE, QUANTIZE_ROTATE, QUANTIZE_SCALE or QUANTIZE_TEXTURE.
[in]valThe value to set the quantizing step size to.

◆ GetConstructionPlane()

Bool GetConstructionPlane ( BaseDraw bd,
Matrix mg,
Vector scale,
BaseObject **  op 
)

Retrieves the viewport workplane and orientation.

Parameters
[in]bdThe view to get the workplane's matrix from. The caller owns the pointed view.
[out]mgAssigned the correct workplane matrix. Pass nullptr to skip.
[out]scaleAssigned the correct workplane scale.Pass nullptr to skip.
[out]opAssigned the workplane object. Pass nullptr to skip.
Returns
true if successful, otherwise false.

◆ GetWorkplaneObject()

BaseObject* GetWorkplaneObject ( BaseDocument doc)

Retrieve the workplane object for the document doc.

Parameters
[in]docThe document to retrieve the workplane from. The caller owns the pointed document.
Returns
The workplane object. The document owns the pointed object.

◆ WorkplaneLock() [1/2]

Bool WorkplaneLock ( BaseDocument doc)

Checks the current workplane locked status for the document doc.

Parameters
[in]docThe document the workplane belongs to. The caller owns the pointed document.
Returns
true if the workplane is locked, otherwise false.

◆ WorkplaneLock() [2/2]

void WorkplaneLock ( BaseDraw bd,
Int32  locked 
)

Sets the current workplane locked status for the document doc.

Parameters
[in]bdThe view to lock the workplane. The caller owns the pointed view.
[in]lockedtrue to lock the workplane, otherwise false.

◆ GetWorkplaneMatrix()

Matrix GetWorkplaneMatrix ( BaseDocument doc,
BaseDraw bd 
)

Gets the current workplane matrix for the document doc and optionally view bd.

Parameters
[in]docThe document the workplane belongs to. The caller owns the pointed document.
[in]bdThe view to get the workplane's matrix from. If nullptr the locked matrix is returned independently from view. The caller owns the pointed view.
Returns
The workplane matrix.

◆ RegisterSnapPlugin()

Bool RegisterSnapPlugin ( Int32  id,
const maxon::String str,
const maxon::String help,
Int32  snapinfo,
SnapDataAllocator npalloc,
BaseBitmap icon,
SNAPPRIORITY  priority = SNAPPRIORITY::EDGE,
Int32  parent_mode = -1 
)

Registers a snap mode plugin with Cinema 4D.

Parameters
[in]idA unique plugin ID. Must be obtained from http://www.plugincafe.com
[in]strThe name of the plugin.
To affect the order that plugins are displayed in menus add "#$n" as a prefix to this name, where n is a number.
Lower numbers are displayed before higher numbers. If name is "--" it will show up as a menu separator.
[in]helpA small block of information that will appear in the interface to explain how the snap mode operates.
[in]snapinfoThe registration flags: PLUGINFLAG PLUGINFLAG_SNAP
[in]npallocThe SnapData allocator. Pass MySnapMode::Alloc.
[in]iconThe icon for the snap mode. The bitmap is copied.
The icon should be of size 32x32, but will be scaled if needed.
It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.
[in]priorityThe priority of the snap mode, a higher priority will take precedent over other snaps within the radius: SNAPPRIORITY
[in]parent_modeAn ID for a parent snap mode, this mode then inherits that modes enabled/disabled state.
Returns
true if the snap mode plugin was registered, otherwise false.

Variable Documentation

◆ MAXON_ENUM_LIST

struct SnapPoint MAXON_ENUM_LIST