SUEntitiesRef Struct Reference

References a container object for all entities in a model, component definition or a group. More...

#include <SketchUpAPI/model/entities.h>

Related Functions
(Note that these are not member functions.)
enum SUResult	SUEntitiesClear (SUEntitiesRef entities)
	Removes all entities in the container. More...
enum SUResult	SUEntitiesFill (SUEntitiesRef entities, SUGeometryInputRef geom_input, bool weld_vertices)
	SUEntitiesFill is the fastest way to populate an entities object. The important precondition is that no duplicate data should be given. More...
enum SUResult	SUEntitiesGetBoundingBox (SUEntitiesRef entities, struct SUBoundingBox3D *bbox)
	Retrieves the bounding box of the entities. More...
enum SUResult	SUEntitiesGetBoundingBoxLLA (SUEntitiesRef entities, struct SUBoundingBox3D *bbox)
	Retrieves the LLA coordinates (Latidue, Longitude and Altitude) bounding box of the given entities object. More...
enum SUResult	SUEntitiesGetNumFaces (SUEntitiesRef entities, size_t *count)
	Retrieves the number of faces in the entities object. More...
enum SUResult	SUEntitiesGetFaces (SUEntitiesRef entities, size_t len, SUFaceRef faces[], size_t *count)
	Retrieves the faces in the entities object. More...
enum SUResult	SUEntitiesGetNumCurves (SUEntitiesRef entities, size_t *count)
	Retrieves the number of curves in the entities object that are not associated with a face. More...
enum SUResult	SUEntitiesGetCurves (SUEntitiesRef entities, size_t len, SUCurveRef curves[], size_t *count)
	Retrieves the curves in the entities object that are not associated with a face. More...
enum SUResult	SUEntitiesGetNumArcCurves (SUEntitiesRef entities, size_t *count)
	Retrieves the number of arccurves in the entities object that are not associated with a face. More...
enum SUResult	SUEntitiesGetArcCurves (SUEntitiesRef entities, size_t len, SUArcCurveRef arccurves[], size_t *count)
	Retrieves the arccurves in the entities object that are not associated with a face. More...
enum SUResult	SUEntitiesGetNumGuidePoints (SUEntitiesRef entities, size_t *count)
	Retrieves the number of guide points in the entities object. More...
enum SUResult	SUEntitiesGetGuidePoints (SUEntitiesRef entities, size_t len, SUGuidePointRef guide_points[], size_t *count)
	Retrieves the guide points in the entities object. More...
enum SUResult	SUEntitiesGetNumGuideLines (SUEntitiesRef entities, size_t *count)
	Retrieves the number of guide lines in the entities object. More...
enum SUResult	SUEntitiesGetGuideLines (SUEntitiesRef entities, size_t len, SUGuideLineRef guide_lines[], size_t *count)
	Retrieves the guide lines in the entities object. More...
enum SUResult	SUEntitiesGetNumEdges (SUEntitiesRef entities, bool standalone_only, size_t *count)
	Retrieves the number of edges in the entities object. More...
enum SUResult	SUEntitiesGetEdges (SUEntitiesRef entities, bool standalone_only, size_t len, SUEdgeRef edges[], size_t *count)
	Retrieves the edges in the entities object. More...
enum SUResult	SUEntitiesGetNumPolyline3ds (SUEntitiesRef entities, size_t *count)
	Retrieves the number of polyline3d's in the entities object. More...
enum SUResult	SUEntitiesGetPolyline3ds (SUEntitiesRef entities, size_t len, SUPolyline3dRef lines[], size_t *count)
	Retrieves the polyline3d's in the entities object. More...
enum SUResult	SUEntitiesAddFaces (SUEntitiesRef entities, size_t len, const SUFaceRef faces[])
	Adds face objects to a entities object. More...
enum SUResult	SUEntitiesAddEdges (SUEntitiesRef entities, size_t len, const SUEdgeRef edges[])
	Adds edge objects to an entities object. More...
enum SUResult	SUEntitiesAddCurves (SUEntitiesRef entities, size_t len, const SUCurveRef curves[])
	Adds curve objects to an entities object. More...
enum SUResult	SUEntitiesAddArcCurves (SUEntitiesRef entities, size_t len, const SUArcCurveRef curves[])
	Adds arccurve objects to an entities object. More...
