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

References a face. More...

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

Inherits SUDrawingElementRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUFaceToEntity (SUFaceRef face)
| Converts from an SUFaceRef to an SUEntityRef. This is essentially an upcast operation. More...
SUFaceRef | SUFaceFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUFaceRef. This is essentially a downcast operation so the given entity must be convertible to an SUFaceRef. More...
SUDrawingElementRef | SUFaceToDrawingElement (SUFaceRef face)
| Converts from an SUFaceRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUFaceRef | SUFaceFromDrawingElement (SUDrawingElementRef drawing_elem)
| Converts from an SUDrawingElementRef to an SUFaceRef. This is essentially a downcast operation so the given element must be convertible to an SUFaceRef. More...
enum SUResult | SUFaceCreate (SUFaceRef *face, const struct SUPoint3D vertices3d[], SULoopInputRef *outer_loop)
| Creates a face without holes. More...
enum SUResult | SUFaceCreateSimple (SUFaceRef *face, const struct SUPoint3D vertices3d[], size_t len)
| Creates a simple face without holes from an array of vertices. More...
enum SUResult | SUFaceGetNormal (SUFaceRef face, struct SUVector3D *normal)
| Retrieves the normal vector of a face object. More...
enum SUResult | SUFaceRelease (SUFaceRef *face)
| Releases a face object and its associated resources. More...
enum SUResult | SUFaceGetNumEdges (SUFaceRef face, size_t *count)
| Retrieves the number of edges in a face. More...
enum SUResult | SUFaceGetEdges (SUFaceRef face, size_t len, SUEdgeRef edges[], size_t *count)
| Retrieves the edges in the face. More...
enum SUResult | SUFaceGetNumEdgeUses (SUFaceRef face, size_t *count)
| Retrieves the number of edge uses in a face. More...
enum SUResult | SUFaceGetEdgeUses (SUFaceRef face, size_t len, SUEdgeUseRef edges[], size_t *count)
| Retrieves the edge uses in the face. More...
enum SUResult | SUFaceGetPlane (SUFaceRef face, struct SUPlane3D *plane)
| Retrieves the plane of the face. More...
enum SUResult | SUFaceGetNumVertices (SUFaceRef face, size_t *count)
| Retrieves the number of vertices that the face is associated with. More...
enum SUResult | SUFaceGetVertices (SUFaceRef face, size_t len, SUVertexRef vertices[], size_t *count)
| Retrieves the vertex objects associated with a face object. More...
enum SUResult | SUFaceGetOuterLoop (SUFaceRef face, SULoopRef *loop)
| Retrieves the outer loop of a face object. More...
enum SUResult | SUFaceGetNumInnerLoops (SUFaceRef face, size_t *count)
| Retrieves the number of loops in a face. More...
enum SUResult | SUFaceGetInnerLoops (SUFaceRef face, size_t len, SULoopRef loops[], size_t *count)
| Retrieves the loops in the face. More...
enum SUResult | SUFaceAddInnerLoop (SUFaceRef face, const struct SUPoint3D vertices3d[], SULoopInputRef *loop)
| Adds a hole to the face. The face object must be associated with a parent component. More...
enum SUResult | SUFaceGetNumOpenings (SUFaceRef face, size_t *count)
| Retrieves the number of openings in a face. More...
enum SUResult | SUFaceGetOpenings (SUFaceRef face, size_t len, SUOpeningRef openings[], size_t *count)
| Retrieves the openings in the face. The retrieved SUOpeningRef() objects must be manually released by calling SUOpeningRelease() on each one. More...
enum SUResult | SUFaceGetFrontMaterial (SUFaceRef face, SUMaterialRef *material)
| Retrieves the front material associated with a face object. More...
enum SUResult | SUFaceSetFrontMaterial (SUFaceRef face, SUMaterialRef material)
| Sets the front material of a face object. More...
enum SUResult | SUFaceGetBackMaterial (SUFaceRef face, SUMaterialRef *material)
| Retrieves the back material associate with a face object. More...
enum SUResult | SUFaceSetBackMaterial (SUFaceRef face, SUMaterialRef material)
| Sets the back material of a face object. More...
enum SUResult | SUFaceIsFrontMaterialAffine (SUFaceRef face, bool *is_affine)
| Retrieves the flag indicating whether a face object has an affine texture applied to its front. More...
enum SUResult | SUFaceIsBackMaterialAffine (SUFaceRef face, bool *is_affine)
| Retrieves the flag indicating whether a face object has an affine texture applied to its back. More...
enum SUResult | SUFaceGetArea (SUFaceRef face, double *area)
| Computes the area of the face, taking into account all the inner loops and cuts from openings. More...
enum SUResult | SUFaceGetAreaWithTransform (SUFaceRef face, const struct SUTransformation *transform, double *area)
| Computes the area of the face with the provided transformation applied. More...
enum SUResult | SUFaceIsComplex (SUFaceRef face, bool *is_complex)
| Retrieves a flag indicating whether the face is complex, i.e. contains either inner loops or openings cut by attached component instances or attached groups. More...
enum SUResult | SUFaceGetUVHelper (SUFaceRef face, bool front, bool back, SUTextureWriterRef texture_writer, SUUVHelperRef *uv_helper)
| Creates a UV helper for the face. More...
enum SUResult | SUFaceGetUVHelperWithTextureHandle (SUFaceRef face, bool front, bool back, SUTextureWriterRef texture_writer, long textureHandle, SUUVHelperRef *uv_helper)
| Creates a UV helper for the face given a specific texture handle. More...
enum SUResult | SUFaceGetNumAttachedDrawingElements (SUFaceRef face, size_t *count)
| Retrieves the number of attached drawing elements in a face. More...
enum SUResult | SUFaceGetAttachedDrawingElements (SUFaceRef face, size_t len, SUDrawingElementRef elems[], size_t *count)
| Retrieves the attached drawing elements in the face. More...
enum SUResult | SUFaceReverse (SUFaceRef face)
| Reverses a face object. More...
enum SUResult | SUFaceGetUVTileAt (SUFaceRef face, const struct SUPoint3D *reference, bool front, struct SUPoint3D points[4], struct SUPoint2D uv_coords[4])
| Retrieves the world and UV coordinates of a UV tile. More...
enum SUResult | SUFaceIsTexturePositioned (SUFaceRef face, bool front, bool *is_positioned)
| Retrieves a flag indicating whether the face has a positioned texture. More...
enum SUResult | SUFaceClearTexturePosition (SUFaceRef face, bool front)
| Clears the texture position. More...
enum SUResult | SUFaceIsTextureProjected (SUFaceRef face, bool front, bool *is_projected)
| Retrieves a flag indicating whether the face has a projected texture. More...
enum SUResult | SUFaceGetTextureProjection (SUFaceRef face, bool front, struct SUVector3D *vector)
| Retrieves a vector representing the projection direction for the texture on the given side of the face. More...
enum SUResult | SUFaceClearTextureProjection (SUFaceRef face, bool front)
| Clears the texture projection. More...
enum SUResult | SUFacePositionMaterial (SUFaceRef face, bool front, struct SUMaterialPositionInput *mapping)
| Positions a textured material on the face. More...
enum SUResult | SUFaceCoplanarWith (SUFaceRef face, SUFaceRef other_face, bool *is_coplanar)
| Retrieves a flag indicating whether `face` is coplanar with `other_face`. 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 face.

