SketchUp C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator 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...
 

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]faceThe face object.
[in]vertices3dThe array of vertices references by the added loop.
[in]loopThe 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
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]face
[in]frontFlag indicating whether to clear the front or back side of the face.
Returns
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]frontFlag indicating whether to clear the front or back side of the face.
Returns
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]faceThe face object created.
[in]vertices3dThe array of vertices that make the face.
[in]outer_loopThe 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
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]faceThe face object created.
[in]vertices3dThe array of vertices of the face.
[in]lenThe length of the array of vertices.
Returns
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_elemThe 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]entityThe 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]faceThe face object.
[out]areaThe area retrieved.
Returns
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]faceThe face object.
[in]transformA transformation to be appllied to the face.
[out]areaThe area retrieved.
Returns
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]faceThe face object.
[in]lenThe number of attached drawing elements to retrieve.
[out]elemsThe attached drawing elements retrieved.
[out]countThe number of attached drawing elements retrieved.
Returns
enum SUResult SUFaceGetBackMaterial ( SUFaceRef  face,
SUMaterialRef material 
)
related

Retrieves the back material associate with a face object.

Parameters
[in]faceThe face object.
[out]materialThe material object retrieved.
Returns
enum SUResult SUFaceGetEdges ( SUFaceRef  face,
size_t  len,
SUEdgeRef  edges[],
size_t *  count 
)
related

Retrieves the edges in the face.

Parameters
[in]faceThe face object.
[in]lenThe number of edges to retrieve.
[out]edgesThe edges retrieved.
[out]countThe number of edges retrieved.
Returns
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]faceThe face object.
[in]lenThe number of edge uses to retrieve.
[out]edgesThe edgeuses retrieved.
[out]countThe number of edge uses retrieved.
Returns
enum SUResult SUFaceGetFrontMaterial ( SUFaceRef  face,
SUMaterialRef material 
)
related

Retrieves the front material associated with a face object.

Parameters
[in]faceThe face object.
[out]materialThe material object retrieved.
Returns
enum SUResult SUFaceGetInnerLoops ( SUFaceRef  face,
size_t  len,
SULoopRef  loops[],
size_t *  count 
)
related

Retrieves the loops in the face.

Parameters
[in]faceThe face object.
[in]lenThe number of loops to retrieve.
[out]loopsThe inner loops retrieved.
[out]countThe number of inner loops retrieved.
Returns
enum SUResult SUFaceGetNormal ( SUFaceRef  face,
struct SUVector3D normal 
)
related

Retrieves the normal vector of a face object.

Parameters
[in]faceThe face object.
[out]normalThe 3d normal vector retrieved.
Returns
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]faceThe face object.
[out]countThe number of attached drawing elements.
Returns
enum SUResult SUFaceGetNumEdges ( SUFaceRef  face,
size_t *  count 
)
related

Retrieves the number of edges in a face.

Parameters
[in]faceThe face object.
[out]countThe number of edges.
Returns
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]faceThe face object.
[out]countThe number of edge uses.
Returns
enum SUResult SUFaceGetNumInnerLoops ( SUFaceRef  face,
size_t *  count 
)
related

Retrieves the number of loops in a face.

Parameters
[in]faceThe face object.
[out]countThe number of inner loops.
Returns
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]faceThe face object.
[out]countThe number of openings.
Returns
enum SUResult SUFaceGetNumVertices ( SUFaceRef  face,
size_t *  count 
)
related

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

Parameters
[in]faceThe face object.
[out]countThe number of vertices.
Returns
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]faceThe face object.
[in]lenThe number of openings to retrieve.
[out]openingsThe openings retrieved.
[out]countThe number of openings retrieved.
Returns
enum SUResult SUFaceGetOuterLoop ( SUFaceRef  face,
SULoopRef loop 
)
related

Retrieves the outer loop of a face object.

Parameters
[in]faceThe face object.
[out]loopThe loop object retrieved.
Returns
enum SUResult SUFaceGetPlane ( SUFaceRef  face,
struct SUPlane3D plane 
)
related

Retrieves the plane of the face.

Parameters
[in]faceThe face object.
[out]planeThe 3d plane retrieved.
Returns
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]frontFlag indicating whether to use the front or back side of the face.
[out]vector
Returns
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]faceThe face object.
[in]frontFlag indicating whether to compute the UV coordinates for the front of the face.
[in]backFlag indicating whether to compute the UV coordinates for the back of the face.
[in]texture_writerAn optional texture writer to aid in texture coordinate calculations for non-affine textures.
[out]uv_helperThe UV helper object created. Must be deallocated via SUUVHelperRelease().
Returns
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]faceThe face object.
[in]frontFlag indicating whether to compute the UV coordinates for the front of the face.
[in]backFlag indicating whether to compute the UV coordinates for the back of the face.
[in]texture_writerAn optional texture writer to aid in texture coordinate calculations for non-affine textures.
[in]textureHandleThe handle of the image that should be mapped to the face.
[out]uv_helperThe UV helper object created. Must be deallocated via SUUVHelperRelease().
Returns
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]referenceA point of reference on the plane of the face.
[in]frontFlag indicating whether to compute the UV Tile for the front side of the face.
[out]pointsWorld coordinates for the bounding UV tile.
[out]uv_coordsUV coordinates for the bounding UV tile.
Returns
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]faceThe face object.
[in]lenThe number of vertices to retrieve.
[out]verticesThe vertices retrieved.
[out]countThe number of vertices retrieved.
Returns
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]faceThe face object.
[out]is_affineThe flag retrieved.
Returns
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]faceThe face object.
[out]is_complexThe flag retrieved.
Returns
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]faceThe face object.
[out]is_affineThe flag retrieved.
Returns
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]frontFlag indicating whether to check the front or back side of the face.
[out]is_positioned
Returns
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]frontFlag indicating whether to check the front or back side of the face.
[out]is_projected
Returns
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]frontFlag indicating whether to use the front or back side of the face.
[in]mapping
Returns
enum SUResult SUFaceRelease ( SUFaceRef face)
related

Releases a face object and its associated resources.

Parameters
[in]faceThe face object.
Returns
enum SUResult SUFaceReverse ( SUFaceRef  face)
related

Reverses a face object.

Since
SketchUp 2016, API 4.0
Parameters
[in]faceThe face object.
Returns
enum SUResult SUFaceSetBackMaterial ( SUFaceRef  face,
SUMaterialRef  material 
)
related

Sets the back material of a face object.

Parameters
[in]faceThe face object.
[in]materialThe material object to set. If invalid, this will set the material to the default material.
Returns
enum SUResult SUFaceSetFrontMaterial ( SUFaceRef  face,
SUMaterialRef  material 
)
related

Sets the front material of a face object.

Parameters
[in]faceThe face object.
[in]materialThe material object to set. If invalid, this will set the material to the default material.
Returns
SUDrawingElementRef SUFaceToDrawingElement ( SUFaceRef  face)
related

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

Parameters
[in]faceThe 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]faceThe 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: