scriptup 2026.0.0 → 2026.0.1

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

@@ -1,4 +1,4 @@
-// Copyright 2013 Trimble Inc. All Rights Reserved.
+// Copyright 2012-2024 Trimble Inc. All Rights Reserved.
 
 /**
  * @file
@@ -22,7 +22,6 @@ extern "C" {
 @brief  References a material object.
 */
 
-
 /**
 @enum SUMaterialType
 @brief Indicates material type.
@@ -55,6 +54,26 @@ enum SUMaterialColorizeType {
   SUMaterialColorizeType_Tint,       ///< Colorize the texture
 };
 
+/**
+@enum SUMaterialWorkflow
+@brief Indicates the workflow being used to represent materials
+@since SketchUp 2025.0, API 13.0
+ */
+enum SUMaterialWorkflow {
+  SUMaterialWorkflow_Classic = 0,          ///< Classic material workflow
+  SUMaterialWorkflow_PBRMetallicRoughness  ///< PBR metallic/roughness material workflow
+};
+
+/**
+@enum SUMaterialNormalMapStyle
+@brief Indicates the normal mapping convention used by the material.
+@since SketchUp 2025.0, API 13.0
+*/
+enum SUMaterialNormalMapStyle {
+  SUMaterialNormalMapStyle_OpenGL = 0,  ///< OpenGL style
+  SUMaterialNormalMapStyle_DirectX,     ///< DirectX style
+};
+
 /**
 @brief Converts from an \ref SUMaterialRef to an \ref SUEntityRef.
        This is essentially an upcast operation.
@@ -95,7 +114,7 @@ SU_RESULT SUMaterialCreate(SUMaterialRef* material);
 @brief Releases a material and its resources.
 
 The material must not be associated with a parent object such as a face.
-@param[in] material The material to be released.
+@param[in,out] material The material to be released.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -112,9 +131,9 @@ SU_RESULT SUMaterialRelease(SUMaterialRef* material);
          managed by a model and the provided name was previously associated
          with a different material in the model.
 
-@param[in] material The material object.
-@param[in] name     The name to set the material name. Assumed to be UTF-8
-                    encoded.
+@param[in,out] material The material object.
+@param[in]     name     The name to set the material name. Assumed to be UTF-8
+                        encoded.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -168,8 +187,8 @@ SU_RESULT SUMaterialGetNameLegacyBehavior(SUMaterialRef material, SUStringRef* n
 
 /**
 @brief Sets the color of a material object.
-@param[in] material The material object.
-@param[in] color    The color value to set the material color.
+@param[in,out] material The material object.
+@param[in]     color    The color value to set the material color.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -191,29 +210,29 @@ SU_RESULT SUMaterialSetColor(SUMaterialRef material, const SUColor* color);
 SU_RESULT SUMaterialGetColor(SUMaterialRef material, SUColor* color);
 
 /**
-@brief Sets the texture of a material object. Materials take ownership of their
-       assigned textures, so textures should not be shared accross different
-       materials.
-@param[in] material The material object.
-@param[in] texture  The texture object to set the material texture.
+@brief Sets the texture of a material object.
+@note Materials take ownership of their assigned textures, so textures should not be shared
+      accross different materials.
+@param[in,out] material The material object.
+@param[in]     texture  The texture object to set the material texture.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
-- \ref SU_ERROR_INVALID_INPUT if material or texture is not a valid object
-- \ref SU_ERROR_GENERIC if texture contains invalid image data
+- \ref SU_ERROR_INVALID_INPUT if \p material or \p texture is not a valid object
+- \ref SU_ERROR_GENERIC if \p texture contains invalid image data
 */
 SU_RESULT SUMaterialSetTexture(SUMaterialRef material, SUTextureRef texture);
 
 /**
 @brief Retrieves the texture of a material object.
 @param[in]  material The material object.
-@param[out] texture  The texture object retrieved.
+@param[out] texture  The texture object retrieved. This texture should not be released
+                     via SUTextureRelease() since it is owned by the material.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
 - \ref SU_ERROR_INVALID_INPUT if material is not a valid object
 - \ref SU_ERROR_NULL_POINTER_OUTPUT if texture is NULL
-- \ref SU_ERROR_INVALID_OUTPUT if texture is not a valid object
 - \ref SU_ERROR_NO_DATA if the material object does not have a texture
 */
 SU_RESULT SUMaterialGetTexture(SUMaterialRef material, SUTextureRef* texture);