enum SUResult	SUEntitiesAddGuidePoints (SUEntitiesRef entities, size_t len, const SUGuidePointRef guide_points[])
	Adds guide point objects to an entities object. More...
enum SUResult	SUEntitiesAddGuideLines (SUEntitiesRef entities, size_t len, const SUGuideLineRef guide_lines[])
	Adds guide line objects to an entities object. More...
enum SUResult	SUEntitiesAddGroup (SUEntitiesRef entities, SUGroupRef group)
	Adds a group object to an entities object. More...
enum SUResult	SUEntitiesAddImage (SUEntitiesRef entities, SUImageRef image)
	Adds an image object to an entities object. More...
enum SUResult	SUEntitiesAddInstance (SUEntitiesRef entities, SUComponentInstanceRef instance, SUStringRef *name)
	Adds a component instance object to the entities. More...
enum SUResult	SUEntitiesAddSectionPlanes (SUEntitiesRef entities, size_t len, const SUSectionPlaneRef section_planes[])
	Adds section plane objects to an entities object. More...
enum SUResult	SUEntitiesAddTexts (SUEntitiesRef entities, size_t len, const SUTextRef texts[])
	Adds text objects to an entities object. More...
enum SUResult	SUEntitiesGetNumGroups (SUEntitiesRef entities, size_t *count)
	Retrieves the number of groups in the entities. More...
enum SUResult	SUEntitiesGetGroups (SUEntitiesRef entities, size_t len, SUGroupRef groups[], size_t *count)
	Retrieves the groups in the entities. More...
enum SUResult	SUEntitiesGetNumImages (SUEntitiesRef entities, size_t *count)
	Retrieves the number of images in the entities. More...
enum SUResult	SUEntitiesGetImages (SUEntitiesRef entities, size_t len, SUImageRef images[], size_t *count)
	Retrieves the array of image objects of a entities object. More...
enum SUResult	SUEntitiesGetNumInstances (SUEntitiesRef entities, size_t *count)
	Retrieves the number of component instances in the entities. More...
enum SUResult	SUEntitiesGetInstances (SUEntitiesRef entities, size_t len, SUComponentInstanceRef instances[], size_t *count)
	Retrieves the component instances in the entities. More...
enum SUResult	SUEntitiesGetNumSectionPlanes (SUEntitiesRef entities, size_t *count)
	Retrieves the number of section planes in the entities object. More...
enum SUResult	SUEntitiesGetNumTexts (SUEntitiesRef entities, size_t *count)
	Retrieves the number of texts in the entities object. More...
enum SUResult	SUEntitiesGetSectionPlanes (SUEntitiesRef entities, size_t len, SUSectionPlaneRef section_planes[], size_t *count)
	Retrieves the section planes in the entities. More...
enum SUResult	SUEntitiesGetNumDimensions (SUEntitiesRef entities, size_t *count)
	Retrieves the number of dimensions in the entities object. More...
enum SUResult	SUEntitiesGetDimensions (SUEntitiesRef entities, size_t len, SUDimensionRef dimensions[], size_t *count)
	Retrieves the dimensions in the entities object. More...
enum SUResult	SUEntitiesGetTexts (SUEntitiesRef entities, size_t len, SUTextRef texts[], size_t *count)
	Retrieves the texts in the entities. More...
enum SUResult	SUEntitiesTransform (SUEntitiesRef entities, size_t len, SUEntityRef elements[], const struct SUTransformation *trans)
	Applies a 3D transformation to the elements of the provided entity array. More...
enum SUResult	SUEntitiesTransformMultiple (SUEntitiesRef entities, size_t len, SUEntityRef elements[], const struct SUTransformation tranforms[])
	Applies a 3D transformations to the elements of the provided entity array. The arrays of elements and transformations must be the same length. More...
enum SUResult	SUEntitiesErase (SUEntitiesRef entities, size_t len, SUEntityRef elements[])
	Erases elements from an entities object. The input elements are destroyed, so the array elements are invalidated to prevent user from attempting to use destroyed entities. More...
enum SUResult	SUEntitiesIsRecursivelyEmpty (SUEntitiesRef entities, bool *is_empty)
	Retrieves a boolean indicating whether the entities object is recursively empty. A recursively empty entities object is defined as one that either has zero entities or contains only instances of definitions with recursively empty entities objects. More...
enum SUResult	SUEntitiesHasSectionCuts (SUEntitiesRef entities, bool *has_section_cuts)
	Retrieves a boolean by recursively searching through the entities determining whether the entities has an active section plane or any of its nested components have an active section plane. More...
