scriptup 2026.0.0 → 2026.0.1

data/sketchup-sdk-mac/SketchUpAPI.framework/Versions/A/Headers/model/environment.h

@@ -0,0 +1,382 @@
+// Copyright 2024-2025 Trimble Inc. All Rights Reserved.
+
+/**
+ * @file
+ * @brief Interfaces for SUEnvironmentRef.
+ */
+#ifndef SKETCHUP_MODEL_ENVIRONMENT_H_
+#define SKETCHUP_MODEL_ENVIRONMENT_H_
+
+#include <SketchUpAPI/common.h>
+#include <SketchUpAPI/model/defs.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+@struct SUEnvironmentRef
+@brief References an environment, which enables sky boxes and image-based lighting.
+@since SketchUp 2025.0, API 13.0
+*/
+
+/**
+@brief Converts from an \ref SUEnvironmentRef to an \ref SUEntityRef.
+       This is essentially an upcast operation.
+@since SketchUp 2025.0, API 13.0
+@param[in] environment The given environment reference.
+@related SUEnvironmentRef
+@return
+- The converted \ref SUEntityRef if \p environment is a valid object
+- If not, the returned reference will be invalid
+*/
+SU_EXPORT SUEntityRef SUEnvironmentToEntity(SUEnvironmentRef environment);
+
+/**
+@brief Converts from an \ref SUEntityRef to an SUEnvironmentRef.
+       This is essentially a downcast operation so the given \ref SUEntityRef
+       must be convertible to an \ref SUEnvironmentRef.
+@since SketchUp 2025.0, API 13.0
+@param[in] entity The given entity reference.
+@related SUEnvironmentRef
+@return
+- The converted \ref SUEnvironmentRef if the downcast operation succeeds
+- If not, the returned reference will be invalid
+*/
+SU_EXPORT SUEnvironmentRef SUEnvironmentFromEntity(SUEntityRef entity);
+
+/**
+ * @brief Creates an environment object from an SKE, HDR, or EXR file.
+ *   The image or SKE file will be loaded into the environment's skydome as a cubemap.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[out] environment The created environment object.
+ * @param[in] file_path    The path to the SKE, HDR, or EXR file.
+ * @param[in] name         The name of the environment. If empty, the name will default to the name
+ * stored in the SKE file (if available), or to the file name.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_OVERWRITE_VALID if \p environment already references a valid object
+ * - \ref SU_ERROR_NULL_POINTER_INPUT if \p file_path , \p name , or \p environment is `NULL`
+ * - \ref SU_ERROR_INVALID_ARGUMENT if \p file_path is an empty string
+ * - \ref SU_ERROR_SERIALIZATION if the \p environment could not be created from the file at \p
+ * file_path
+ *
+ */
+SU_RESULT SUEnvironmentCreateFromFile(
+    SUEnvironmentRef* environment, const char* file_path, const char* name);
+
+/**
+ * @brief Writes an environment to an SKE file.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object to write to file.
+ * @param[in] file_path   The location to save the environment to. Assumed to be UTF-8 encoded.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_INPUT if \p file_path , \p name , or \p environment is `NULL`
+ * - \ref SU_ERROR_INVALID_ARGUMENT if \p file_path or \p name is an empty string
+ * - \ref SU_ERROR_SERIALIZATION if the \p environment could not be written to \p file_path
+ *
+ */
+SU_RESULT SUEnvironmentWriteToFile(SUEnvironmentRef environment, const char* file_path);
+
+/**
+@brief Releases an environment object and its associated objects.
+@note An environment object retrieved through \p SUEnvironmentsRef methods should not be released as
+  it is owned by the model.
+@since SketchUp 2025.0, API 13.0
+@param[in,out] environment The environment object.
+@related SUEnvironmentRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_NULL_POINTER_INPUT if \p environment is `NULL`
+- \ref SU_ERROR_INVALID_INPUT if \p environment does not reference a valid object
+*/
+SU_RESULT SUEnvironmentRelease(SUEnvironmentRef* environment);
+
+/**
+@brief Sets the name of a environment object.
+@since SketchUp 2025.0, API 13.0
+@param[in] environment The environment object.
+@param[in] name  The name string to set the environment object.
+                 Assumed to be UTF-8 encoded.
+@related SUEnvironmentRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if \p name is `NULL`
+- \ref SU_ERROR_INVALID_ARGUMENT if \p name is an empty string or if no manager is associated with
+the environment
+- \ref SU_ERROR_DUPLICATE if \p name is a duplicate of another environment
+*/
+SU_RESULT SUEnvironmentSetName(SUEnvironmentRef environment, const char* name);
+
+/**
+@brief Retrieves the name of a environment object.
+@since SketchUp 2025.0, API 13.0
+@param[in]  environment The environment object.
+@param[out] name The name retrieved.
+@related SUEnvironmentRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p name is `NULL`
+- \ref SU_ERROR_INVALID_OUTPUT if \p name does not point to a valid \ref
+  SUStringRef object
+*/
+SU_RESULT SUEnvironmentGetName(SUEnvironmentRef environment, SUStringRef* name);
+
+/**
+@brief Sets the description of a environment object.
+@since SketchUp 2025, API 13.0
+@param[in] environment The environment object.
+@param[in] desc The description to be set.
+Assumed to be UTF-8 encoded.
+@related SUEnvironmentRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+- \ref SU_ERROR_NULL_POINTER_INPUT if \p desc is `NULL`
+*/
+SU_RESULT SUEnvironmentSetDescription(SUEnvironmentRef environment, const char* desc);
+
+/**
+@brief Retrieves the description of a environment object.
+@since SketchUp 2025.0, API 13.0
+@param[in]  environment The environment object.
+@param[out] desc  The description retrieved.
+@related SUEnvironmentRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p desc is `NULL`
+- \ref SU_ERROR_INVALID_OUTPUT if \p desc does not point to a valid \ref SUStringRef object
+*/
+SU_RESULT SUEnvironmentGetDescription(SUEnvironmentRef environment, SUStringRef* desc);
+
+/**
+ * @brief Sets the the environment to be used as a skydome.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] skydome The flag to set on the environment object.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ */
+SU_RESULT SUEnvironmentSetUseAsSkydome(SUEnvironmentRef environment, bool skydome);
+
+/**
+ * @brief Retrieves whether the environment is used as a skydome.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] skydome The flag retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if skydome is `NULL`
+ */
+SU_RESULT SUEnvironmentGetUseAsSkydome(SUEnvironmentRef environment, bool* skydome);
+
+/**
+ * @brief Sets the the environment to be used for reflections.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] reflections The flag to set the environment object.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ */
+SU_RESULT SUEnvironmentSetUseForReflections(SUEnvironmentRef environment, bool reflections);
+
+/**
+ * @brief Retrieves whether the environment is used for reflections.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] reflections The flag retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p reflections is `NULL`
+ */
+SU_RESULT SUEnvironmentGetUseForReflections(SUEnvironmentRef environment, bool* reflections);
+
+/**
+ * @brief Sets the the environment image vertical rotation angle in degrees.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] angle The angle to set the environment object, within the range `[0.0, 360.0)`
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_OUT_OF_RANGE if \p angle is not within the range `[0.0, 360.0)`
+ */
+SU_RESULT SUEnvironmentSetRotation(SUEnvironmentRef environment, double angle);
+
+/**
+ * @brief Retrieves the environment image rotation in degrees.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] angle The angle retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p angle is `NULL`
+ */
+SU_RESULT SUEnvironmentGetRotation(SUEnvironmentRef environment, double* angle);
+
+/**
+ * @brief Sets the skydome exposure to compensate for variations in HDR image exposure.
+ *   The unaltered exposure level is `1.0`.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] exposure The exposure to set the environment object, within the range [0.0, 20.0].
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_OUT_OF_RANGE if \p exposure is not within the range [0.0, 20.0]
+ */
+SU_RESULT SUEnvironmentSetSkydomeExposure(SUEnvironmentRef environment, double exposure);
+
+/**
+ * @brief Retrieves the skydome exposure of the environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] exposure The exposure retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p exposure is `NULL`
+ */
+SU_RESULT SUEnvironmentGetSkydomeExposure(SUEnvironmentRef environment, double* exposure);
+
+/**
+ * @brief Sets the reflection exposure of the environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] exposure The exposure to set the environment object, within the range [0.0, 10.0].
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_OUT_OF_RANGE if \p exposure is not within the range [0.0, 10.0]
+ */
+SU_RESULT SUEnvironmentSetReflectionExposure(SUEnvironmentRef environment, double exposure);
+
+/**
+ * @brief Retrieves the reflection exposure of the environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] exposure The exposure retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p exposure is `NULL`
+ */
+SU_RESULT SUEnvironmentGetReflectionExposure(SUEnvironmentRef environment, double* exposure);
+
+/**
+ * @brief Sets the linked sun flag of the environment, enabling the shadow-casting light.
+ *   Corresponding to "Set Sun Location" in the SketchUp UI.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] linked_sun The flag to set the environment object.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ */
+SU_RESULT SUEnvironmentSetLinkedSun(SUEnvironmentRef environment, bool linked_sun);
+
+/**
+ * @brief Retrieves whether the environment is linked sun is enabled.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] linked_sun The flag retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p linked_sun is `NULL`
+ */
+SU_RESULT SUEnvironmentGetLinkedSun(SUEnvironmentRef environment, bool* linked_sun);
+
+/**
+ * @brief Sets the linked sun position in the environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] position The position to set the environment object.
+ *   `x` corresponds to longitude with the range `[0.0, 1.0]`,
+ *   `y` corresponds to latitude with the range `[-1.0, 1.0]`.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_INPUT if \p position is `NULL`
+ * - \ref SU_ERROR_OUT_OF_RANGE if \p position has invalid x or y values
+ */
+SU_RESULT SUEnvironmentSetLinkedSunPosition(
+    SUEnvironmentRef environment, const struct SUPoint2D* position);
+
+/**
+ * @brief Retrieves the linked sun position in the environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] position The position retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p position is `NULL`
+ */
+SU_RESULT SUEnvironmentGetLinkedSunPosition(
+    SUEnvironmentRef environment, struct SUPoint2D* position);
+
+/**
+ * @brief Retrieves the thumbnail preview image for the given environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environment The environment object.
+ * @param[out] image The thumbnail to be retrieved.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p image is NULL
+ * - \ref SU_ERROR_INVALID_OUTPUT if \p image does not point to a valid \ref
+       SUImageRepRef object
+ * - \ref SU_ERROR_NO_DATA if the thumbnail can not be retrieved
+ */
+SU_RESULT SUEnvironmentGetThumbnail(SUEnvironmentRef environment, SUImageRepRef* image);
+
+/**
+ * @brief Writes the HDR image of the environment to a file in its original file type.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environment The environment object.
+ * @param[in] dir_path The directory path to save the HDR image to.
+ * @param[out] full_path_written The full path of the written file.
+ * @related SUEnvironmentRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_INPUT if \p dir_path or \p full_path_written is `NULL`
+ * - \ref SU_ERROR_INVALID_ARGUMENT if \p dir_path is an empty string
+ * - \ref SU_ERROR_SERIALIZATION if the HDR image could not be written to \p dir_path
+ */
+SU_RESULT SUEnvironmentWriteHDRImageToFile(
+    SUEnvironmentRef environment, const char* dir_path, SUStringRef* full_path_written);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // SKETCHUP_MODEL_ENVIRONMENT_H_

