SketchUp C API
 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. 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...
 

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]materialThe material created.
Returns
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]entityThe 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 
)
related

Retrieves the color value of a material object.

Parameters
[in]materialThe material object.
[out]colorThe color value retrieved.
Returns
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]materialThe material object.
[out]hueThe Hue delta.
[out]saturationThe Saturation delta.
[out]lightnessThe Lightness delta.
Returns
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]materialThe material object.
[out]typeThe type retrieved.
Returns
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]materialThe material object.
[out]nameThe name retrieved.
Returns
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]materialThe material object.
[out]nameThe name retrieved.
Returns
enum SUResult SUMaterialGetOpacity ( SUMaterialRef  material,
double *  alpha 
)
related

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

Parameters
[in]materialThe material object.
[out]alphaThe alpha value retrieved.
Returns
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]materialThe material object.
[out]typeThe type retrieved.
Returns
enum SUResult SUMaterialGetTexture ( SUMaterialRef  material,
SUTextureRef texture 
)
related

Retrieves the texture of a material object.

Parameters
[in]materialThe material object.
[out]textureThe texture object retrieved.
Returns
enum SUResult SUMaterialGetType ( SUMaterialRef  material,
enum SUMaterialType type 
)
related

Retrieves the type of a material object.

Parameters
[in]materialThe material object.
[out]typeThe type retrieved.
Returns
enum SUResult SUMaterialGetUseOpacity ( SUMaterialRef  material,
bool *  use_opacity 
)
related

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

Parameters
[in]materialThe material object.
[out]use_opacityThe flag retrieved.
Returns
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]materialThe material object.
[out]transparencyThe flag retrieved.
Returns
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]materialThe material to be released.
Returns
enum SUResult SUMaterialSetColor ( SUMaterialRef  material,
const SUColor color 
)
related

Sets the color of a material object.

Parameters
[in]materialThe material object.
[in]colorThe color value to set the material color.
Returns
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]materialThe material object.
[in]typeThe type to set.
Returns
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]materialThe material object.
[in]nameThe name to set the material name. Assumed to be UTF-8 encoded.
Returns
enum SUResult SUMaterialSetOpacity ( SUMaterialRef  material,
double  alpha 
)
related

Sets the alpha value of a material object.

Parameters
[in]materialThe material object.
[in]alphaThe alpha value to set. Must be within range [0.0, 1.0].
Returns
enum SUResult SUMaterialSetTexture ( SUMaterialRef  material,
SUTextureRef  texture 
)
related

Sets the texture of a material object. Materials take ownership of their assigned textures, so textures should not be shared accross different materials.

Parameters
[in]materialThe material object.
[in]textureThe texture object to set the material texture.
Returns
enum SUResult SUMaterialSetType ( SUMaterialRef  material,
enum SUMaterialType  type 
)
related

Sets the type of a material object.

Parameters
[in]materialThe material object.
[in]typeThe type to set.
Returns
enum SUResult SUMaterialSetUseOpacity ( SUMaterialRef  material,
bool  use_opacity 
)
related

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

Parameters
[in]materialThe material object.
[in]use_opacityThe flag boolean value to set.
Returns
SUEntityRef SUMaterialToEntity ( SUMaterialRef  material)
related

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

Parameters
[in]materialThe 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]materialThe material object.
[in]file_pathThe location to save the material to. Assumed to be UTF-8 encoded.
Returns
enum SUResult SUModelLoadMaterial ( SUModelRef  model,
const char *  file_path,
SUMaterialRef material 
)
related

Loads a material from a SKM file.

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

Since
SketchUp 2021.1, API 9.1
Parameters
[in]modelThe model object.
[in]file_pathThe location to load the material from. Assumed to be UTF-8 encoded.
[out]materialThe material object.
Returns

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