enum SUResult	SUEntitiesEntityListFill (SUEntitiesRef entities, enum SURefType type, SUEntityListRef list)
	Fills the list with all entities of the specified type in the instance. The list is not in any specific order. More...
enum SUResult	SUEntitiesWeld (SUEntitiesRef entities, size_t num_edges, SUEdgeRef edges[], SUEntityListRef list)
	Takes a set of edges and find all possible chains of edges and connect them with a SUCurveRef. More...
enum SUResult	SUEntitiesGetParent (SUEntitiesRef entities, struct SUEntitiesParent *parent)
	Get the parent component definition or model that owns this entities object. More...
enum SUResult	SUEntitiesGetActiveSectionPlane (SUEntitiesRef entities, SUSectionPlaneRef *section_plane)
	Get the active section plane for this entities object. More...
enum SUResult	SUEntitiesSetActiveSectionPlane (SUEntitiesRef entities, SUSectionPlaneRef section_plane)
	Set the active section plane for this entities object. More...

Detailed Description

References a container object for all entities in a model, component definition or a group.

Friends And Related Function Documentation

enum SUResult SUEntitiesAddArcCurves ( SUEntitiesRef  entities, size_t  len, const SUArcCurveRef  curves[]  )

related

Adds arccurve objects to an entities object.

Since

SketchUp 2016, API 4.0

NOTE: This function does not merge geometry, which will likely create an invalid SketchUp model. It is recommended to use SUGeometryInput instead which does correctly merge geometry.

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of curve objects.
[in]	curves	The array of arccurve objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if curves is NULL

enum SUResult SUEntitiesAddCurves ( SUEntitiesRef  entities, size_t  len, const SUCurveRef  curves[]  )

related

Adds curve objects to an entities object.

NOTE: This function does not merge geometry, which will likely create an invalid SketchUp model. It is recommended to use SUGeometryInput instead which does correctly merge geometry.

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of curve objects.
[in]	curves	The array of curve objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if curves is NULL

enum SUResult SUEntitiesAddEdges ( SUEntitiesRef  entities, size_t  len, const SUEdgeRef  edges[]  )

related

Adds edge objects to an entities object.

NOTE: This function does not merge geometry, which will likely create an invalid SketchUp model. It is recommended to use SUGeometryInput instead which does correctly merge geometry.

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of edge objects.
[in]	edges	The array of edge objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if edges is NULL

enum SUResult SUEntitiesAddFaces ( SUEntitiesRef  entities, size_t  len, const SUFaceRef  faces[]  )

related

Adds face objects to a entities object.

Bug:

SUEntitiesAddFaces() will not merge overlapping vertices and edges, which produces SketchUp models with unexpected state. Avoid using these functions and instead use SUGeometryInputRef along with SUEntitiesFill().

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of face objects.
[in]	faces	The array of face objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if faces is NULL

enum SUResult SUEntitiesAddGroup ( SUEntitiesRef  entities, SUGroupRef  group  )

related

Adds a group object to an entities object.

Parameters

[in,out]	entities	The entities object.
[in]	group	The group object to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities or group is not a valid object

enum SUResult SUEntitiesAddGuideLines ( SUEntitiesRef  entities, size_t  len, const SUGuideLineRef  guide_lines[]  )

related

Adds guide line objects to an entities object.

Since

SketchUp 2016, API 4.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of guide line objects.
[in]	guide_lines	The array of guide line objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if guide_lines is NULL

enum SUResult SUEntitiesAddGuidePoints ( SUEntitiesRef  entities, size_t  len, const SUGuidePointRef  guide_points[]  )

related

Adds guide point objects to an entities object.

Since

SketchUp 2014 M1, API 2.1

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of guide point objects.
[in]	guide_points	The array of guide point objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if guide_points is NULL

enum SUResult SUEntitiesAddImage ( SUEntitiesRef  entities, SUImageRef  image  )

related

Adds an image object to an entities object.

Parameters

[in,out]	entities	The entities object.
[in]	image	The image object to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities or image is not a valid object

enum SUResult SUEntitiesAddInstance ( SUEntitiesRef  entities, SUComponentInstanceRef  instance, SUStringRef *  name  )

related

Adds a component instance object to the entities.

Parameters

