SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUMaterialRef Struct Reference

References a material object. More...

`#include <SketchUpAPI/model/material.h>`

Inherits SUEntityRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUMaterialToEntity (SUMaterialRef material)
| Converts from an SUMaterialRef to an SUEntityRef. This is essentially an upcast operation. More...
SUMaterialRef | SUMaterialFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUMaterialRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUMaterialRef. More...
enum SUResult | SUMaterialCreate (SUMaterialRef *material)
| Creates a material. More...
enum SUResult | SUMaterialRelease (SUMaterialRef *material)
| Releases a material and its resources. More...
enum SUResult | SUMaterialSetName (SUMaterialRef material, const char *name)
| Sets the name of a material object. More...
enum SUResult | SUMaterialGetName (SUMaterialRef material, SUStringRef *name)
| Retrieves the internal name of a material object. The internal name is the unprocessed identifier string stored with the material. More...
enum SUResult | SUMaterialGetNameLegacyBehavior (SUMaterialRef material, SUStringRef *name)
| Retrieves the name of a material object. This method was added for users who require the functionality of SUMaterialGetName() prior to SketchUp 2017, API 5.0. If the internal name is encased in square brackets, [], this method will return the name without brackets, otherwise the name will match the name retrieved by SUMaterialGetName. More...
enum SUResult | SUMaterialSetColor (SUMaterialRef material, const SUColor *color)
| Sets the color of a material object. More...
enum SUResult | SUMaterialGetColor (SUMaterialRef material, SUColor *color)
| Retrieves the color value of a material object. More...
enum SUResult | SUMaterialSetTexture (SUMaterialRef material, SUTextureRef texture)
| Sets the texture of a material object. More...
enum SUResult | SUMaterialGetTexture (SUMaterialRef material, SUTextureRef *texture)
| Retrieves the texture of a material object. More...
enum SUResult | SUMaterialGetOpacity (SUMaterialRef material, double *alpha)
| Retrieves the alpha value (0.0 - 1.0) of a material object. More...
enum SUResult | SUMaterialSetOpacity (SUMaterialRef material, double alpha)
| Sets the alpha value of a material object. More...
enum SUResult | SUMaterialGetUseOpacity (SUMaterialRef material, bool *use_opacity)
| Retrieves the flag indicating whether alpha values are used from a material object. More...
enum SUResult | SUMaterialSetUseOpacity (SUMaterialRef material, bool use_opacity)
| Sets the flag indicating whether alpha values are used on a material object. More...
enum SUResult | SUMaterialSetType (SUMaterialRef material, enum SUMaterialType type)
| Sets the type of a material object. More...
enum SUResult | SUMaterialGetType (SUMaterialRef material, enum SUMaterialType *type)
| Retrieves the type of a material object. More...
enum SUResult | SUMaterialIsDrawnTransparent (SUMaterialRef material, bool *transparency)
| Retrieves the flag indicating whether the material is drawn with transparency. More...
enum SUResult | SUMaterialGetOwnerType (SUMaterialRef material, enum SUMaterialOwnerType *type)
| Retrieves the owner type of a material object. More...
enum SUResult | SUMaterialSetColorizeType (SUMaterialRef material, enum SUMaterialColorizeType type)
| Sets the colorization type of a material object. This is used when the material's color is set to a custom value. Call this function after calling SUMaterialSetColor as otherwise the colorize type will be reset. More...
enum SUResult | SUMaterialGetColorizeType (SUMaterialRef material, enum SUMaterialColorizeType *type)
| Retrieves the colorization type of a material object. More...
enum SUResult | SUMaterialGetColorizeDeltas (SUMaterialRef material, double *hue, double *saturation, double *lightness)
| The colorize_deltas method retrieves the HLS deltas for colorized materials. More...
enum SUResult | SUMaterialWriteToFile (SUMaterialRef material, const char *file_path)
| Writes a material to a SKM file. More...
PBR Metallic Roughness Workflow
enum SUResult | SUMaterialGetWorkflow (SUMaterialRef material, enum SUMaterialWorkflow *workflow)
| Queries the workflow type of a material. More...
enum SUResult | SUMaterialSetMetalnessEnabled (SUMaterialRef material, bool enable)
| Enables metalness properties for the material. More...
enum SUResult | SUMaterialIsMetalnessEnabled (SUMaterialRef material, bool *enabled)
| Queries whether metalness properties are enabled for the material. More...
enum SUResult | SUMaterialSetMetallicTexture (SUMaterialRef material, SUTextureRef texture)
| Sets the metallic texture of a PBR material. More...
enum SUResult | SUMaterialGetMetallicTexture (SUMaterialRef material, SUTextureRef *texture)
| Retrieves the metallic texture of a material. More...
enum SUResult | SUMaterialSetMetallicFactor (SUMaterialRef material, double factor)
| Sets the metallic factor of a material. More...
enum SUResult | SUMaterialGetMetallicFactor (SUMaterialRef material, double *factor)
| Retrieves the metallic factor of a material. More...
enum SUResult | SUMaterialSetRoughnessEnabled (SUMaterialRef material, bool enable)
| Enables roughness properties for the material. More...
enum SUResult | SUMaterialIsRoughnessEnabled (SUMaterialRef material, bool *enabled)
| Queries whether roughness properties are enabled for the material. More...
enum SUResult | SUMaterialSetRoughnessTexture (SUMaterialRef material, SUTextureRef texture)
| Sets the roughness texture of a PBR material. More...
enum SUResult | SUMaterialGetRoughnessTexture (SUMaterialRef material, SUTextureRef *texture)
| Retrieves the roughness texture of a material. More...
enum SUResult | SUMaterialSetRoughnessFactor (SUMaterialRef material, double factor)
| Sets the roughness factor of a material. More...
enum SUResult | SUMaterialGetRoughnessFactor (SUMaterialRef material, double *factor)
| Retrieves the roughness factor of a material. More...
enum SUResult | SUMaterialSetNormalEnabled (SUMaterialRef material, bool enable)
| Enables normal map for the material. More...
enum SUResult | SUMaterialIsNormalEnabled (SUMaterialRef material, bool *enabled)
| Queries whether normal mapping is enabled for the material. More...
enum SUResult | SUMaterialSetNormalTexture (SUMaterialRef material, SUTextureRef texture)
| Sets the normal texture of a PBR material. More...
enum SUResult | SUMaterialGetNormalTexture (SUMaterialRef material, SUTextureRef *texture)
| Retrieves the normal texture of a material. More...
enum SUResult | SUMaterialSetNormalScale (SUMaterialRef material, double scale)
| Sets the normal scale of a material. More...
enum SUResult | SUMaterialGetNormalScale (SUMaterialRef material, double *scale)
| Retrieves the normal scale of a material. More...
enum SUResult | SUMaterialSetNormalStyle (SUMaterialRef material, enum SUMaterialNormalMapStyle style)
| Sets the normal mapping style of a material. More...
enum SUResult | SUMaterialGetNormalStyle (SUMaterialRef material, enum SUMaterialNormalMapStyle *style)
| Retrieves the normal mapping style of a material. More...
enum SUResult | SUMaterialSetAOEnabled (SUMaterialRef material, bool enable)
| Enables ambient occlusion map for the material. More...
enum SUResult | SUMaterialIsAOEnabled (SUMaterialRef material, bool *enabled)
| Queries whether ambient occlusion mapping is enabled for the material. More...
enum SUResult | SUMaterialSetAOTexture (SUMaterialRef material, SUTextureRef texture)
| Sets the ambient occlusion texture of a PBR material. More...
enum SUResult | SUMaterialGetAOTexture (SUMaterialRef material, SUTextureRef *texture)
| Retrieves the ambient occlusion texture of a material. More...
enum SUResult | SUMaterialSetAOStrength (SUMaterialRef material, double strength)
| Sets the ambient occlusion strength of a material. More...
enum SUResult | SUMaterialGetAOStrength (SUMaterialRef material, double *strength)
| Retrieves the ambient occlusion strength of a material. 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 material object.

