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
SUComponentInstanceRef Struct Reference

References a component instance, i.e. an instance of a component definition. More...

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

Inherits SUDrawingElementRef.

Inherited by SUGroupRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUComponentInstanceToEntity (SUComponentInstanceRef instance)
| Converts from an SUComponentInstanceRef to an SUEntityRef. This is essentially an upcast operation. More...
SUComponentInstanceRef | SUComponentInstanceFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given entity must be convertible to a component instance. More...
SUDrawingElementRef | SUComponentInstanceToDrawingElement (SUComponentInstanceRef instance)
| Converts from an SUComponentInstanceRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUComponentInstanceRef | SUComponentInstanceFromDrawingElement (SUDrawingElementRef drawing_elem)
| Converts from an SUDrawingElementRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given element must be convertible to a component instance. More...
enum SUResult | SUComponentInstanceSetName (SUComponentInstanceRef instance, const char *name)
| Sets the name of a component instance object. More...
enum SUResult | SUComponentInstanceRelease (SUComponentInstanceRef *instance)
| Deallocates a component instance object created with SUComponentDefinitionCreateInstance(). More...
enum SUResult | SUComponentInstanceGetName (SUComponentInstanceRef instance, SUStringRef *name)
| Retrieves the name of a component instance object. More...
enum SUResult | SUComponentInstanceSetGuid (SUComponentInstanceRef instance, const char *guid)
| Sets the globally unique identifier (guid) string of a instance object. More...
enum SUResult | SUComponentInstanceGetGuid (SUComponentInstanceRef instance, SUStringRef *guid)
| Retrieves the globally unique identifier (guid) string of a instance object. More...
enum SUResult | SUComponentInstanceSetTransform (SUComponentInstanceRef instance, const struct SUTransformation *transform)
| Sets the transform of a component instance object. More...
enum SUResult | SUComponentInstanceGetTransform (SUComponentInstanceRef instance, struct SUTransformation *transform)
| Retrieves the transform of a component instance object. More...
enum SUResult | SUComponentInstanceGetDefinition (SUComponentInstanceRef instance, SUComponentDefinitionRef *component)
| Retrieves the component definition of a component instance object. More...
enum SUResult | SUComponentInstanceSetLocked (SUComponentInstanceRef instance, bool lock)
| Locks the instance if is_locked is true, otherwise unlocks the instance. More...
enum SUResult | SUComponentInstanceIsLocked (SUComponentInstanceRef instance, bool *is_locked)
| Retrieves a boolean indicating whether tne instance is locked. More...
enum SUResult | SUComponentInstanceSaveAs (SUComponentInstanceRef instance, const char *file_path)
| Saves the component instance data to a file. More...
enum SUResult | SUComponentInstanceComputeVolume (SUComponentInstanceRef instance, const struct SUTransformation *transform, double *volume)
| Computes the volume of the component instance. More...
enum SUResult | SUComponentInstanceCreateDCInfo (SUComponentInstanceRef instance, SUDynamicComponentInfoRef *dc_info)
| Creates a SUDynamicComponentInfoRef object. More...
enum SUResult | SUComponentInstanceCreateClassificationInfo (SUComponentInstanceRef instance, SUClassificationInfoRef *classification_info)
| Creates a SUClassificationInfoRef object. More...
enum SUResult | SUComponentInstanceGetNumAttachedInstances (SUComponentInstanceRef instance, size_t *count)
| Retrieves the number of attached component instances. More...
enum SUResult | SUComponentInstanceGetAttachedInstances (SUComponentInstanceRef instance, size_t len, SUComponentInstanceRef instances[], size_t *count)
| Retrieves the attached component instances. More...
enum SUResult | SUComponentInstanceGetNumAttachedToDrawingElements (SUComponentInstanceRef instance, size_t *count)
| Retrieves the number of drawing element this instance is attached to. More...
enum SUResult | SUComponentInstanceGetAttachedToDrawingElements (SUComponentInstanceRef instance, size_t len, SUDrawingElementRef elements[], size_t *count)
| Retrieves the drawing elements this instance is attached to. 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 component instance, i.e. an instance of a component definition.

## Friends And Related Function Documentation