## Friends And Related Function Documentation

enum SUResult SUFaceAddInnerLoop | ( | SUFaceRef | face,
|  | const struct SUPoint3D | vertices3d[],
|  | SULoopInputRef * | loop
| ) |  |
| related

Adds a hole to the face. The face object must be associated with a parent component.

Parameters

  [in,out] | face | The face object.
  [in] | vertices3d | The array of vertices references by the added loop.
  [in,out] | loop | The loop input that describes the inner loop. If the function is successful, the new face will take ownership of the loop and this reference will be invalidated.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if vertices3d or loop is NULL
  - SU_ERROR_INVALID_INPUT if loop contains invalid input data
  - SU_ERROR_GENERIC if the face object is not associated with a parent component.

enum SUResult SUFaceClearTexturePosition | ( | SUFaceRef | face,
|  | bool | front
| ) |  |
| related

Clears the texture position.

This is similar to reseting the texture position from the SketchUp UI face context menu.

Since
  SketchUp 2022.0, API 10.0

Parameters

  [in,out] | face |
  [in] | front | Flag indicating whether to clear the front or back side of the face.

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object.

enum SUResult SUFaceClearTextureProjection | ( | SUFaceRef | face,
|  | bool | front
| ) |  |
| related

Clears the texture projection.

This is similar to toggling off Projection from the Position Texture tool in the UI.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in,out] | face |
  [in] | front | Flag indicating whether to clear the front or back side of the face.

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object.