[in,out]	entities	The entities object.
[in]	instance	The component instance object to add.
[out]	name	The unique name that is assigned to definition of the component instance. This can be NULL in which case the caller does not need to retrieve the assigned name.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities or instance is not a valid object
• SU_ERROR_INVALID_OUTPUT if name (when not NULL) does not refer to a valid SUStringRef object

enum SUResult SUEntitiesAddSectionPlanes ( SUEntitiesRef  entities, size_t  len, const SUSectionPlaneRef  section_planes[]  )

related

Adds section plane objects to an entities object.

Since

SketchUp 2016, API 4.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of section planes objects.
[in]	section_planes	The array of section planes objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if section_planes is NULL

enum SUResult SUEntitiesAddTexts ( SUEntitiesRef  entities, size_t  len, const SUTextRef  texts[]  )

related

Adds text objects to an entities object.

Since

SketchUp 2018, API 6.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The length of the array of text objects.
[in]	texts	The array of text objects to add.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if texts is NULL

enum SUResult SUEntitiesClear ( SUEntitiesRef  entities )

related

Removes all entities in the container.

Since

SketchUp 2019, API 7.0

Parameters

[in,out]

entities

The entities to clear.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object

enum SUResult SUEntitiesEntityListFill ( SUEntitiesRef  entities, enum SURefType  type, SUEntityListRef  list  )

related

Fills the list with all entities of the specified type in the instance. The list is not in any specific order.

Since

SketchUp 2018, API 6.0

Parameters

[in]	entities	The entities object to be queried.
[in]	type	The type of entities to be collected.
[out]	list	The list object to be filled.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_INVALID_OUTPUT if list is not a valid object

enum SUResult SUEntitiesErase ( SUEntitiesRef  entities, size_t  len, SUEntityRef  elements[]  )

related

Erases elements from an entities object. The input elements are destroyed, so the array elements are invalidated to prevent user from attempting to use destroyed entities.

Since

SketchUp 2017, API 5.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The number of entities in the array.
[in]	elements	The elements to be destroyed.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if elements is NULL
• SU_ERROR_UNSUPPORTED if any of the elements in the array are not contained by entities

enum SUResult SUEntitiesFill ( SUEntitiesRef  entities, SUGeometryInputRef  geom_input, bool  weld_vertices  )

related

SUEntitiesFill is the fastest way to populate an entities object. The important precondition is that no duplicate data should be given.

NOTE: Faces included in the geometry input object will be merged together when using this function. This only applies to geometry in the geometry input object and not to any already-existing geometry in the entities object. Examples of merging are:

• If weld_vertices is true, duplicated vertices are merged.
• Coincident faces are merged.
• Coincident faces with opposite normals are merged into a single face using the appropriate materials from both faces as the front and back materials.
• Faces are created from coplanar edge loops.
• Conincident edges are merged. Visibility is retained when visible and invisible edges are welded together. Hardness is retained when hard and soft edges are welded together.

Parameters

[in,out]	entities	The entities to populate. Must be an empty entities object.
[in]	geom_input	The geometry input that the entities object is to be populated with.
[in]	weld_vertices	Flag indicating whether to join coincident vertices.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities or geom_input are invalid objects

enum SUResult SUEntitiesGetActiveSectionPlane ( SUEntitiesRef  entities, SUSectionPlaneRef *  section_plane  )

related

Get the active section plane for this entities object.

Since

SketchUp 2021.1, API 9.1

Parameters

[in]	entities
[out]	section_plane

Returns

• SU_ERROR_NONE on success.
• SU_ERROR_INVALID_INPUT if entities is not a valid object.
• SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL.
• SU_ERROR_OVERWRITE_VALID if section_plane already references a valid object.
• SU_ERROR_NO_DATA if entities has no active section plane.

enum SUResult SUEntitiesGetArcCurves ( SUEntitiesRef  entities, size_t  len, SUArcCurveRef  arccurves[], size_t *  count  )

related

Retrieves the arccurves in the entities object that are not associated with a face.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[in]	len	The number of arccurves to retrieve.
[out]	arccurves	The arccurves retrieved.
[out]	count	The number of curves retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if arccurves or count is NULL

enum SUResult SUEntitiesGetBoundingBox ( SUEntitiesRef  entities, struct SUBoundingBox3D *  bbox  )

related

Retrieves the bounding box of the entities.

Parameters