enum SUResult SUComponentInstanceComputeVolume | ( | SUComponentInstanceRef | instance,
|  | const struct SUTransformation * | transform,
|  | double * | volume
| ) |  |
| related

Computes the volume of the component instance.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | instance | The component instance object.
  [in] | transform | A transformation to be applied to the component instance. If set to NULL, the volume will be computed based on the instance's transformation. Note that in this case if the instance is contained within another instance or group, the parent transformation is not factored in.
  [out] | volume | The volume of the component instance in cubic inches.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if component instance is not a valid object
  - SU_ERROR_NO_DATA if component instance is not manifold.
  - SU_ERROR_NULL_POINTER_OUTPUT if volume is NULL

enum SUResult SUComponentInstanceCreateClassificationInfo | ( | SUComponentInstanceRef | instance,
|  | SUClassificationInfoRef * | classification_info
| ) |  |
| related

Creates a SUClassificationInfoRef object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | instance | The component instance object.
  [out] | classification_info | The classification info object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NO_DATA if instance is not a classified object
  - SU_ERROR_NULL_POINTER_OUTPUT if classification_info is NULL

enum SUResult SUComponentInstanceCreateDCInfo | ( | SUComponentInstanceRef | instance,
|  | SUDynamicComponentInfoRef * | dc_info
| ) |  |
| related

Creates a SUDynamicComponentInfoRef object.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | instance | The component instance object.
  [out] | dc_info | The dynamic component info object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NO_DATA if instance is not a dynamic component
  - SU_ERROR_NULL_POINTER_OUTPUT if dc_info is NULL
  - SU_ERROR_OVERWRITE_VALID if dc_info is a valid object

SUComponentInstanceRef SUComponentInstanceFromDrawingElement | ( | SUDrawingElementRef | drawing_elem | ) |
| related

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

Parameters

  [in] | drawing_elem | The given drawing element reference.

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

SUComponentInstanceRef SUComponentInstanceFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Parameters

  [in] | entity | The given entity reference.

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

enum SUResult SUComponentInstanceGetAttachedInstances | ( | SUComponentInstanceRef | instance,
|  | size_t | len,
|  | SUComponentInstanceRef | instances[],
|  | size_t * | count
| ) |  |
| related

Retrieves the attached component instances.

Parameters

  [in] | instance | The component instance object.
  [in] | len | The number of instances to retrieve.
  [out] | instances | The attached instances retrieved. These may be instances or groups.
  [out] | count | The number of instances retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if instances or count is NULL

enum SUResult SUComponentInstanceGetAttachedToDrawingElements | ( | SUComponentInstanceRef | instance,
|  | size_t | len,
|  | SUDrawingElementRef | elements[],
|  | size_t * | count
| ) |  |
| related

Retrieves the drawing elements this instance is attached to.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | instance | The component instance object.
  [in] | len | The number of instances to retrieve.
  [out] | elements | The drawing elements retrieved. These may be instances, groups or faces.
  [out] | count | The number of drawing elements retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if instances or count is NULL

enum SUResult SUComponentInstanceGetDefinition | ( | SUComponentInstanceRef | instance,
|  | SUComponentDefinitionRef * | component
| ) |  |
| related

Retrieves the component definition of a component instance object.

Parameters

  [in] | instance | The component instance object.
  [out] | component | The component definition retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `instance` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `component` is NULL

enum SUResult SUComponentInstanceGetGuid | ( | SUComponentInstanceRef | instance,
|  | SUStringRef * | guid
| ) |  |
| related

Retrieves the globally unique identifier (guid) string of a instance object.

Parameters

  [in] | instance | The component instance object.
  [out] | guid | The guid retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if guid is NULL
  - SU_ERROR_INVALID_OUTPUT if guid does not point to a valid SUStringRef object

