SketchUp C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Enumerations | Functions
material.h File Reference
#include <SketchUpAPI/color.h>
#include <SketchUpAPI/common.h>
#include <SketchUpAPI/unicodestring.h>
#include <SketchUpAPI/model/defs.h>

Go to the source code of this file.

Enumerations

enum  SUMaterialType { SUMaterialType_Colored = 0, SUMaterialType_Textured, SUMaterialType_ColorizedTexture }
 Indicates material type. More...
 
enum  SUMaterialOwnerType { SUMaterialOwnerType_None = 0, SUMaterialOwnerType_DrawingElement, SUMaterialOwnerType_Image, SUMaterialOwnerType_Layer }
 Indicates material owner type. More...
 
enum  SUMaterialColorizeType { SUMaterialColorizeType_Shift = 0, SUMaterialColorizeType_Tint }
 Indicates material type. More...
 

Functions

SU_EXPORT SUEntityRef SUMaterialToEntity (SUMaterialRef material)
 Converts from an SUMaterialRef to an SUEntityRef. This is essentially an upcast operation. More...
 
SU_EXPORT 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...
 
SU_RESULT SUMaterialCreate (SUMaterialRef *material)
 Creates a material. More...
 
SU_RESULT SUMaterialRelease (SUMaterialRef *material)
 Releases a material and its resources. More...
 
SU_RESULT SUMaterialSetName (SUMaterialRef material, const char *name)
 Sets the name of a material object. More...
 
SU_RESULT 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...
 
SU_RESULT 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...
 
SU_RESULT SUMaterialSetColor (SUMaterialRef material, const SUColor *color)
 Sets the color of a material object. More...
 
SU_RESULT SUMaterialGetColor (SUMaterialRef material, SUColor *color)
 Retrieves the color value of a material object. More...
 
SU_RESULT 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...
 
SU_RESULT SUMaterialGetTexture (SUMaterialRef material, SUTextureRef *texture)
 Retrieves the texture of a material object. More...
 
SU_RESULT SUMaterialGetOpacity (SUMaterialRef material, double *alpha)
 Retrieves the alpha value (0.0 - 1.0) of a material object. More...
 
SU_RESULT SUMaterialSetOpacity (SUMaterialRef material, double alpha)
 Sets the alpha value of a material object. More...
 
SU_RESULT SUMaterialGetUseOpacity (SUMaterialRef material, bool *use_opacity)
 Retrieves the flag indicating whether alpha values are used from a material object. More...
 
SU_RESULT SUMaterialSetUseOpacity (SUMaterialRef material, bool use_opacity)
 Sets the flag indicating whether alpha values are used on a material object. More...
 
SU_RESULT SUMaterialSetType (SUMaterialRef material, enum SUMaterialType type)
 Sets the type of a material object. More...
 
SU_RESULT SUMaterialGetType (SUMaterialRef material, enum SUMaterialType *type)
 Retrieves the type of a material object. More...
 
SU_RESULT SUMaterialIsDrawnTransparent (SUMaterialRef material, bool *transparency)
 Retrieves the flag indicating whether the material is drawn with transparency. More...
 
SU_RESULT SUMaterialGetOwnerType (SUMaterialRef material, enum SUMaterialOwnerType *type)
 Retrieves the owner type of a material object. More...
 
SU_RESULT 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...
 
SU_RESULT SUMaterialGetColorizeType (SUMaterialRef material, enum SUMaterialColorizeType *type)
 Retrieves the colorization type of a material object. More...
 
SU_RESULT SUMaterialGetColorizeDeltas (SUMaterialRef material, double *hue, double *saturation, double *lightness)
 The colorize_deltas method retrieves the HLS deltas for colorized materials. More...
 

Enumeration Type Documentation

Indicates material type.

Since
SketchUp 2019.2, API 7.1
Enumerator
SUMaterialColorizeType_Shift 

Shifts the texture's Hue.

SUMaterialColorizeType_Tint 

Colorize the texture.

Indicates material owner type.

Since
SketchUp 2019.2, API 7.1
Enumerator
SUMaterialOwnerType_None 

Not owned.

SUMaterialOwnerType_DrawingElement 

Can be applied to SUDrawingElements.

SUMaterialOwnerType_Image 

Owned exclusively by an Image.

SUMaterialOwnerType_Layer 

Owned exclusively by a Layer.

Indicates material type.

Enumerator
SUMaterialType_Colored 

Colored material.

SUMaterialType_Textured 

Textured material.

SUMaterialType_ColorizedTexture 

Colored and textured material.

Function Documentation

SU_RESULT SUMaterialCreate ( SUMaterialRef material)

Creates a material.

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

Parameters
[out]materialThe material created.
Returns
SU_EXPORT 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.

Parameters
[in]entityThe given entity reference.
Returns
  • The converted SUMaterialRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
SU_RESULT SUMaterialGetColor ( SUMaterialRef  material,
SUColor color 
)

Retrieves the color value of a material object.

Parameters
[in]materialThe material object.
[out]colorThe color value retrieved.
Returns
SU_RESULT SUMaterialGetColorizeDeltas ( SUMaterialRef  material,
double *  hue,
double *  saturation,
double *  lightness 
)

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
SU_RESULT SUMaterialGetColorizeType ( SUMaterialRef  material,
enum SUMaterialColorizeType type 
)

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

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
SU_RESULT 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]materialThe material object.
[out]nameThe name retrieved.
Returns
SU_RESULT SUMaterialGetOpacity ( SUMaterialRef  material,
double *  alpha 
)

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

Parameters
[in]materialThe material object.
[out]alphaThe alpha value retrieved.
Returns
SU_RESULT SUMaterialGetOwnerType ( SUMaterialRef  material,
enum SUMaterialOwnerType type 
)

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
SU_RESULT SUMaterialGetTexture ( SUMaterialRef  material,
SUTextureRef texture 
)

Retrieves the texture of a material object.

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

Retrieves the type of a material object.

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

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

Parameters
[in]materialThe material object.
[out]use_opacityThe flag retrieved.
Returns
SU_RESULT SUMaterialIsDrawnTransparent ( SUMaterialRef  material,
bool *  transparency 
)

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
SU_RESULT SUMaterialRelease ( SUMaterialRef material)

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
SU_RESULT SUMaterialSetColor ( SUMaterialRef  material,
const SUColor color 
)

Sets the color of a material object.

Parameters
[in]materialThe material object.
[in]colorThe color value to set the material color.
Returns
SU_RESULT 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]materialThe material object.
[in]typeThe type to set.
Returns
SU_RESULT SUMaterialSetName ( SUMaterialRef  material,
const char *  name 
)

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

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

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

Sets the type of a material object.

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

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
SU_EXPORT SUEntityRef SUMaterialToEntity ( SUMaterialRef  material)

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