[in]	entities	The entities object.
[out]	bbox	The bounding box retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if bbox is NULL

enum SUResult SUEntitiesGetBoundingBoxLLA ( SUEntitiesRef  entities, struct SUBoundingBox3D *  bbox  )

related

Retrieves the LLA coordinates (Latidue, Longitude and Altitude) bounding box of the given entities object.

Note

Note that the altitude is calculated based on the model origin. Example: If an entities object has a bounding box with the following values {100,100,100}, {200,200,200} the result will be something like the following: {Latitude, Longitude, 100/METERS_TO_INCHES}, {Latitude, Longitude, 200/METERS_TO_INCHES} where Latitude and Longitude are the geographical coordinates and altitude is just a conversion from inches to meters.

Since

SketchUp 2018 M0, API 6.0

Parameters

[in]	entities	The entities object.
[out]	bbox	The latidue longitude and altitude bounding box retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NO_DATA if entities doesn't belong to a valid model.
• SU_ERROR_NULL_POINTER_OUTPUT if bbox is NULL

SUModelRef model = SU_INVALID;
SUModelLoadStatus status;
SUResult res = SUModelCreateFromFileWithStatus(&model, "path/to/face.skp", &status);
if (res != SU_ERROR_NONE) {
    // Handle error
    return 1;
}

// Get the entity container of the model
SUEntitiesRef entities = SU_INVALID;
SUModelGetEntities(model, &entities);

// Retrieve the bounding box in LLA coordinates
SUBoundingBox3D box_lla;
res = SUEntitiesGetBoundingBoxLLA(entities, &box_lla);
if (res == SU_ERROR_NONE) {
    // Process box_lla
}

SUModelRelease(&model);

enum SUResult SUEntitiesGetCurves ( SUEntitiesRef  entities, size_t  len, SUCurveRef  curves[], size_t *  count  )

related

Retrieves the curves in the entities object that are not associated with a face.

Parameters

[in]	entities	The entities object.
[in]	len	The number of curves to retrieve.
[out]	curves	The curves retrieved.
[out]	count	The number of curves retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if curves or count is NULL

enum SUResult SUEntitiesGetDimensions ( SUEntitiesRef  entities, size_t  len, SUDimensionRef  dimensions[], size_t *  count  )

related

Retrieves the dimensions in the entities object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	entities	The entities object.
[in]	len	The number of dimensions to retrieve.
[out]	dimensions	The dimensions retrieved.
[out]	count	The number of dimensions retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if dimensions or count is NULL

enum SUResult SUEntitiesGetEdges ( SUEntitiesRef  entities, bool  standalone_only, size_t  len, SUEdgeRef  edges[], size_t *  count  )

related

Retrieves the edges in the entities object.

Parameters

[in]	entities	The entities object.
[in]	standalone_only	Whether to get all edges (false) or only the edges not attached to curves and faces (true).
[in]	len	The number of edges to retrieve.
[out]	edges	The edges retrieved.
[out]	count	The number of edges retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if edges or count is NULL

enum SUResult SUEntitiesGetFaces ( SUEntitiesRef  entities, size_t  len, SUFaceRef  faces[], size_t *  count  )

related

Retrieves the faces in the entities object.

Parameters

[in]	entities	The entities object.
[in]	len	The number of faces to retrieve.
[out]	faces	The faces retrieved.
[out]	count	The number of faces retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if faces or count is NULL

enum SUResult SUEntitiesGetGroups ( SUEntitiesRef  entities, size_t  len, SUGroupRef  groups[], size_t *  count  )

related

Retrieves the groups in the entities.

Parameters

[in]	entities	The entities object.
[in]	len	The number of groups to retrieve.
[out]	groups	The groups retrieved.
[out]	count	The number of groups retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if groups or count is NULL

enum SUResult SUEntitiesGetGuideLines ( SUEntitiesRef  entities, size_t  len, SUGuideLineRef  guide_lines[], size_t *  count  )

related

Retrieves the guide lines in the entities object.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[in]	len	The number of guide lines to retrieve.
[out]	guide_lines	The guide_lines retrieved.
[out]	count	The number of guide_lines retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if guide_lines or count is NULL

enum SUResult SUEntitiesGetGuidePoints ( SUEntitiesRef  entities, size_t  len, SUGuidePointRef  guide_points[], size_t *  count  )

related

Retrieves the guide points in the entities object.

Since

SketchUp 2014 M1, API 2.1