enum SUResult SUComponentInstanceGetName | ( | SUComponentInstanceRef | instance,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the name of a component instance object.

Parameters

  [in] | instance | The component instance object.
  [out] | name | The name retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
  - SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

enum SUResult SUComponentInstanceGetNumAttachedInstances | ( | SUComponentInstanceRef | instance,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of attached component instances.

Parameters

  [in] | instance | The component instance object.
  [out] | count | The number of attached instances.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUComponentInstanceGetNumAttachedToDrawingElements | ( | SUComponentInstanceRef | instance,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of drawing element this instance is attached to.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | instance | The component instance object.
  [out] | count | The number of drawing elements this component instance is attached to.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is an invalid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUComponentInstanceGetTransform | ( | SUComponentInstanceRef | instance,
|  | struct SUTransformation * | transform
| ) |  |
| related

Retrieves the transform of a component instance object.

See description of SUComponentInstanceSetTransform() for a discussion of component instance transforms.

Parameters

  [in] | instance | The component instance object.
  [out] | transform | The transform retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

enum SUResult SUComponentInstanceIsLocked | ( | SUComponentInstanceRef | instance,
|  | bool * | is_locked
| ) |  |
| related

Retrieves a boolean indicating whether tne instance is locked.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | instance | The instance object.
  [out] | is_locked | returns true if the instance is locked

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is invalid
  - SU_ERROR_NULL_POINTER_OUTPUT if is_locked is NULL

enum SUResult SUComponentInstanceRelease | ( | SUComponentInstanceRef * | instance | ) |
| related

Deallocates a component instance object created with SUComponentDefinitionCreateInstance().

Parameters

  [in,out] | instance | The component instance object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if instance is NULL

enum SUResult SUComponentInstanceSaveAs | ( | SUComponentInstanceRef | instance,
|  | const char * | file_path
| ) |  |
| related

Saves the component instance data to a file.

Parameters

  [in] | instance | The component instance object.
  [in] | file_path | The file path destination of the serialization operation. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
  - SU_ERROR_SERIALIZATION if the serialization operation itself fails

Deprecated:
  Superseded by SUComponentDefinitionSaveToFile(). This function had the side effects of making the instance unique and changing its transformation. An SKP file also conceptually maps better to a component definition than a component instance.

enum SUResult SUComponentInstanceSetGuid | ( | SUComponentInstanceRef | instance,
|  | const char * | guid
| ) |  |
| related

Sets the globally unique identifier (guid) string of a instance object.

Since
  SketchUp 2015, API 3.0

Parameters

  [in,out] | instance | The component instance object.
  [in] | guid | The utf-8 formatted guid string.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_INVALID_INPUT if guid is NULL or invalid

enum SUResult SUComponentInstanceSetLocked | ( | SUComponentInstanceRef | instance,
|  | bool | lock
| ) |  |
| related

Locks the instance if is_locked is true, otherwise unlocks the instance.

Since
  SketchUp 2016, API 4.0

Parameters

  [in,out] | instance | The instance object.
  [in] | lock | if true lock the instance, otherwise unlock it.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is invalid
  - SU_ERROR_NULL_POINTER_OUTPUT if is_locked is NULL

enum SUResult SUComponentInstanceSetName | ( | SUComponentInstanceRef | instance,
|  | const char * | name
| ) |  |
| related

Sets the name of a component instance object.

Parameters

  [in,out] | instance | The component instance object.
  [in] | name | The name string to set the component instance object. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL

enum SUResult SUComponentInstanceSetTransform | ( | SUComponentInstanceRef | instance,
|  | const struct SUTransformation * | transform
| ) |  |
| related

Sets the transform of a component instance object.

The transform is relative to the parent component. If the parent component is the root component of a model, then the transform is relative to absolute coordinates.

Parameters

  [in,out] | instance | The component instance object.
  [in] | transform | The affine transform to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if instance is not a valid object or transform is non invertible
  - SU_ERROR_NULL_POINTER_INPUT if transform is NULL

SUDrawingElementRef SUComponentInstanceToDrawingElement | ( | SUComponentInstanceRef | instance | ) |
| related

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

Parameters

  [in] | instance | The given component instance reference.

Returns
  - The converted SUEntityRef if instance is a valid component instance
  - If not, the returned reference will be invalid

SUEntityRef SUComponentInstanceToEntity | ( | SUComponentInstanceRef | instance | ) |
| related

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

Parameters

  [in] | instance | The given component instance reference.

Returns
  - The converted SUEntityRef if instance is a valid component instance
  - 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/component_instance.h