SketchUp C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
face.h File Reference
#include <SketchUpAPI/common.h>
#include <SketchUpAPI/geometry.h>
#include <SketchUpAPI/transformation.h>
#include <SketchUpAPI/model/geometry_input.h>
#include <SketchUpAPI/model/defs.h>

Go to the source code of this file.

Functions

SU_EXPORT SUEntityRef SUFaceToEntity (SUFaceRef face)
 Converts from an SUFaceRef to an SUEntityRef. This is essentially an upcast operation. More...
 
SU_EXPORT 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...
 
SU_EXPORT SUDrawingElementRef SUFaceToDrawingElement (SUFaceRef face)
 Converts from an SUFaceRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
 
SU_EXPORT 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...
 
SU_RESULT SUFaceCreate (SUFaceRef *face, const struct SUPoint3D vertices3d[], SULoopInputRef *outer_loop)
 Creates a face without holes. More...
 
SU_RESULT SUFaceCreateSimple (SUFaceRef *face, const struct SUPoint3D vertices3d[], size_t len)
 Creates a simple face without holes from an array of vertices. More...
 
SU_RESULT SUFaceGetNormal (SUFaceRef face, struct SUVector3D *normal)
 Retrieves the normal vector of a face object. More...
 
SU_RESULT SUFaceRelease (SUFaceRef *face)
 Releases a face object and its associated resources. More...
 
SU_RESULT SUFaceGetNumEdges (SUFaceRef face, size_t *count)
 Retrieves the number of edges in a face. More...
 
SU_RESULT SUFaceGetEdges (SUFaceRef face, size_t len, SUEdgeRef edges[], size_t *count)
 Retrieves the edges in the face. More...
 
SU_RESULT SUFaceGetNumEdgeUses (SUFaceRef face, size_t *count)
 Retrieves the number of edge uses in a face. More...
 
SU_RESULT SUFaceGetEdgeUses (SUFaceRef face, size_t len, SUEdgeUseRef edges[], size_t *count)
 Retrieves the edge uses in the face. More...
 
SU_RESULT SUFaceGetPlane (SUFaceRef face, struct SUPlane3D *plane)
 Retrieves the plane of the face. More...
 
SU_RESULT SUFaceGetNumVertices (SUFaceRef face, size_t *count)
 Retrieves the number of vertices that the face is associated with. More...
 
SU_RESULT SUFaceGetVertices (SUFaceRef face, size_t len, SUVertexRef vertices[], size_t *count)
 Retrieves the vertex objects associated with a face object. More...
 
SU_RESULT SUFaceGetOuterLoop (SUFaceRef face, SULoopRef *loop)
 Retrieves the outer loop of a face object. More...
 
SU_RESULT SUFaceGetNumInnerLoops (SUFaceRef face, size_t *count)
 Retrieves the number of loops in a face. More...
 
SU_RESULT SUFaceGetInnerLoops (SUFaceRef face, size_t len, SULoopRef loops[], size_t *count)
 Retrieves the loops in the face. More...
 
SU_RESULT 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...
 
SU_RESULT SUFaceGetNumOpenings (SUFaceRef face, size_t *count)
 Retrieves the number of openings in a face. More...
 
SU_RESULT 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...
 
SU_RESULT SUFaceGetFrontMaterial (SUFaceRef face, SUMaterialRef *material)
 Retrieves the front material associated with a face object. More...
 
SU_RESULT SUFaceSetFrontMaterial (SUFaceRef face, SUMaterialRef material)
 Sets the front material of a face object. More...
 
SU_RESULT SUFaceGetBackMaterial (SUFaceRef face, SUMaterialRef *material)
 Retrieves the back material associate with a face object. More...
 
SU_RESULT SUFaceSetBackMaterial (SUFaceRef face, SUMaterialRef material)
 Sets the back material of a face object. More...
 
SU_RESULT SUFaceIsFrontMaterialAffine (SUFaceRef face, bool *is_affine)
 Retrieves the flag indicating whether a face object has an affine texture applied to its front. More...
 
SU_RESULT SUFaceIsBackMaterialAffine (SUFaceRef face, bool *is_affine)
 Retrieves the flag indicating whether a face object has an affine texture applied to its back. More...
 
SU_RESULT SUFaceGetArea (SUFaceRef face, double *area)
 Computes the area of the face, taking into account all the inner loops and cuts from openings. More...
 
SU_RESULT SUFaceGetAreaWithTransform (SUFaceRef face, const struct SUTransformation *transform, double *area)
 Computes the area of the face with the provided transformation applied. More...
 
SU_RESULT 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...
 
SU_RESULT SUFaceGetUVHelper (SUFaceRef face, bool front, bool back, SUTextureWriterRef texture_writer, SUUVHelperRef *uv_helper)
 Creates a UV helper for the face. More...
 
SU_RESULT 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...
 
SU_RESULT SUFaceGetNumAttachedDrawingElements (SUFaceRef face, size_t *count)
 Retrieves the number of attached drawing elements in a face. More...
 
