SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUSnapRef Struct Reference

References a snap. More...

`#include <SketchUpAPI/model/snap.h>`

Inherits SUDrawingElementRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUSnapToEntity (SUSnapRef snap)
| Converts from an SUSnapRef to an SUEntityRef. This is essentially an upcast operation. More...
SUSnapRef | SUSnapFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUSnapRef. This is essentially a downcast operation so the given entity must be convertible to an SUSnapRef. More...
SUDrawingElementRef | SUSnapToDrawingElement (SUSnapRef snap)
| Converts from an SUSnapRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUSnapRef | SUSnapFromDrawingElement (SUDrawingElementRef drawing_elem)
| Converts from an SUDrawingElementRef to an SUSnapRef. This is essentially a downcast operation so the given element must be convertible to an SUSnapRef. More...
enum SUResult | SUSnapCreate (SUSnapRef *snap, const struct SUPoint3D position, const struct SUVector3D *direction, const struct SUVector3D *up)
| Creates a snap at the given position and orientation. More...
enum SUResult | SUSnapRelease (SUSnapRef *snap)
| Releases a snap object and its associated resources. More...
enum SUResult | SUSnapGetPosition (SUSnapRef snap, struct SUPoint3D *position)
| Retrieves the position of a snap. More...
enum SUResult | SUSnapGetDirection (SUSnapRef snap, struct SUVector3D *direction)
| Retrieves the orientation of a snap. More...
enum SUResult | SUSnapGetUp (SUSnapRef snap, struct SUVector3D *up)
| Retrieves the up vector of a snap. More...
enum SUResult | SUSnapSet (SUSnapRef snap, const struct SUPoint3D position, const struct SUVector3D *direction, const struct SUVector3D *up)
| Sets the position, direction and up vector of the snap. More...
Related Functions inherited from SUDrawingElementRef
SUEntityRef | SUDrawingElementToEntity (SUDrawingElementRef elem)
| Converts from an SUDrawingElementRef to an SUEntityRef. This is essentially an upcast operation. More...
SUDrawingElementRef | SUDrawingElementFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUDrawingElementRef. This is essentially a downcast operation so the given entity must be convertible to a drawing element. More...
enum SURefType | SUDrawingElementGetType (SUDrawingElementRef elem)
| Returns the concrete type of the given drawing element. More...
enum SUResult | SUDrawingElementGetBoundingBox (SUDrawingElementRef elem, struct SUBoundingBox3D *bbox)
| Retrieves the bounding box of a drawing element. More...
enum SUResult | SUDrawingElementGetMaterial (SUDrawingElementRef elem, SUMaterialRef *material)
| Retrieves the material object of a drawing element. More...
enum SUResult | SUDrawingElementSetMaterial (SUDrawingElementRef elem, SUMaterialRef material)
| Sets the material of a drawing element. More...
enum SUResult | SUDrawingElementGetLayer (SUDrawingElementRef elem, SULayerRef *layer)
| Retrieves the layer object associated with a drawing element. More...
enum SUResult | SUDrawingElementSetLayer (SUDrawingElementRef elem, SULayerRef layer)
| Sets the layer object to be associated with a drawing element. More...
enum SUResult | SUDrawingElementSetHidden (SUDrawingElementRef elem, bool hide_flag)
| Sets the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementGetHidden (SUDrawingElementRef elem, bool *hide_flag)
| Retrieves the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementSetCastsShadows (SUDrawingElementRef elem, bool casts_shadows_flag)
| Sets the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetCastsShadows (SUDrawingElementRef elem, bool *casts_shadows_flag)
| Retrieves the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementSetReceivesShadows (SUDrawingElementRef elem, bool receives_shadows_flag)
| Sets the receives shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetReceivesShadows (SUDrawingElementRef elem, bool *receives_shadows_flag)
| Retrieves the receives shadows flag of a drawing element. More...
Related Functions inherited from SUEntityRef
enum SURefType | SUEntityGetType (SUEntityRef entity)
| Returns the concrete type of the given entity. More...
enum SUResult | SUEntityGetID (SUEntityRef entity, int32_t *entity_id)
| Retrieves the id of the entity. More...
enum SUResult | SUEntityGetPersistentID (SUEntityRef entity, int64_t *entity_pid)
| Retrieves the persistent id of the entity. More...
enum SUResult | SUEntityGetNumAttributeDictionaries (SUEntityRef entity, size_t *count)
| Retrieves the number of attribute dictionaries of an entity. More...
enum SUResult | SUEntityGetAttributeDictionaries (SUEntityRef entity, size_t len, SUAttributeDictionaryRef dictionaries[], size_t *count)
| Retrieves the attribute dictionaries of an entity. More...
enum SUResult | SUEntityAddAttributeDictionary (SUEntityRef entity, SUAttributeDictionaryRef dictionary)
| Adds the attribute dictionary to an entity. The given dictionary object must not belong to another entity. In other words, each dictionary should be added to one entity only. More...
enum SUResult | SUEntityGetAttributeDictionary (SUEntityRef entity, const char *name, SUAttributeDictionaryRef *dictionary)
| Retrieves the attribute dictionary of an entity that has the given name. More...
enum SUResult | SUEntityGetModel (SUEntityRef entity, SUModelRef *model)
| Retrieves the model object associated with the entity. More...
enum SUResult | SUEntityGetParentEntities (SUEntityRef entity, SUEntitiesRef *entities)
| Retrieves the entities object which contains the entity. More...