enum SUResult SUFaceCoplanarWith | ( | SUFaceRef | face,
|  | SUFaceRef | other_face,
|  | bool * | is_coplanar
| ) |  |
| related

Retrieves a flag indicating whether `face` is coplanar with `other_face`.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | face | The `face` object.
  [in] | other_face | The `other_face` object.
  [out] | is_coplanar | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `face` or `other_face` is not a valid face object
  - SU_ERROR_NULL_POINTER_OUTPUT if `is_coplanar` is NULL

enum SUResult SUFaceCreate | ( | SUFaceRef * | face,
|  | const struct SUPoint3D | vertices3d[],
|  | SULoopInputRef * | outer_loop
| ) |  |
| related

Creates a face without holes.

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

  [out] | face | The face object created.
  [in] | vertices3d | The array of vertices that make the face.
  [in,out] | outer_loop | The loop input that describes the outer loop of the face. If the function is successful, the new face will take ownership of the loop and this reference will be invalidated.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if vertices3d or outer_loop is NULL
  - SU_ERROR_INVALID_INPUT if outer_loop contains invalid input data
  - SU_ERROR_GENERIC if the the points specified by outer_loop do not lie on a plane within 1.0e-3 tolerance
  - SU_ERROR_NULL_POINTER_OUTPUT if face is NULL
  - SU_ERROR_OVERWRITE_VALID if face already refers to a valid object

enum SUResult SUFaceCreateSimple | ( | SUFaceRef * | face,
|  | const struct SUPoint3D | vertices3d[],
|  | size_t | len
| ) |  |
| related

Creates a simple face without holes from an array of vertices.

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

  [out] | face | The face object created.
  [in] | vertices3d | The array of vertices of the face.
  [in] | len | The length of the array of vertices.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if vertices3d is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if face is NULL
  - SU_ERROR_GENERIC if the specified vertices do not lie on a plane within 1.0e-3 tolerance
  - SU_ERROR_OVERWRITE_VALID if face already refers to a valid face object

SUFaceRef SUFaceFromDrawingElement | ( | SUDrawingElementRef | drawing_elem | ) |
| related

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

Parameters

  [in] | drawing_elem | The given element reference.

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

SUFaceRef SUFaceFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Parameters

  [in] | entity | The given entity reference.

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

enum SUResult SUFaceGetArea | ( | SUFaceRef | face,
|  | double * | area
| ) |  |
| related

Computes the area of the face, taking into account all the inner loops and cuts from openings.

Parameters

  [in] | face | The face object.
  [out] | area | The area retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if area is NULL

enum SUResult SUFaceGetAreaWithTransform | ( | SUFaceRef | face,
|  | const struct SUTransformation * | transform,
|  | double * | area
| ) |  |
| related

Computes the area of the face with the provided transformation applied.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | face | The face object.
  [in] | transform | A transformation to be appllied to the face.
  [out] | area | The area retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if transformation is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if area is NULL

enum SUResult SUFaceGetAttachedDrawingElements | ( | SUFaceRef | face,
|  | size_t | len,
|  | SUDrawingElementRef | elems[],
|  | size_t * | count
| ) |  |
| related

Retrieves the attached drawing elements in the face.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | face | The face object.
  [in] | len | The number of attached drawing elements to retrieve.
  [out] | elems | The attached drawing elements retrieved.
  [out] | count | The number of attached drawing elements retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if elems or count is NULL

enum SUResult SUFaceGetBackMaterial | ( | SUFaceRef | face,
|  | SUMaterialRef * | material
| ) |  |
| related

Retrieves the back material associate with a face object.

Parameters

  [in] | face | The face object.
  [out] | material | The material object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if material is NULL
  - SU_ERROR_INVALID_ARGUMENT is the material is owned by a layer or image