SU_RESULT SUFaceGetAttachedDrawingElements (SUFaceRef face, size_t len, SUDrawingElementRef elems[], size_t *count)
 Retrieves the attached drawing elements in the face. More...
 
SU_RESULT SUFaceReverse (SUFaceRef face)
 Reverses a face object. More...
 

Function Documentation

SU_RESULT 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.

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
SU_RESULT SUFaceCreate ( SUFaceRef face,
const struct SUPoint3D  vertices3d[],
SULoopInputRef *  outer_loop 
)

Creates a face without holes.

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
SU_RESULT SUFaceCreateSimple ( SUFaceRef face,
const struct SUPoint3D  vertices3d[],
size_t  len 
)

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

Parameters
[out]faceThe face object created.
[in]vertices3dThe array of vertices of the face.
[in]lenThe length of the array of vertices.
Returns
SU_EXPORT 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.

Parameters
[in]drawing_elemThe given element reference.
Returns
  • The converted SUFaceRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
SU_EXPORT 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.

Parameters
[in]entityThe given entity reference.
Returns
  • The converted SUFaceRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
SU_RESULT SUFaceGetArea ( SUFaceRef  face,
double *  area 
)

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
SU_RESULT SUFaceGetAreaWithTransform ( SUFaceRef  face,
const struct SUTransformation transform,
double *  area 
)

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
SU_RESULT SUFaceGetAttachedDrawingElements ( SUFaceRef  face,
size_t  len,
SUDrawingElementRef  elems[],
size_t *  count 
)

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
SU_RESULT SUFaceGetBackMaterial ( SUFaceRef  face,
SUMaterialRef material 
)

Retrieves the back material associate with a face object.

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

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
SU_RESULT SUFaceGetEdgeUses ( SUFaceRef  face,
size_t  len,
SUEdgeUseRef  edges[],
size_t *  count 
)

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
SU_RESULT SUFaceGetFrontMaterial ( SUFaceRef  face,
SUMaterialRef material 
)

Retrieves the front material associated with a face object.

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

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
SU_RESULT SUFaceGetNormal ( SUFaceRef  face,
struct SUVector3D normal 
)

Retrieves the normal vector of a face object.

Parameters
[in]faceThe face object.
[out]normalThe 3d normal vector retrieved.
Returns
SU_RESULT SUFaceGetNumAttachedDrawingElements ( SUFaceRef  face,
size_t *  count 
)

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
SU_RESULT SUFaceGetNumEdges ( SUFaceRef  face,
size_t *  count 
)

Retrieves the number of edges in a face.

Parameters
[in]faceThe face object.
[out]countThe number of edges.
Returns
SU_RESULT SUFaceGetNumEdgeUses ( SUFaceRef  face,
size_t *  count 
)

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
SU_RESULT SUFaceGetNumInnerLoops ( SUFaceRef  face,
size_t *  count 
)

Retrieves the number of loops in a face.

Parameters
[in]faceThe face object.
[out]countThe number of inner loops.
Returns
SU_RESULT SUFaceGetNumOpenings ( SUFaceRef  face,
size_t *  count 
)

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
SU_RESULT SUFaceGetNumVertices ( SUFaceRef  face,
size_t *  count 
)

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

Parameters
[in]faceThe face object.
[out]countThe number of vertices.
Returns
SU_RESULT 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.

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
SU_RESULT SUFaceGetOuterLoop ( SUFaceRef  face,
SULoopRef loop 
)

Retrieves the outer loop of a face object.

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

Retrieves the plane of the face.

Parameters
[in]faceThe face object.
[out]planeThe 3d plane retrieved.
Returns
SU_RESULT SUFaceGetUVHelper ( SUFaceRef  face,
bool  front,
bool  back,
SUTextureWriterRef  texture_writer,
SUUVHelperRef uv_helper 
)

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
SU_RESULT 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.

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
SU_RESULT SUFaceGetVertices ( SUFaceRef  face,
size_t  len,
SUVertexRef  vertices[],
size_t *  count 
)

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
SU_RESULT SUFaceIsBackMaterialAffine ( SUFaceRef  face,
bool *  is_affine 
)

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
SU_RESULT 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.

Parameters
[in]faceThe face object.
[out]is_complexThe flag retrieved.
Returns
SU_RESULT SUFaceIsFrontMaterialAffine ( SUFaceRef  face,
bool *  is_affine 
)

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
SU_RESULT SUFaceRelease ( SUFaceRef face)

Releases a face object and its associated resources.

Parameters
[in]faceThe face object.
Returns
SU_RESULT SUFaceReverse ( SUFaceRef  face)

Reverses a face object.

Parameters
[in]faceThe face object.
Returns
SU_RESULT SUFaceSetBackMaterial ( SUFaceRef  face,
SUMaterialRef  material 
)

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
SU_RESULT SUFaceSetFrontMaterial ( SUFaceRef  face,
SUMaterialRef  material 
)

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
SU_EXPORT SUDrawingElementRef SUFaceToDrawingElement ( SUFaceRef  face)

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.
SU_EXPORT SUEntityRef SUFaceToEntity ( SUFaceRef  face)

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.