@@ -232,8 +251,8 @@ SU_RESULT SUMaterialGetOpacity(SUMaterialRef material, double* alpha);
 
 /**
 @brief Sets the alpha value of a material object.
-@param[in] material The material object.
-@param[in] alpha    The alpha value to set. Must be within range [0.0, 1.0].
+@param[in,out] material The material object.
+@param[in]     alpha    The alpha value to set. Must be within range [0.0, 1.0].
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -258,8 +277,8 @@ SU_RESULT SUMaterialGetUseOpacity(SUMaterialRef material, bool* use_opacity);
 /**
 @brief Sets the flag indicating whether alpha values are used on a material
        object.
-@param[in] material    The material object.
-@param[in] use_opacity The flag boolean value to set.
+@param[in,out] material    The material object.
+@param[in]     use_opacity The flag boolean value to set.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -269,8 +288,8 @@ SU_RESULT SUMaterialSetUseOpacity(SUMaterialRef material, bool use_opacity);
 
 /**
 @brief Sets the type of a material object.
-@param[in] material The material object.
-@param[in] type     The type to set.
+@param[in,out] material The material object.
+@param[in]     type     The type to set.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -326,8 +345,8 @@ SU_RESULT SUMaterialGetOwnerType(SUMaterialRef material, enum SUMaterialOwnerTyp
        material's color is set to a custom value. Call this function after
        calling SUMaterialSetColor as otherwise the colorize type will be reset.
 @since SketchUp 2019.2, API 7.1
-@param[in] material The material object.
-@param[in] type     The type to set.
+@param[in,out] material The material object.
+@param[in]     type     The type to set.
 @related SUMaterialRef
 @return
 - \ref SU_ERROR_NONE on success
@@ -366,6 +385,7 @@ SU_RESULT SUMaterialGetColorizeType(SUMaterialRef material, enum SUMaterialColor
 */
 SU_RESULT SUMaterialGetColorizeDeltas(
     SUMaterialRef material, double* hue, double* saturation, double* lightness);
+
 /**
 @brief Writes a material to a SKM file.
 @since SketchUp 2021.1, API 9.1
@@ -382,6 +402,393 @@ SU_RESULT SUMaterialGetColorizeDeltas(
 */
 SU_RESULT SUMaterialWriteToFile(SUMaterialRef material, const char* file_path);
 
