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

#include <SketchUpAPI/model/component_instance.h>

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
	)

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
	)

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
	)

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 )

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 )

Parameters

[in] 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
	)

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

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

Since: SketchUp 2015, API 3.0

Parameters

[in]	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
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	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
	)

Parameters

[in]	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
	)

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]	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
SU_ERROR_NULL_POINTER_INPUT if transform is NULL

SUDrawingElementRef SUComponentInstanceToDrawingElement ( SUComponentInstanceRef instance )

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 )

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

Related Functions

Detailed Description

Friends And Related Function Documentation