References a material object. More...

#include <SketchUpAPI/model/material.h>

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

enum SUResult	SUMaterialGetHatchPattern (SUMaterialRef material, SUHatchPatternRef *hatch_pattern)
	Retrieves the hatch pattern that fills the section cut of groups and component instances painted with this material. More...

enum SUResult	SUMaterialSetHatchPattern (SUMaterialRef material, SUHatchPatternRef hatch_pattern)
	Sets the hatch pattern that fills the section cut of groups and component instances painted with this material. 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	SUMaterialSetRoughnessTextureInverted (SUMaterialRef material, bool invert)
	Sets the roughness texture inversion flag of a material. More...

enum SUResult	SUMaterialIsRoughnessTextureInverted (SUMaterialRef material, bool *inverted)
	Retrieves the roughness texture inversion flag 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 )

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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 SUMaterialGetHatchPattern	(	SUMaterialRef	material,
		SUHatchPatternRef *	hatch_pattern
	)

The returned hatch pattern is owned by the model and must not be released. A pattern assigned to the group or component instance itself takes precedence over its material's pattern, which in turn takes precedence over the section plane's pattern.

Since: SketchUp 2027.0, API 15.0

Parameters

[in]	material	The material object.
[out]	hatch_pattern	The hatch pattern retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if material is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if hatch_pattern is NULL
SU_ERROR_NO_DATA if material has no hatch pattern assigned

enum SUResult SUMaterialGetMetallicFactor	(	SUMaterialRef	material,
		double *	factor
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 SUMaterialIsRoughnessTextureInverted	(	SUMaterialRef	material,
		bool *	inverted
	)

Since: SketchUp 2026.2, API 14.2

Parameters

[in]	material	The material object.
[out]	inverted	Whether the roughness texture values are inverted.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if material is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if inverted is NULL

enum SUResult SUMaterialRelease ( SUMaterialRef * material )

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
	)

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
	)

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
	)

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
	)

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
	)

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 SUMaterialSetHatchPattern	(	SUMaterialRef	material,
		SUHatchPatternRef	hatch_pattern
	)

hatch_pattern must belong to the same model as material, so it must have been added with SUHatchPatternsAdd() first. Passing an invalid SUHatchPatternRef clears the assignment. Materials that belong to a layer or an image cannot be assigned a hatch pattern, but an existing assignment can still be cleared.

Since: SketchUp 2027.0, API 15.0

Parameters

[in]	material	The material object.
[in]	hatch_pattern	The hatch pattern to assign, or an invalid ref to clear the assignment.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if material is not a valid object
SU_ERROR_INVALID_ARGUMENT if material is not in a model, or if hatch_pattern is valid and material belongs to a layer or an image or hatch_pattern does not belong to material's model

enum SUResult SUMaterialSetMetallicFactor	(	SUMaterialRef	material,
		double	factor
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 SUMaterialSetRoughnessTextureInverted	(	SUMaterialRef	material,
		bool	invert
	)

When enabled, the roughness texture values will be inverted (1.0 - value), effectively converting between roughness and smoothness/glossiness representations.

Since: SketchUp 2026.2, API 14.2

Parameters

[in,out]	material	The material object.
[in]	invert	Whether to invert the roughness texture values.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if material is not a valid object

enum SUResult SUMaterialSetTexture	(	SUMaterialRef	material,
		SUTextureRef	texture
	)

Note: Materials take ownership of their assigned textures, so textures should not be shared across 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
	)

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
	)

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 )

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
	)

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

Related Functions

Detailed Description

Friends And Related Function Documentation