## Detailed Description

References a snap.

Since
  SketchUp 2025.0, API 13.0

A Snap is a custom grip used by SketchUp's Move tool. Snaps can be added at strategic places such as connectors to help assembling objects.

SUSnapGetDirection() is the direction a snap is "pointing". This can be thought of as the normal direction of the snap. It can also be thought of as the direction you move an object when plugging it into another object, e.g. inserting a power coord.

SUSnapGetUp() controls the rotation around the Snap's axis.

When two objects are snapped together, the Snaps have opposite SUSnapGetDirection() vectors but matching SUSnapGetUp() vectors.

## Friends And Related Function Documentation

enum SUResult SUSnapCreate | ( | SUSnapRef * | snap,
|  | const struct SUPoint3D | position,
|  | const struct SUVector3D * | direction,
|  | const struct SUVector3D * | up
| ) |  |
| related

Creates a snap at the given position and orientation.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [out] | snap | The snap object created.
  [in] | position | The position of the snap.
  [in] | direction | The orientation of the snap. Pass `NULL` to use the default orientation.
  [in] | up | The up vector controls the rotation around the `orientation` of the snap. Pass `NULL` to use the default up vector.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_ARGUMENT if `direction` an `up` are parallel.
  - SU_ERROR_NULL_POINTER_OUTPUT if `snap` is `NULL`
  - SU_ERROR_OVERWRITE_VALID if `snap` already refers to a valid object

SUSnapRef SUSnapFromDrawingElement | ( | SUDrawingElementRef | drawing_elem | ) |
| related

Converts from an SUDrawingElementRef to an SUSnapRef. This is essentially a downcast operation so the given element must be convertible to an SUSnapRef.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | drawing_elem | The given element reference.

Returns
  - The converted SUSnapRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

SUSnapRef SUSnapFromEntity | ( | SUEntityRef | entity | ) |
| related

Converts from an SUEntityRef to an SUSnapRef. This is essentially a downcast operation so the given entity must be convertible to an SUSnapRef.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | entity | The given entity reference.

Returns
  - The converted SUSnapRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

enum SUResult SUSnapGetDirection | ( | SUSnapRef | snap,
|  | struct SUVector3D * | direction
| ) |  |
| related

Retrieves the orientation of a snap.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The snap object.
  [out] | direction | The direction of the snap.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `snap` point is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if direction is `NULL`

enum SUResult SUSnapGetPosition | ( | SUSnapRef | snap,
|  | struct SUPoint3D * | position
| ) |  |
| related

Retrieves the position of a snap.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The snap object.
  [out] | position | The position retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `snap` point is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if position is `NULL`

enum SUResult SUSnapGetUp | ( | SUSnapRef | snap,
|  | struct SUVector3D * | up
| ) |  |
| related

Retrieves the up vector of a snap.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The snap object.
  [out] | up | The up vector of the snap.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `snap` point is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if up is `NULL`

enum SUResult SUSnapRelease | ( | SUSnapRef * | snap | ) |
| related

Releases a snap object and its associated resources.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The snap object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if `snap` points to an `NULL`
  - SU_ERROR_INVALID_INPUT if the `snap` object is not a valid object.

enum SUResult SUSnapSet | ( | SUSnapRef | snap,
|  | const struct SUPoint3D | position,
|  | const struct SUVector3D * | direction,
|  | const struct SUVector3D * | up
| ) |  |
| related

Sets the position, direction and up vector of the snap.

If only `position` is provided then `direction` and `up` remains unchanged.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The snap object.
  [in] | position | The position of the snap.
  [in] | direction | The orientation of the snap. Pass `NULL` to use the default orientation.
  [in] | up | The up vector of the snap. Pass `NULL` to use the default up vector.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_ARGUMENT if `direction` an `up` are parallel.
  - SU_ERROR_NULL_POINTER_INPUT if `snap` is `NULL`

SUDrawingElementRef SUSnapToDrawingElement | ( | SUSnapRef | snap | ) |
| related

Converts from an SUSnapRef to an SUDrawingElementRef. This is essentially an upcast operation.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The given snap reference.

Returns
  - The converted SUEntityRef if `snap` is a valid snap.
  - If not, the returned reference will be invalid.

SUEntityRef SUSnapToEntity | ( | SUSnapRef | snap | ) |
| related

Converts from an SUSnapRef to an SUEntityRef. This is essentially an upcast operation.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | snap | The given snap reference.

Returns
  - The converted SUEntityRef if `snap` is a valid snap.
  - If not, the returned reference will be invalid.

The documentation for this struct was generated from the following files:

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/snap.h