+/** @name PBR Metallic Roughness Workflow
+ */
+///@{
+/**
+@brief Queries the workflow type of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] workflow The returned workflow type.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p workflow is NULL
+*/
+SU_RESULT SUMaterialGetWorkflow(SUMaterialRef material, enum SUMaterialWorkflow* workflow);
+
+/**
+@brief Enables metalness properties for the material.
+@note After this is enabled, a metallic texture and/or a metallic factor can be set.
+@since SketchUp 2025.0, API 13.0
+@param[in,out]  material The material object.
+@param[in]      enable   Whether to enable or disable.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+*/
+SU_RESULT SUMaterialSetMetalnessEnabled(SUMaterialRef material, bool enable);
+
+/**
+@brief Queries whether metalness properties are enabled for the material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] enabled  Whether metalness is enabled or not.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p enabled is NULL
+*/
+SU_RESULT SUMaterialIsMetalnessEnabled(SUMaterialRef material, bool* enabled);
+
+/**
+@brief Sets the metallic texture of a PBR material.
+@note Materials take ownership of their assigned textures, so textures should not be shared
+      accross different materials.
+@since SketchUp 2025.0, API 13.0
+@param[in,out] material The material object.
+@param[in]     texture  The texture containing the metalness information. Should be an 8 bit per
+                        pixel (single channel) image. If an invalid texture reference is given (i.e.
+                        \ref SU_INVALID), then any existing metallic texture will be removed from
+                        the material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p texture contains invalid metalness data
+*/
+SU_RESULT SUMaterialSetMetallicTexture(SUMaterialRef material, SUTextureRef texture);
+
+/**
+@brief Retrieves the metallic texture of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] texture  The texture containing the metalness information, if one exists. This texture
+                     should not be released via SUTextureRelease() since it is owned by the
+                     material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p texture is NULL
+- \ref SU_ERROR_NO_DATA if \p material does not have a metalness texture
+*/
+SU_RESULT SUMaterialGetMetallicTexture(SUMaterialRef material, SUTextureRef* texture);
+
+/**
+@brief Sets the metallic factor of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in,out]  material The material object.
+@param[in]      factor   Metallic factor to set. The valid range is [0.0, 1.0].
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p factor is not within the valid range
+*/
+SU_RESULT SUMaterialSetMetallicFactor(SUMaterialRef material, double factor);
+
+/**
+@brief Retrieves the metallic factor of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] factor   The factor returned.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p factor is NULL
+*/
+SU_RESULT SUMaterialGetMetallicFactor(SUMaterialRef material, double* factor);
+
+/**
+@brief Enables roughness properties for the material.
+@note After this is enabled, a roughness texture and/or a roughness factor can be set.
+@since SketchUp 2025.0, API 13.0
+@param[in,out]  material The material object.
+@param[in]      enable   Whether to enable or disable.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+*/
+SU_RESULT SUMaterialSetRoughnessEnabled(SUMaterialRef material, bool enable);
+
+/**
+@brief Queries whether roughness properties are enabled for the material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] enabled  Whether roughness is enabled or not.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p enabled is NULL
+*/
+SU_RESULT SUMaterialIsRoughnessEnabled(SUMaterialRef material, bool* enabled);
+
+/**
+@brief Sets the roughness texture of a PBR material.
+@note Materials take ownership of their assigned textures, so textures should not be shared
+      accross different materials.
+@since SketchUp 2025.0, API 13.0
+@param[in,out] material The material object.
+@param[in]     texture  The texture containing the roughness information. Should be an 8 bit per
+                        pixel (single channel) image. If an invalid texture reference is given (i.e.
+                        \ref SU_INVALID), then any existing metallic texture will be removed from
+                        the material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p texture contains invalid roughness data
+*/
+SU_RESULT SUMaterialSetRoughnessTexture(SUMaterialRef material, SUTextureRef texture);
+
+/**
+@brief Retrieves the roughness texture of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] texture  The texture containing the roughness information, if one exists. This texture
+                     should not be released via SUTextureRelease() since it is owned by the
+                     material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p texture is NULL
+- \ref SU_ERROR_NO_DATA if \p material does not have a roughness texture
+*/
+SU_RESULT SUMaterialGetRoughnessTexture(SUMaterialRef material, SUTextureRef* texture);
+
+/**
+@brief Sets the roughness factor of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in,out]  material The material object.
+@param[in]      factor   Roughness factor to set. The valid range is [0.0, 1.0].
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p factor is not within the valid range
+*/
+SU_RESULT SUMaterialSetRoughnessFactor(SUMaterialRef material, double factor);
+
+/**
+@brief Retrieves the roughness factor of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] factor   The factor returned.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p factor is NULL
+*/
+SU_RESULT SUMaterialGetRoughnessFactor(SUMaterialRef material, double* factor);
+
+/**
+@brief Enables normal map for the material.
+@note  A normal map texture must be set before enabling it.
+@since SketchUp 2025.0.2, API 13.1
+@param[in,out]  material The material object.
+@param[in]      enable   Whether to enable or disable.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_ARGUMENT if a normal map texture was not set before enabling.
+*/
+SU_RESULT SUMaterialSetNormalEnabled(SUMaterialRef material, bool enable);
+
+/**
+@brief Queries whether normal mapping is enabled for the material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] enabled  Whether normal mapping is enabled or not.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p enabled is NULL
+*/
+SU_RESULT SUMaterialIsNormalEnabled(SUMaterialRef material, bool* enabled);
+
+/**
+@brief Sets the normal texture of a PBR material.
+@note Materials take ownership of their assigned textures, so textures should not be shared
+      accross different materials.
+@since SketchUp 2025.0, API 13.0
+@param[in,out] material The material object.
+@param[in]     texture  The texture containing the normal information. Should be an 24 bit per pixel
+                        (3 channel) image. If an invalid texture reference is given (i.e. \ref
+                        SU_INVALID), then any existing normal texture will be removed from the
+                        material, which will effectively disable normal mapping.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p texture contains invalid normal data
+*/
+SU_RESULT SUMaterialSetNormalTexture(SUMaterialRef material, SUTextureRef texture);
+
+/**
+@brief Retrieves the normal texture of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] texture  The texture containing the normal information, if one exists. This texture
+                     should not be released via SUTextureRelease() since it is owned by the
+                     material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p texture is NULL
+- \ref SU_ERROR_NO_DATA if \p material does not have a normal texture
+*/
+SU_RESULT SUMaterialGetNormalTexture(SUMaterialRef material, SUTextureRef* texture);
+
+/**
+@brief Sets the normal scale of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[in]  scale    Normal scale to set. Should be >= 0.0
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p scale is not valid
+*/
+SU_RESULT SUMaterialSetNormalScale(SUMaterialRef material, double scale);
+
+/**
+@brief Retrieves the normal scale of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] scale    Normal scale returned.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p scale is NULL
+*/
+SU_RESULT SUMaterialGetNormalScale(SUMaterialRef material, double* scale);
+
+/**
+@brief Sets the normal mapping style of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[in]  style    Normal style to set.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+*/
+SU_RESULT SUMaterialSetNormalStyle(SUMaterialRef material, enum SUMaterialNormalMapStyle style);
+
+/**
+@brief Retrieves the normal mapping style of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] style    Normal style returned.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p style is NULL
+*/
+SU_RESULT SUMaterialGetNormalStyle(SUMaterialRef material, enum SUMaterialNormalMapStyle* style);
+
+/**
+@brief Enables ambient occlusion map for the material.
+@note  An ambient occlusion map texture must be set before enabling it.
+@since SketchUp 2025.0.2, API 13.1
+@param[in,out]  material The material object.
+@param[in]      enable   Whether to enable or disable.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_ARGUMENT if an ambient occlusion map texture was not set before enabling.
+*/
+SU_RESULT SUMaterialSetAOEnabled(SUMaterialRef material, bool enable);
+
+/**
+@brief Queries whether ambient occlusion mapping is enabled for the material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] enabled  Whether occlusion mapping is enabled or not.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p enabled is NULL
+*/
+SU_RESULT SUMaterialIsAOEnabled(SUMaterialRef material, bool* enabled);
+
+/**
+@brief Sets the ambient occlusion texture of a PBR material.
+@note Materials take ownership of their assigned textures, so textures should not be shared
+      accross different materials.
+@since SketchUp 2025.0, API 13.0
+@param[in] material The material object.
+@param[in] texture  The texture containing the occlusion information. Should be an 8 bit per pixel
+                    (single channel) image. If an invalid texture reference is given (i.e. \ref
+                    SU_INVALID), then any existing AO texture will be removed from the material,
+                    which will effectively disable AO mapping.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p texture contains invalid occlusion data
+*/
+SU_RESULT SUMaterialSetAOTexture(SUMaterialRef material, SUTextureRef texture);
+
+/**
+@brief Retrieves the ambient occlusion texture of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] texture  The texture containing the occlusion information, if one exists. This texture
+                     should not be released via SUTextureRelease() since it is owned by the
+                     material.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p texture is NULL
+- \ref SU_ERROR_NO_DATA if \p material does not have an AO texture
+*/
+SU_RESULT SUMaterialGetAOTexture(SUMaterialRef material, SUTextureRef* texture);
+
+/**
+@brief Sets the ambient occlusion strength of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in] material The material object.
+@param[in] strength Strength to set. The valid range is [0.0, 1.0].
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_INVALID_ARGUMENT if \p strength is not within the valid range
+*/
+SU_RESULT SUMaterialSetAOStrength(SUMaterialRef material, double strength);
+
+/**
+@brief Retrieves the ambient occlusion strength of a material.
+@since SketchUp 2025.0, API 13.0
+@param[in]  material The material object.
+@param[out] strength Occlusion strength returned.
+@related SUMaterialRef
+@return
+- \ref SU_ERROR_NONE on success
+- \ref SU_ERROR_INVALID_INPUT if \p material is not a valid object
+- \ref SU_ERROR_NULL_POINTER_OUTPUT if \p strength is NULL
+*/
+SU_RESULT SUMaterialGetAOStrength(SUMaterialRef material, double* strength);
+
+// End of PBR grouping:
+///@}
 
 #ifdef __cplusplus
 }  // extern "C"