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. Materials take ownership of their assigned textures, so textures should not be shared accross different materials. 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	SUModelLoadMaterial (SUModelRef model, const char file_path, SUMaterialRef material)
	Loads a material from a SKM file. 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 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 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 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 SUMaterialGetTexture	(	SUMaterialRef	material,
		SUTextureRef *	texture
	)

Parameters

[in]	material	The material object.
[out]	texture	The texture object retrieved.

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_INVALID_OUTPUT if texture is not a valid object
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 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 SUMaterialRelease ( SUMaterialRef * material )

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

Parameters

[in] 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 SUMaterialSetColor	(	SUMaterialRef	material,
		const SUColor *	color
	)

Parameters

[in]	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]	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 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]	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 SUMaterialSetOpacity	(	SUMaterialRef	material,
		double	alpha
	)

Parameters

[in]	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 SUMaterialSetTexture	(	SUMaterialRef	material,
		SUTextureRef	texture
	)

Parameters

[in]	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]	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]	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

enum SUResult SUModelLoadMaterial	(	SUModelRef	model,
		const char *	file_path,
		SUMaterialRef *	material
	)

If a matching material exists in the model it will be returned instead.

Since: SketchUp 2021.1, API 9.1

Parameters

[in]	model	The model object.
[in]	file_path	The location to load the material from. Assumed to be UTF-8 encoded.
[out]	material	The material object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if model is not a valid object
SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
SU_ERROR_OVERWRITE_VALID if material is already a valid object
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
SketchUpAPI/model/model.h

Related Functions

Detailed Description

Friends And Related Function Documentation