data/sketchup-sdk-mac/SketchUpAPI.framework/Versions/A/Headers/model/environments.h

@@ -0,0 +1,133 @@
+// Copyright 2024-2025 Trimble Inc. All Rights Reserved.
+
+/**
+ * @file
+ * @brief Interfaces for SUEnvironmentsRef.
+ */
+#ifndef SKETCHUP_MODEL_ENVIRONMENTS_H_
+#define SKETCHUP_MODEL_ENVIRONMENTS_H_
+
+#include <SketchUpAPI/common.h>
+#include <SketchUpAPI/model/defs.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+@struct SUEnvironmentsRef
+@brief References a container object for all environments in a model.
+@since SketchUp 2025.0, API 13.0
+*/
+
+/**
+ * @brief Retrieves the number of environment objects in an environments object.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environments The environments object.
+ * @param[out] count        The number of environments.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environments is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p count is `NULL`
+ */
+SU_RESULT SUEnvironmentsGetCount(SUEnvironmentsRef environments, size_t* count);
+
+/**
+ * @brief Retrieves every environment associated with an environments object.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environments The environments object.
+ * @param[in]  len          The number of environments to retrieve.
+ * @param[out] items        The environments retrieved.
+ * @param[out] count        The number of environments retrieved.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environments is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p items or \p count is `NULL`
+ */
+SU_RESULT SUEnvironmentsGetAll(
+    SUEnvironmentsRef environments, size_t len, SUEnvironmentRef items[], size_t* count);
+
+/**
+ * @brief Retrieves the currently selected environment.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environments The environments object.
+ * @param[out] environment  The selected environment object.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environments is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p environment is `NULL`
+ * - \ref SU_ERROR_NO_DATA if no environment is currently selected
+ */
+SU_RESULT SUEnvironmentsGetSelectedEnvironment(
+    SUEnvironmentsRef environments, SUEnvironmentRef* environment);
+
+/**
+ * @brief Retrieves an environment by persistent ID.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environments The environments object.
+ * @param[in]  pid          The PID of the environment object to retrieve.
+ * @param[out] environment  The environment object with the given PID.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environments is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p environment is `NULL`
+ * - \ref SU_ERROR_NO_DATA if no environment can be found with the given PID
+ */
+SU_RESULT SUEnvironmentsGetEnvironmentByPersistentID(
+    SUEnvironmentsRef environments, uint64_t pid, SUEnvironmentRef* environment);
+
+/**
+ * @brief Retrieves an environment by name.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in]  environments The environments object.
+ * @param[in]  name         The name of the environment object to retrieve.
+ * @param[out] environment  The environment object with the given name.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environments is not a valid object
+ * - \ref SU_ERROR_NULL_POINTER_OUTPUT if \p environment is `NULL`
+ * - \ref SU_ERROR_NO_DATA if no environment can be found with the given name
+ */
+SU_RESULT SUEnvironmentsGetEnvironmentByName(
+    SUEnvironmentsRef environments, const char* name, SUEnvironmentRef* environment);
+
+/**
+ * @brief Adds an environment to an environments object.
+ * @note This method transfers ownership of the \p environment to the model. Do not call
+ *   \p SUEnvironmentRelease on \p environment after calling this method.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environments The environments object.
+ * @param[in] environment  The environment object to add.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment or \p environments is not a valid object
+ * - \ref SU_ERROR_DUPLICATE if the \p environment is already part of the environments
+ *        object
+ * - \ref SU_ERROR_INVALID_ARGUMENT if the environment name is already in use
+ */
+SU_RESULT SUEnvironmentsAdd(SUEnvironmentsRef environments, SUEnvironmentRef environment);
+
+/**
+ * @brief Removes an environment from an environments object.
+ * @since SketchUp 2025.0, API 13.0
+ * @param[in] environments The environments object.
+ * @param[in] environment  The environment object to remove.
+ * @related SUEnvironmentsRef
+ * @return
+ * - \ref SU_ERROR_NONE on success
+ * - \ref SU_ERROR_INVALID_INPUT if \p environment or \p environments is not a valid object
+ * - \ref SU_ERROR_INVALID_OPERATION if \p environment is not part of the \p environments object
+ */
+SU_RESULT SUEnvironmentsRemove(SUEnvironmentsRef environments, SUEnvironmentRef environment);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // SKETCHUP_SLAPI_PUBLIC_MODEL_ENVIRONMENTS_H_