enum SUResult SUFaceGetEdges | ( | SUFaceRef | face,
|  | size_t | len,
|  | SUEdgeRef | edges[],
|  | size_t * | count
| ) |  |
| related

Retrieves the edges in the face.

Parameters

  [in] | face | The face object.
  [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 face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if edges or count is NULL

enum SUResult SUFaceGetEdgeUses | ( | SUFaceRef | face,
|  | size_t | len,
|  | SUEdgeUseRef | edges[],
|  | size_t * | count
| ) |  |
| related

Retrieves the edge uses in the face.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | face | The face object.
  [in] | len | The number of edge uses to retrieve.
  [out] | edges | The edgeuses retrieved.
  [out] | count | The number of edge uses retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if edges or count is NULL

enum SUResult SUFaceGetFrontMaterial | ( | SUFaceRef | face,
|  | SUMaterialRef * | material
| ) |  |
| related

Retrieves the front material associated with a face object.

Parameters

  [in] | face | The face object.
  [out] | material | The material object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if material is NULL

enum SUResult SUFaceGetInnerLoops | ( | SUFaceRef | face,
|  | size_t | len,
|  | SULoopRef | loops[],
|  | size_t * | count
| ) |  |
| related

Retrieves the loops in the face.

Parameters

  [in] | face | The face object.
  [in] | len | The number of loops to retrieve.
  [out] | loops | The inner loops retrieved.
  [out] | count | The number of inner loops retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face object is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if loops or count is NULL

enum SUResult SUFaceGetNormal | ( | SUFaceRef | face,
|  | struct SUVector3D * | normal
| ) |  |
| related

Retrieves the normal vector of a face object.

Parameters

  [in] | face | The face object.
  [out] | normal | The 3d normal vector retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if normal is NULL

enum SUResult SUFaceGetNumAttachedDrawingElements | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of attached drawing elements in a face.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | face | The face object.
  [out] | count | The number of attached drawing elements.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if the face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetNumEdges | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of edges in a face.

Parameters

  [in] | face | The face object.
  [out] | count | The number of edges.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if the face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetNumEdgeUses | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of edge uses in a face.

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | face | The face object.
  [out] | count | The number of edge uses.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if the face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetNumInnerLoops | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of loops in a face.

Parameters

  [in] | face | The face object.
  [out] | count | The number of inner loops.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if the face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetNumOpenings | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of openings in a face.

Since
  SketchUp 2014, API 2.0

Parameters

  [in] | face | The face object.
  [out] | count | The number of openings.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if the face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetNumVertices | ( | SUFaceRef | face,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of vertices that the face is associated with.

Parameters

  [in] | face | The face object.
  [out] | count | The number of vertices.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUFaceGetOpenings | ( | SUFaceRef | face,
|  | size_t | len,
|  | SUOpeningRef | openings[],
|  | size_t * | count
| ) |  |
| related

Retrieves the openings in the face. The retrieved SUOpeningRef() objects must be manually released by calling SUOpeningRelease() on each one.

Since
  SketchUp 2014, API 2.0

Parameters

  [in] | face | The face object.
  [in] | len | The number of openings to retrieve.
  [out] | openings | The openings retrieved.
  [out] | count | The number of openings retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if openings or count is NULL

enum SUResult SUFaceGetOuterLoop | ( | SUFaceRef | face,
|  | SULoopRef * | loop
| ) |  |
| related

Retrieves the outer loop of a face object.

Parameters

  [in] | face | The face object.
  [out] | loop | The loop object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if loop is NULL
  - SU_ERROR_OVERWRITE_VALID if loop already refers to a valid object

enum SUResult SUFaceGetPlane | ( | SUFaceRef | face,
|  | struct SUPlane3D * | plane
| ) |  |
| related

Retrieves the plane of the face.

Parameters

  [in] | face | The face object.
  [out] | plane | The 3d plane retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if plane is NULL

enum SUResult SUFaceGetTextureProjection | ( | SUFaceRef | face,
|  | bool | front,
|  | struct SUVector3D * | vector
| ) |  |
| related

Retrieves a vector representing the projection direction for the texture on the given side of the face.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | face |
  [in] | front | Flag indicating whether to use the front or back side of the face.
  [out] | vector |

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object.
  - SU_ERROR_NO_DATA if `face` does not have a projected material applied.
  - SU_ERROR_NULL_POINTER_OUTPUT if `vector` is NULL.

enum SUResult SUFaceGetUVHelper | ( | SUFaceRef | face,
|  | bool | front,
|  | bool | back,
|  | SUTextureWriterRef | texture_writer,
|  | SUUVHelperRef * | uv_helper
| ) |  |
| related

Creates a UV helper for the face.

Parameters

  [in] | face | The face object.
  [in] | front | Flag indicating whether to compute the UV coordinates for the front of the face.
  [in] | back | Flag indicating whether to compute the UV coordinates for the back of the face.
  [in] | texture_writer | An optional texture writer to aid in texture coordinate calculations for non-affine textures.
  [out] | uv_helper | The UV helper object created. Must be deallocated via SUUVHelperRelease().

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if uv_helper is NULL

enum SUResult SUFaceGetUVHelperWithTextureHandle | ( | SUFaceRef | face,
|  | bool | front,
|  | bool | back,
|  | SUTextureWriterRef | texture_writer,
|  | long | textureHandle,
|  | SUUVHelperRef * | uv_helper
| ) |  |
| related

Creates a UV helper for the face given a specific texture handle.

Parameters

  [in] | face | The face object.
  [in] | front | Flag indicating whether to compute the UV coordinates for the front of the face.
  [in] | back | Flag indicating whether to compute the UV coordinates for the back of the face.
  [in] | texture_writer | An optional texture writer to aid in texture coordinate calculations for non-affine textures.
  [in] | textureHandle | The handle of the image that should be mapped to the face.
  [out] | uv_helper | The UV helper object created. Must be deallocated via SUUVHelperRelease().

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if uv_helper is NULL.

enum SUResult SUFaceGetUVTileAt | ( | SUFaceRef | face,
|  | const struct SUPoint3D * | reference,
|  | bool | front,
|  | struct SUPoint3D | points[4],
|  | struct SUPoint2D | uv_coords[4]
| ) |  |
| related

Retrieves the world and UV coordinates of a UV tile.

The UV tile bounds the given reference point on the plane of the face. If the reference isn't on the plane of the face it will be projected onto it.

The world coordinates are on the plane of the face unless the texture is projected. When the texture is projected the the world points are on an arbitrary plane that is perpendicular to the projection direction.

The returned `points` and `uv_coords` can be used directly with SUMaterialPositionInput.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | face |
  [in] | reference | A point of reference on the plane of the face.
  [in] | front | Flag indicating whether to compute the UV Tile for the front side of the face.
  [out] | points | World coordinates for the bounding UV tile.
  [out] | uv_coords | UV coordinates for the bounding UV tile.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `face` is not a valid object.
  - SU_ERROR_NO_DATA if the `face` has no textured material of the given side.
  - SU_ERROR_NULL_POINTER_INPUT if `reference` is NULL.
  - SU_ERROR_NULL_POINTER_OUTPUT if `points` is NULL.
  - SU_ERROR_NULL_POINTER_OUTPUT if `uv_coords` is NULL.

enum SUResult SUFaceGetVertices | ( | SUFaceRef | face,
|  | size_t | len,
|  | SUVertexRef | vertices[],
|  | size_t * | count
| ) |  |
| related

Retrieves the vertex objects associated with a face object.

Parameters

  [in] | face | The face object.
  [in] | len | The number of vertices to retrieve.
  [out] | vertices | The vertices retrieved.
  [out] | count | The number of vertices retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if vertices or count is NULL

enum SUResult SUFaceIsBackMaterialAffine | ( | SUFaceRef | face,
|  | bool * | is_affine
| ) |  |
| related

Retrieves the flag indicating whether a face object has an affine texture applied to its back.

Parameters

  [in] | face | The face object.
  [out] | is_affine | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if is_affine is NULL
  - SU_ERROR_NO_DATA if face does not have a textured material applied to its back

enum SUResult SUFaceIsComplex | ( | SUFaceRef | face,
|  | bool * | is_complex
| ) |  |
| related

Retrieves a flag indicating whether the face is complex, i.e. contains either inner loops or openings cut by attached component instances or attached groups.

Parameters

  [in] | face | The face object.
  [out] | is_complex | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid face object
  - SU_ERROR_NULL_POINTER_OUTPUT if is_complex is NULL

enum SUResult SUFaceIsFrontMaterialAffine | ( | SUFaceRef | face,
|  | bool * | is_affine
| ) |  |
| related

Retrieves the flag indicating whether a face object has an affine texture applied to its front.

Parameters

  [in] | face | The face object.
  [out] | is_affine | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if is_affine is NULL
  - SU_ERROR_NO_DATA if face does not have a textured material applied to its front

enum SUResult SUFaceIsTexturePositioned | ( | SUFaceRef | face,
|  | bool | front,
|  | bool * | is_positioned
| ) |  |
| related

Retrieves a flag indicating whether the face has a positioned texture.

A texture is positioned when it's not using the default texture coordinates.

When a user uses the Paint Bucket Tool to apply a material sampled from the Material Browser it will use default texture coordinates and not be positioned. It will be positioned if the user uses the Position Texture Tool.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | face |
  [in] | front | Flag indicating whether to check the front or back side of the face.
  [out] | is_positioned |

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object.
  - SU_ERROR_NULL_POINTER_OUTPUT if `is_positioned` is NULL.

enum SUResult SUFaceIsTextureProjected | ( | SUFaceRef | face,
|  | bool | front,
|  | bool * | is_projected
| ) |  |
| related

Retrieves a flag indicating whether the face has a projected texture.

A texture is projected when the user enables this property via the Position Texture Tool.

In SketchUp a projected texture can use an arbitrary plane, rather than the face's own plane. The projection vector defines the normal of this plane and used this to project the texture onto the face.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | face |
  [in] | front | Flag indicating whether to check the front or back side of the face.
  [out] | is_projected |

Returns
  - SU_ERROR_NONE on success.
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object.
  - SU_ERROR_NULL_POINTER_OUTPUT if `is_projected` is NULL.

enum SUResult SUFacePositionMaterial | ( | SUFaceRef | face,
|  | bool | front,
|  | struct SUMaterialPositionInput * | mapping
| ) |  |
| related

Positions a textured material on the face.

The texture is positioned using 1 to 4 pairs of model and uv points. The points are used in pairs to describe where a point in the texture image is positioned on the face. This is similar to how textures are positioned in the UI using the Position Texture tool.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in,out] | face |
  [in] | front | Flag indicating whether to use the front or back side of the face.
  [in] | mapping |

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `face` is not a valid face object
  - SU_ERROR_NULL_POINTER_INPUT if `mapping` is NULL
  - SU_ERROR_INVALID_ARGUMENT if `mapping` doesn't have a valid textured material
  - SU_ERROR_INVALID_ARGUMENT if `mapping` doesn't have 1-4 points/uv_coords.
  - SU_ERROR_INVALID_ARGUMENT if valid texture coordinates could not be computed from `mapping`.

enum SUResult SUFaceRelease | ( | SUFaceRef * | face | ) |
| related

Releases a face object and its associated resources.

Parameters

  [in,out] | face | The face object.

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

enum SUResult SUFaceReverse | ( | SUFaceRef | face | ) |
| related

Reverses a face object.

Since
  SketchUp 2016, API 4.0

Parameters

  [in,out] | face | The face object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object

enum SUResult SUFaceSetBackMaterial | ( | SUFaceRef | face,
|  | SUMaterialRef | material
| ) |  |
| related

Sets the back material of a face object.

Parameters

  [in,out] | face | The face object.
  [in] | material | The material object to set. If invalid, this will set the material to the default material.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object

enum SUResult SUFaceSetFrontMaterial | ( | SUFaceRef | face,
|  | SUMaterialRef | material
| ) |  |
| related

Sets the front material of a face object.

Parameters

  [in,out] | face | The face object.
  [in] | material | The material object to set. If invalid, this will set the material to the default material.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if face is not a valid object
  - SU_ERROR_INVALID_ARGUMENT is the material is owned by a layer or image

SUDrawingElementRef SUFaceToDrawingElement | ( | SUFaceRef | face | ) |
| related

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

Parameters

  [in] | face | The given face reference.

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

SUEntityRef SUFaceToEntity | ( | SUFaceRef | face | ) |
| related

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

Parameters

  [in] | face | The given face reference.

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