Parameters

[in]	entities	The entities object.
[in]	len	The number of guide points to retrieve.
[out]	guide_points	The guide_points retrieved.
[out]	count	The number of guide_points retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if guide_points or count is NULL

enum SUResult SUEntitiesGetImages ( SUEntitiesRef  entities, size_t  len, SUImageRef  images[], size_t *  count  )

related

Retrieves the array of image objects of a entities object.

Parameters

[in]	entities	The entities object.
[in]	len	The number of image objects to retrieve.
[out]	images	The image objects retrieved.
[out]	count	The number of image objects retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if images or count is NULL

enum SUResult SUEntitiesGetInstances ( SUEntitiesRef  entities, size_t  len, SUComponentInstanceRef  instances[], size_t *  count  )

related

Retrieves the component instances in the entities.

Parameters

[in]	entities	The entities object.
[in]	len	The number of component instances to retrieve.
[out]	instances	The component instances retrieved.
[out]	count	The number of component instances retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if instances or count is NULL

enum SUResult SUEntitiesGetNumArcCurves ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of arccurves in the entities object that are not associated with a face.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[out]	count	The number of arccurves.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumCurves ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of curves in the entities object that are not associated with a face.

Parameters

[in]	entities	The entities object.
[out]	count	The number of curves.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumDimensions ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of dimensions in the entities object.

Since

SketchUp 2017, API 5.0

Parameters

[in]	entities	The entities object.
[out]	count	The number of dimensions.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumEdges ( SUEntitiesRef  entities, bool  standalone_only, size_t *  count  )

related

Retrieves the number of edges in the entities object.

Parameters

[in]	entities	The entities object.
[in]	standalone_only	Whether to count all edges (false) or only the edges not attached to curves and faces (true).
[out]	count	The number of edges.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumFaces ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of faces in the entities object.

Parameters

[in]	entities	The entities object.
[out]	count	The number of faces.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumGroups ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of groups in the entities.

Parameters

[in]	entities	The entities object.
[out]	count	The number of groups.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is an invalid entities object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumGuideLines ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of guide lines in the entities object.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[out]	count	The number of guide_lines.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumGuidePoints ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of guide points in the entities object.

Since

SketchUp 2014 M1, API 2.1

Parameters

[in]	entities	The entities object.
[out]	count	The number of guide_points.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumImages ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of images in the entities.

Parameters

[in]	entities	The entities object.
[out]	count	The number of image objects.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumInstances ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of component instances in the entities.

Parameters

[in]	entities	The entities object.
[out]	count	The number of component instances.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is an invalid entities object.
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumPolyline3ds ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of polyline3d's in the entities object.

Parameters

[in]	entities	The entities object.
[out]	count	The the number of polyline3d's.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumSectionPlanes ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of section planes in the entities object.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[out]	count	The number of section planes.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetNumTexts ( SUEntitiesRef  entities, size_t *  count  )

related

Retrieves the number of texts in the entities object.

Since

SketchUp 2018, API 6.0

Parameters

[in]	entities	The entities object.
[out]	count	The number of texts.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntitiesGetParent ( SUEntitiesRef  entities, struct SUEntitiesParent *  parent  )

related

Get the parent component definition or model that owns this entities object.

Since

SketchUp 2021.1, API 9.1

Parameters

[in]	entities
[out]	parent

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if parent is NULL.

enum SUResult SUEntitiesGetPolyline3ds ( SUEntitiesRef  entities, size_t  len, SUPolyline3dRef  lines[], size_t *  count  )

related

Retrieves the polyline3d's in the entities object.

Parameters

[in]	len	The number of polyline3d's to retrieve.
[in]	entities	The entities object.
[out]	lines	The polyline3d's retrieved.
[out]	count	The number of polyline3d's retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if lines or count is NULL

enum SUResult SUEntitiesGetSectionPlanes ( SUEntitiesRef  entities, size_t  len, SUSectionPlaneRef  section_planes[], size_t *  count  )

related

Retrieves the section planes in the entities.

Since

SketchUp 2016, API 4.0

Parameters

[in]	entities	The entities object.
[in]	len	The number of section planes to retrieve.
[out]	section_planes	The section planes retrieved.
[out]	count	The number of section planes retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if section_planes or count is NULL

enum SUResult SUEntitiesGetTexts ( SUEntitiesRef  entities, size_t  len, SUTextRef  texts[], size_t *  count  )

