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	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...
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]	face	The face object.
[in]	vertices3d	The array of vertices references by the added loop.
[in]	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 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]	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 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]	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]	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]

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]

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]	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]	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