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
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 | SUEntitiesAddDimensions (SUEntitiesRef entities_ref, size_t len, const SUDimensionRef dim_refs[])
| Adds dimension objects to an 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 SUEntitiesAddDimensions | ( | SUEntitiesRef | entities_ref,
|  | size_t | len,
|  | const SUDimensionRef | dim_refs[]
| ) |  |
| related

Adds dimension objects to an entities object.

Since
  SketchUp 2026.1, API 14.1

Parameters

  [in,out] | entities_ref | The entities object.
  [in] | len | The length of the array of dimension objects.
  [in] | dim_refs | The array of dimension objects to add.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `entities_ref` is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if `dim_refs` is `NULL`

Note
  Some dimension creation and manipulation functions such as SUDimensionLinearCreate() and SUDimensionRadialCreate() may have already added the dimension to a SUEntitiesRef. If that is the case users should take care not to add the dimension to a different SUEntitiesRef.

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