## Friends And Related Function Documentation

enum SUResult SUMaterialCreate | ( | SUMaterialRef * | material | ) |
| related

Creates a material.

If the material is not associated with any face, it must be deallocated with SUMaterialRelease().

Parameters

  [out] | material | The material created.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_OUTPUT if the input parameter is NULL

SUMaterialRef SUMaterialFromEntity | ( | SUEntityRef | entity | ) |
| related

Converts from an SUEntityRef to an SUMaterialRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUMaterialRef.

Parameters

  [in] | entity | The given entity reference.

Returns
  - The converted SUMaterialRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

enum SUResult SUMaterialGetAOStrength | ( | SUMaterialRef | material,
|  | double * | strength
| ) |  |
| related

Retrieves the ambient occlusion strength of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | strength | Occlusion strength returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `strength` is NULL

enum SUResult SUMaterialGetAOTexture | ( | SUMaterialRef | material,
|  | SUTextureRef * | texture
| ) |  |
| related

Retrieves the ambient occlusion texture of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [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.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `texture` is NULL
  - SU_ERROR_NO_DATA if `material` does not have an AO texture

enum SUResult SUMaterialGetColor | ( | SUMaterialRef | material,
|  | SUColor * | color
| ) |  |
| related

Retrieves the color value of a material object.

Parameters

  [in] | material | The material object.
  [out] | color | The color value retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if color is NULL
  - SU_ERROR_NO_DATA if the material object does not have a color value

enum SUResult SUMaterialGetColorizeDeltas | ( | SUMaterialRef | material,
|  | double * | hue,
|  | double * | saturation,
|  | double * | lightness
| ) |  |
| related

The colorize_deltas method retrieves the HLS deltas for colorized materials.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | material | The material object.
  [out] | hue | The Hue delta.
  [out] | saturation | The Saturation delta.
  [out] | lightness | The Lightness delta.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if either hue, saturation or lightness is NULL

enum SUResult SUMaterialGetColorizeType | ( | SUMaterialRef | material,
|  | enum SUMaterialColorizeType * | type
| ) |  |
| related

Retrieves the colorization type of a material object.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | material | The material object.
  [out] | type | The type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if type is NULL

enum SUResult SUMaterialGetMetallicFactor | ( | SUMaterialRef | material,
|  | double * | factor
| ) |  |
| related

Retrieves the metallic factor of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | factor | The factor returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `factor` is NULL

enum SUResult SUMaterialGetMetallicTexture | ( | SUMaterialRef | material,
|  | SUTextureRef * | texture
| ) |  |
| related

Retrieves the metallic texture of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [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.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `texture` is NULL
  - SU_ERROR_NO_DATA if `material` does not have a metalness texture

enum SUResult SUMaterialGetName | ( | SUMaterialRef | material,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the internal name of a material object. The internal name is the unprocessed identifier string stored with the material.

Warning
  Breaking Change: The behavior of this method was changed in SketchUp 2017, API 5.0. In previous releases this method retrieved the material's non-localized display name but it was changed to retrieve the internal name. If the old functionality is required, use SUMaterialGetNameLegacyBehavior.

Parameters

  [in] | material | The material object.
  [out] | name | The name retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
  - SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

enum SUResult SUMaterialGetNameLegacyBehavior | ( | SUMaterialRef | material,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the name of a material object. This method was added for users who require the functionality of SUMaterialGetName() prior to SketchUp 2017, API 5.0. If the internal name is encased in square brackets, [], this method will return the name without brackets, otherwise the name will match the name retrieved by SUMaterialGetName.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | material | The material object.
  [out] | name | The name retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
  - SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

enum SUResult SUMaterialGetNormalScale | ( | SUMaterialRef | material,
|  | double * | scale
| ) |  |
| related

Retrieves the normal scale of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | scale | Normal scale returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `scale` is NULL

enum SUResult SUMaterialGetNormalStyle | ( | SUMaterialRef | material,
|  | enum SUMaterialNormalMapStyle * | style
| ) |  |
| related

Retrieves the normal mapping style of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | style | Normal style returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `style` is NULL

enum SUResult SUMaterialGetNormalTexture | ( | SUMaterialRef | material,
|  | SUTextureRef * | texture
| ) |  |
| related

Retrieves the normal texture of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [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.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `texture` is NULL
  - SU_ERROR_NO_DATA if `material` does not have a normal texture

enum SUResult SUMaterialGetOpacity | ( | SUMaterialRef | material,
|  | double * | alpha
| ) |  |
| related

Retrieves the alpha value (0.0 - 1.0) of a material object.

Parameters

  [in] | material | The material object.
  [out] | alpha | The alpha value retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if alpha is NULL

enum SUResult SUMaterialGetOwnerType | ( | SUMaterialRef | material,
|  | enum SUMaterialOwnerType * | type
| ) |  |
| related

Retrieves the owner type of a material object.

Warning
  Materials owned by SUImageRef and SULayerRef may not be applied to any other entity in the model.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | material | The material object.
  [out] | type | The type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if type is NULL

enum SUResult SUMaterialGetRoughnessFactor | ( | SUMaterialRef | material,
|  | double * | factor
| ) |  |
| related

Retrieves the roughness factor of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | factor | The factor returned.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `factor` is NULL

enum SUResult SUMaterialGetRoughnessTexture | ( | SUMaterialRef | material,
|  | SUTextureRef * | texture
| ) |  |
| related

Retrieves the roughness texture of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [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.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `texture` is NULL
  - SU_ERROR_NO_DATA if `material` does not have a roughness texture

enum SUResult SUMaterialGetTexture | ( | SUMaterialRef | material,
|  | SUTextureRef * | texture
| ) |  |
| related

Retrieves the texture of a material object.

Parameters

  [in] | material | The material object.
  [out] | texture | The texture object retrieved. This texture should not be released via SUTextureRelease() since it is owned by the material.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if texture is NULL
  - SU_ERROR_NO_DATA if the material object does not have a texture

enum SUResult SUMaterialGetType | ( | SUMaterialRef | material,
|  | enum SUMaterialType * | type
| ) |  |
| related

Retrieves the type of a material object.

Parameters

  [in] | material | The material object.
  [out] | type | The type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if type is NULL

enum SUResult SUMaterialGetUseOpacity | ( | SUMaterialRef | material,
|  | bool * | use_opacity
| ) |  |
| related

Retrieves the flag indicating whether alpha values are used from a material object.

Parameters

  [in] | material | The material object.
  [out] | use_opacity | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if use_opacity is NULL

enum SUResult SUMaterialGetWorkflow | ( | SUMaterialRef | material,
|  | enum SUMaterialWorkflow * | workflow
| ) |  |
| related

Queries the workflow type of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | workflow | The returned workflow type.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `workflow` is NULL

enum SUResult SUMaterialIsAOEnabled | ( | SUMaterialRef | material,
|  | bool * | enabled
| ) |  |
| related

Queries whether ambient occlusion mapping is enabled for the material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | enabled | Whether occlusion mapping is enabled or not.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `enabled` is NULL

enum SUResult SUMaterialIsDrawnTransparent | ( | SUMaterialRef | material,
|  | bool * | transparency
| ) |  |
| related

Retrieves the flag indicating whether the material is drawn with transparency.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | material | The material object.
  [out] | transparency | The flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if is_drawn_transparent is NULL

enum SUResult SUMaterialIsMetalnessEnabled | ( | SUMaterialRef | material,
|  | bool * | enabled
| ) |  |
| related

Queries whether metalness properties are enabled for the material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | enabled | Whether metalness is enabled or not.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `enabled` is NULL

enum SUResult SUMaterialIsNormalEnabled | ( | SUMaterialRef | material,
|  | bool * | enabled
| ) |  |
| related

Queries whether normal mapping is enabled for the material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | enabled | Whether normal mapping is enabled or not.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `enabled` is NULL

enum SUResult SUMaterialIsRoughnessEnabled | ( | SUMaterialRef | material,
|  | bool * | enabled
| ) |  |
| related

Queries whether roughness properties are enabled for the material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [out] | enabled | Whether roughness is enabled or not.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `enabled` is NULL

enum SUResult SUMaterialRelease | ( | SUMaterialRef * | material | ) |
| related

Releases a material and its resources.

The material must not be associated with a parent object such as a face.

Parameters

  [in,out] | material | The material to be released.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT material is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if material is NULL

enum SUResult SUMaterialSetAOEnabled | ( | SUMaterialRef | material,
|  | bool | enable
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [in] | enable | Whether to enable or disable.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_ARGUMENT if an ambient occlusion map texture was not set before enabling.

enum SUResult SUMaterialSetAOStrength | ( | SUMaterialRef | material,
|  | double | strength
| ) |  |
| related

Sets the ambient occlusion strength of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [in] | strength | Strength to set. The valid range is [0.0, 1.0].

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `strength` is not within the valid range

enum SUResult SUMaterialSetAOTexture | ( | SUMaterialRef | material,
|  | SUTextureRef | texture
| ) |  |
| related

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

Parameters

  [in] | material | The material object.
  [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. SU_INVALID), then any existing AO texture will be removed from the material, which will effectively disable AO mapping.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `texture` contains invalid occlusion data

enum SUResult SUMaterialSetColor | ( | SUMaterialRef | material,
|  | const SUColor * | color
| ) |  |
| related

Sets the color of a material object.

Parameters

  [in,out] | material | The material object.
  [in] | color | The color value to set the material color.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if color is NULL

enum SUResult SUMaterialSetColorizeType | ( | SUMaterialRef | material,
|  | enum SUMaterialColorizeType | type
| ) |  |
| related

Sets the colorization type of a material object. This is used when the 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

Parameters

  [in,out] | material | The material object.
  [in] | type | The type to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if type is not a valid value

enum SUResult SUMaterialSetMetallicFactor | ( | SUMaterialRef | material,
|  | double | factor
| ) |  |
| related

Sets the metallic factor of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in,out] | material | The material object.
  [in] | factor | Metallic factor to set. The valid range is [0.0, 1.0].

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `factor` is not within the valid range

enum SUResult SUMaterialSetMetallicTexture | ( | SUMaterialRef | material,
|  | SUTextureRef | texture
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [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. SU_INVALID), then any existing metallic texture will be removed from the material.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `texture` contains invalid metalness data

enum SUResult SUMaterialSetMetalnessEnabled | ( | SUMaterialRef | material,
|  | bool | enable
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [in] | enable | Whether to enable or disable.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object

enum SUResult SUMaterialSetName | ( | SUMaterialRef | material,
|  | const char * | name
| ) |  |
| related

Sets the name of a material object.

Warning
  Breaking Change: A new failure mode was added in SketchUp 2018, API 6.0. Returns SU_ERROR_INVALID_ARGUMENT if the material is managed by a model and the provided name was previously associated with a different material in the model.

Parameters

  [in,out] | material | The material object.
  [in] | name | The name to set the material name. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL
  - SU_ERROR_INVALID_ARGUMENT if material is managed and name is not unique

enum SUResult SUMaterialSetNormalEnabled | ( | SUMaterialRef | material,
|  | bool | enable
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [in] | enable | Whether to enable or disable.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_ARGUMENT if a normal map texture was not set before enabling.

enum SUResult SUMaterialSetNormalScale | ( | SUMaterialRef | material,
|  | double | scale
| ) |  |
| related

Sets the normal scale of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [in] | scale | Normal scale to set. Should be >= 0.0

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `scale` is not valid

enum SUResult SUMaterialSetNormalStyle | ( | SUMaterialRef | material,
|  | enum SUMaterialNormalMapStyle | style
| ) |  |
| related

Sets the normal mapping style of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in] | material | The material object.
  [in] | style | Normal style to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object

enum SUResult SUMaterialSetNormalTexture | ( | SUMaterialRef | material,
|  | SUTextureRef | texture
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [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. SU_INVALID), then any existing normal texture will be removed from the material, which will effectively disable normal mapping.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `texture` contains invalid normal data

enum SUResult SUMaterialSetOpacity | ( | SUMaterialRef | material,
|  | double | alpha
| ) |  |
| related

Sets the alpha value of a material object.

Parameters

  [in,out] | material | The material object.
  [in] | alpha | The alpha value to set. Must be within range [0.0, 1.0].

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object
  - SU_ERROR_OUT_OF_RANGE if alpha is not within the acceptable range

enum SUResult SUMaterialSetRoughnessEnabled | ( | SUMaterialRef | material,
|  | bool | enable
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [in] | enable | Whether to enable or disable.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object

enum SUResult SUMaterialSetRoughnessFactor | ( | SUMaterialRef | material,
|  | double | factor
| ) |  |
| related

Sets the roughness factor of a material.

Since
  SketchUp 2025.0, API 13.0

Parameters

  [in,out] | material | The material object.
  [in] | factor | Roughness factor to set. The valid range is [0.0, 1.0].

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `factor` is not within the valid range

enum SUResult SUMaterialSetRoughnessTexture | ( | SUMaterialRef | material,
|  | SUTextureRef | texture
| ) |  |
| related

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

Parameters

  [in,out] | material | The material object.
  [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. SU_INVALID), then any existing metallic texture will be removed from the material.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_ARGUMENT if `texture` contains invalid roughness data

enum SUResult SUMaterialSetTexture | ( | SUMaterialRef | material,
|  | SUTextureRef | texture
| ) |  |
| related

Sets the texture of a material object.

Note
  Materials take ownership of their assigned textures, so textures should not be shared accross different materials.

Parameters

  [in,out] | material | The material object.
  [in] | texture | The texture object to set the material texture.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` or `texture` is not a valid object
  - SU_ERROR_GENERIC if `texture` contains invalid image data

enum SUResult SUMaterialSetType | ( | SUMaterialRef | material,
|  | enum SUMaterialType | type
| ) |  |
| related

Sets the type of a material object.

Parameters

  [in,out] | material | The material object.
  [in] | type | The type to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object

enum SUResult SUMaterialSetUseOpacity | ( | SUMaterialRef | material,
|  | bool | use_opacity
| ) |  |
| related

Sets the flag indicating whether alpha values are used on a material object.

Parameters

  [in,out] | material | The material object.
  [in] | use_opacity | The flag boolean value to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if material is not a valid object

SUEntityRef SUMaterialToEntity | ( | SUMaterialRef | material | ) |
| related

Converts from an SUMaterialRef to an SUEntityRef. This is essentially an upcast operation.

Parameters

  [in] | material | The given material reference.

Returns
  - The converted SUEntityRef if material is a valid object
  - If not, the returned reference will be invalid

enum SUResult SUMaterialWriteToFile | ( | SUMaterialRef | material,
|  | const char * | file_path
| ) |  |
| related

Writes a material to a SKM file.

Since
  SketchUp 2021.1, API 9.1

Parameters

  [in] | material | The material object.
  [in] | file_path | The location to save the material to. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `material` is not a valid object
  - SU_ERROR_INVALID_INPUT if `material` is not attached to a model
  - SU_ERROR_NULL_POINTER_INPUT if `file_path` is NULL
  - SU_ERROR_SERIALIZATION if the serialization operation itself fails

The documentation for this struct was generated from the following files:

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/material.h