data/sketchup-sdk-mac/SketchUpAPI.framework/Versions/A/Headers/model/face.h

@@ -78,12 +78,12 @@ SU_EXPORT SUFaceRef SUFaceFromDrawingElement(SUDrawingElementRef drawing_elem);
   produces SketchUp models with unexpected state. Avoid using these functions
   and instead use SUGeometryInputRef along with SUEntitiesFill().
 
-@param[out] face       The face object created.
-@param[in]  vertices3d The array of vertices that make the face.
-@param[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.
+@param[out]     face       The face object created.
+@param[in]      vertices3d The array of vertices that make the face.
+@param[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.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -132,7 +132,7 @@ SU_RESULT SUFaceGetNormal(SUFaceRef face, struct SUVector3D* normal);
 
 /**
 @brief Releases a face object and its associated resources.
-@param[in] face The face object.
+@param[in,out] face The face object.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -275,12 +275,12 @@ SU_RESULT SUFaceGetInnerLoops(SUFaceRef face, size_t len, SULoopRef loops[], siz
 /**
 @brief Adds a hole to the face. The face object must be associated with a parent
        component.
-@param[in] face       The face object.
-@param[in] vertices3d The array of vertices references by the added loop.
-@param[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.
+@param[in,out] face       The face object.
+@param[in]     vertices3d The array of vertices references by the added loop.
+@param[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.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -334,9 +334,9 @@ SU_RESULT SUFaceGetFrontMaterial(SUFaceRef face, SUMaterialRef* material);
 
 /**
 @brief Sets the front material of a face object.
-@param[in] face     The face object.
-@param[in] material The material object to set. If invalid, this will set the
-                    material to the default material.
+@param[in,out] face     The face object.
+@param[in]     material The material object to set. If invalid, this will set the
+                        material to the default material.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -360,9 +360,9 @@ SU_RESULT SUFaceGetBackMaterial(SUFaceRef face, SUMaterialRef* material);
 
 /**
 @brief Sets the back material of a face object.
-@param[in] face     The face object.
-@param[in] material The material object to set. If invalid, this will set the
-                    material to the default material.
+@param[in,out] face     The face object.
+@param[in]     material The material object to set. If invalid, this will set the
+                        material to the default material.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -519,7 +519,7 @@ SU_RESULT SUFaceGetAttachedDrawingElements(
 /**
 @brief Reverses a face object.
 @since SketchUp 2016, API 4.0
-@param[in] face The face object.
+@param[in,out] face The face object.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -590,8 +590,8 @@ This is similar to reseting the texture position from the SketchUp UI face conte
 
 @since SketchUp 2022.0, API 10.0
 
-@param[in] face
-@param[in] front  Flag indicating whether to clear the front or back side of the face.
+@param[in,out] face
+@param[in]     front  Flag indicating whether to clear the front or back side of the face.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success.
@@ -646,8 +646,8 @@ This is similar to toggling off Projection from the Position Texture tool in the
 
 @since SketchUp 2021.1, API 9.1
 
-@param[in]  face
-@param[in] front  Flag indicating whether to clear the front or back side of the face.
+@param[in,out]  face
+@param[in]      front  Flag indicating whether to clear the front or back side of the face.
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success.
@@ -664,9 +664,9 @@ textures are positioned in the UI using the Position Texture tool.
 
 @since SketchUp 2021.1, API 9.1
 
-@param[in] face
-@param[in] front  Flag indicating whether to use the front or back side of the face.
-@param[in] mapping
+@param[in,out] face
+@param[in]     front  Flag indicating whether to use the front or back side of the face.
+@param[in]     mapping
 @related SUFaceRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -679,6 +679,22 @@ textures are positioned in the UI using the Position Texture tool.
 SU_RESULT SUFacePositionMaterial(
     SUFaceRef face, bool front, struct SUMaterialPositionInput* mapping);
 
+/**
+@brief Retrieves a flag indicating whether \p face is coplanar with \p other_face.
+
+@since SketchUp 2025.0, API 13.0
+
+@param[in]  face        The \p face object.
+@param[in]  other_face  The \p other_face object.
+@param[out] is_coplanar The flag retrieved.
+@related SUFaceRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p face or \p other_face is not a valid face object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p is_coplanar is NULL
+*/
+SU_RESULT SUFaceCoplanarWith(SUFaceRef face, SUFaceRef other_face, bool* is_coplanar);
+
 #ifdef __cplusplus
 }  //  extern "C" {
 #endif