Snapping

Detailed Description

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

• SnapData: Data class to develop snap mode plugins.
• SnapCore: The snap interface with utilities functions.

Data structures:

• SnapStruct
• SnapResult
• SnapPoint

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

AutoAlloc<DetectSnapping> snap;
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:

SnapResult res;
AutoAlloc<SnapCore> snap;
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 SnapData *	SnapDataAllocator()

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)
BaseObject *	GetWorkplaneObject (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()

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]	doc	The document to check. The caller owns the pointed document.
[in]	mode	Optionally 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]	state	The state to set: true to enable, false to disable.
[in]	doc	The document to set the snap mode state for. The caller owns the pointed document.
[in]	mode	Optionally 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]	doc	The document related snap settings to get. The caller owns the pointed document.
[in]	snapmode	Optionally 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]	doc	The document to set the snap settings for. The caller owns the pointed document.
[in]	bc	The container with the snap settings for the document doc and/or snapmode. See description\dmodeling.h for more information on the container.
[in]	snapmode	Optionally 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]

doc

The 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]	doc	The document to get the quantize step values. The caller owns the pointed document.
[in]	bd	The view to retrieve the quantize values. Not relevant for other quantize modes (pass nullptr).
[in]	quantize_mode	The 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]	doc	The document to set the quantize step values. The caller owns the pointed document.
[in]	bd	The view to set the quantize step values. Not relevant for other quantize modes (pass nullptr).
[in]	quantize_mode	The mode to set the values for, e.g. QUANTIZE_MOVE, QUANTIZE_ROTATE, QUANTIZE_SCALE or QUANTIZE_TEXTURE.
[in]	val	The 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]	bd	The view to get the workplane's matrix from. The caller owns the pointed view.
[out]	mg	Assigned the correct workplane matrix. Pass nullptr to skip.
[out]	scale	Assigned the correct workplane scale.Pass nullptr to skip.
[out]	op	Assigned 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]

doc

The 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]

doc

The 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]	bd	The view to lock the workplane. The caller owns the pointed view.
[in]	locked	true 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]	doc	The document the workplane belongs to. The caller owns the pointed document.
[in]	bd	The 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]	id	A unique plugin ID. Must be obtained from http://www.plugincafe.com
[in]	str	The 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]	help	A small block of information that will appear in the interface to explain how the snap mode operates.
[in]	snapinfo	The registration flags: PLUGINFLAG PLUGINFLAG_SNAP
[in]	npalloc	The SnapData allocator. Pass MySnapMode::Alloc.
[in]	icon	The 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]	priority	The priority of the snap mode, a higher priority will take precedent over other snaps within the radius: SNAPPRIORITY
[in]	parent_mode	An 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