related

Retrieves the texts in the entities.

Since

SketchUp 2018, API 6.0

Parameters

[in]	entities	The entities object.
[in]	len	The number of section planes to retrieve.
[out]	texts	The texts retrieved.
[out]	count	The number of texts retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_OUTPUT if texts or count is NULL

enum SUResult SUEntitiesHasSectionCuts ( SUEntitiesRef  entities, bool *  has_section_cuts  )

related

Retrieves a boolean by recursively searching through the entities determining whether the entities has an active section plane or any of its nested components have an active section plane.

Since

SketchUp 2018, API 6.0

Parameters

[in]	entities	The entities object.
[out]	has_section_cuts	The bool value retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is invalid
• SU_ERROR_NULL_POINTER_OUTPUT if has_section_cuts is NULL

enum SUResult SUEntitiesIsRecursivelyEmpty ( SUEntitiesRef  entities, bool *  is_empty  )

related

Retrieves a boolean indicating whether the entities object is recursively empty. A recursively empty entities object is defined as one that either has zero entities or contains only instances of definitions with recursively empty entities objects.

Since

SketchUp 2017, API 5.0

Parameters

[in]	entities	The entities object.
[out]	is_empty	The bool value retrieved.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is invalid
• SU_ERROR_NULL_POINTER_OUTPUT if is_empty is NULL

enum SUResult SUEntitiesSetActiveSectionPlane ( SUEntitiesRef  entities, SUSectionPlaneRef  section_plane  )

related

Set the active section plane for this entities object.

Since

SketchUp 2021.1, API 9.1

Bug:

Before SketchUp 2023.1 (API 11.1) this function would not accept SU_INVALID as a valid section_plane value and would have returned SU_ERROR_INVALID_INPUT instead

Parameters

[in,out]	entities
[in]	section_plane	The section plane to activate or SU_INVALID if none should be active.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object.
• SU_ERROR_INVALID_ARGUMENT if section_plane doesn't belong to entities.

enum SUResult SUEntitiesTransform ( SUEntitiesRef  entities, size_t  len, SUEntityRef  elements[], const struct SUTransformation *  trans  )

related

Applies a 3D transformation to the elements of the provided entity array.

Since

SketchUp 2017, API 5.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The number of entities in the array.
[in]	elements	The elements to be transformed.
[in]	trans	The transform to be applied.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if trans or elements are NULL
• SU_ERROR_UNSUPPORTED if any of the elements in the array are not contained by entities
• SU_ERROR_GENERIC if the transformation operation fails

enum SUResult SUEntitiesTransformMultiple ( SUEntitiesRef  entities, size_t  len, SUEntityRef  elements[], const struct SUTransformation  tranforms[]  )

related

Applies a 3D transformations to the elements of the provided entity array. The arrays of elements and transformations must be the same length.

Since

SketchUp 2017, API 5.0

Parameters

[in,out]	entities	The entities object.
[in]	len	The number of entities in the array.
[in]	elements	The elements to be transformed.
[in]	tranforms	The transformations to be applied.

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if elements or tranforms are NULL
• SU_ERROR_UNSUPPORTED if any of the elements in the array are not contained by entities
• SU_ERROR_GENERIC if the transformation operation fails

enum SUResult SUEntitiesWeld ( SUEntitiesRef  entities, size_t  num_edges, SUEdgeRef  edges[], SUEntityListRef  list  )

related

Takes a set of edges and find all possible chains of edges and connect them with a SUCurveRef.

   A curve will not cross another curve. They will split where multiple
   curves meet.

Since

SketchUp 2020.1, API 8.1

Parameters

[in,out]	entities	The entities object to be queried.
[in]	num_edges	The length of the array of edge objects.
[in]	edges	The array of edge objects to weld.
[out]	list	The list object to be filled with SUCurveRef objects.

See Also

SUArcCurveRef

SUCurveRef

Returns

• SU_ERROR_NONE on success
• SU_ERROR_INVALID_INPUT if entities is not a valid object
• SU_ERROR_NULL_POINTER_INPUT if edges is NULL
• SU_ERROR_INVALID_OUTPUT if list is not a valid object
• SU_ERROR_INVALID_ARGUMENT if edges contains edges that don't belong to the same entities collection.

---

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

• SketchUpAPI/model/defs.h
• SketchUpAPI/model/entities.h