Material(ID)

base classes — bpy_struct, ID

class bpy.types.Material(ID)

Material datablock to define the appearance of geometric objects for rendering

active_node_material

Active node material

Type:Material

active_texture

Active texture slot being displayed

Type:Texture

active_texture_index

Index of active texture slot

Type:int in [0, 17], default 0

alpha

Alpha transparency of the material

Type:float in [0, 1], default 0.0

ambient

Amount of global ambient color the material receives

Type:float in [0, 1], default 0.0

animation_data

Animation data for this datablock

Type:AnimData, (readonly)

darkness

Minnaert darkness

Type:float in [0, 2], default 0.0

diffuse_color

Diffuse color of the material

Type:float array of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

diffuse_fresnel

Power of Fresnel

Type:float in [0, 5], default 0.0

diffuse_fresnel_factor

Blending factor of Fresnel

Type:float in [0, 5], default 0.0

diffuse_intensity

Amount of diffuse reflection

Type:float in [0, 1], default 0.0

diffuse_ramp

Color ramp used to affect diffuse shading

Type:ColorRamp, (readonly)

diffuse_ramp_blend

Blending method of the ramp and the diffuse color

Type:enum in [‘MIX’, ‘ADD’, ‘MULTIPLY’, ‘SUBTRACT’, ‘SCREEN’, ‘DIVIDE’, ‘DIFFERENCE’, ‘DARKEN’, ‘LIGHTEN’, ‘OVERLAY’, ‘DODGE’, ‘BURN’, ‘HUE’, ‘SATURATION’, ‘VALUE’, ‘COLOR’, ‘SOFT_LIGHT’, ‘LINEAR_LIGHT’], default ‘MIX’

diffuse_ramp_factor

Blending factor (also uses alpha in Colorband)

Type:float in [0, 1], default 0.0

diffuse_ramp_input

How the ramp maps on the surface

Type:enum in [‘SHADER’, ‘ENERGY’, ‘NORMAL’, ‘RESULT’], default ‘SHADER’

diffuse_shader

• LAMBERT Lambert, Use a Lambertian shader.
• OREN_NAYAR Oren-Nayar, Use an Oren-Nayar shader.
• TOON Toon, Use a toon shader.
• MINNAERT Minnaert, Use a Minnaert shader.
• FRESNEL Fresnel, Use a Fresnel shader.

Type:enum in [‘LAMBERT’, ‘OREN_NAYAR’, ‘TOON’, ‘MINNAERT’, ‘FRESNEL’], default ‘LAMBERT’

diffuse_toon_size

Size of diffuse toon area

Type:float in [0, 3.14], default 0.0

diffuse_toon_smooth

Smoothness of diffuse toon area

Type:float in [0, 1], default 0.0

emit

Amount of light to emit

Type:float in [0, inf], default 0.0

game_settings

Game material settings

Type:MaterialGameSettings, (readonly, never None)

halo

Halo settings for the material

Type:MaterialHalo, (readonly, never None)

invert_z

Render material’s faces with an inverted Z buffer (scanline only)

Type:boolean, default False

light_group

Limit lighting to lamps in this Group

Type:Group

mirror_color

Mirror color of the material

Type:float array of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

node_tree

Node tree for node based materials

Type:NodeTree, (readonly)

offset_z

Give faces an artificial offset in the Z buffer for Z transparency

Type:float in [-inf, inf], default 0.0

pass_index

Index number for the IndexMA render pass

Type:int in [0, 32767], default 0

physics

Game physics settings

Type:MaterialPhysics, (readonly, never None)

preview_render_type

Type of preview render

• FLAT Flat, Flat XY plane.
• SPHERE Sphere, Sphere.
• CUBE Cube, Cube.
• MONKEY Monkey, Monkey.
• HAIR Hair, Hair strands.
• SPHERE_A World Sphere, Large sphere with sky.

Type:enum in [‘FLAT’, ‘SPHERE’, ‘CUBE’, ‘MONKEY’, ‘HAIR’, ‘SPHERE_A’], default ‘FLAT’

raytrace_mirror

Raytraced reflection settings for the material

Type:MaterialRaytraceMirror, (readonly, never None)

raytrace_transparency

Raytraced transparency settings for the material

Type:MaterialRaytraceTransparency, (readonly, never None)

roughness

Oren-Nayar Roughness

Type:float in [0, 3.14], default 0.0

shadow_buffer_bias

Factor to multiply shadow buffer bias with (0 is ignore)

Type:float in [0, 10], default 0.0

shadow_cast_alpha

Shadow casting alpha, in use for Irregular and Deep shadow buffer

Type:float in [0.001, 1], default 0.0

shadow_only_type

How to draw shadows

• SHADOW_ONLY_OLD Shadow and Distance, Old shadow only method.
• SHADOW_ONLY Shadow Only, Improved shadow only method.
• SHADOW_ONLY_SHADED Shadow and Shading, Improved shadow only method which also renders lightless areas as shadows.

Type:enum in [‘SHADOW_ONLY_OLD’, ‘SHADOW_ONLY’, ‘SHADOW_ONLY_SHADED’], default ‘SHADOW_ONLY_OLD’

shadow_ray_bias

Shadow raytracing bias to prevent terminator problems on shadow boundary

Type:float in [0, 0.25], default 0.0

specular_alpha

Alpha transparency for specular areas

Type:float in [0, 1], default 0.0

specular_color

Specular color of the material

Type:float array of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

specular_hardness

How hard (sharp) the specular reflection is

Type:int in [1, 511], default 0

specular_intensity

How intense (bright) the specular reflection is

Type:float in [0, 1], default 0.0

specular_ior

Specular index of refraction

Type:float in [1, 10], default 0.0

specular_ramp

Color ramp used to affect specular shading

Type:ColorRamp, (readonly)

specular_ramp_blend

Blending method of the ramp and the specular color

Type:enum in [‘MIX’, ‘ADD’, ‘MULTIPLY’, ‘SUBTRACT’, ‘SCREEN’, ‘DIVIDE’, ‘DIFFERENCE’, ‘DARKEN’, ‘LIGHTEN’, ‘OVERLAY’, ‘DODGE’, ‘BURN’, ‘HUE’, ‘SATURATION’, ‘VALUE’, ‘COLOR’, ‘SOFT_LIGHT’, ‘LINEAR_LIGHT’], default ‘MIX’

specular_ramp_factor

Blending factor (also uses alpha in Colorband)

Type:float in [0, 1], default 0.0

specular_ramp_input

How the ramp maps on the surface

Type:enum in [‘SHADER’, ‘ENERGY’, ‘NORMAL’, ‘RESULT’], default ‘SHADER’

specular_shader

• COOKTORR CookTorr, Use a Cook-Torrance shader.
• PHONG Phong, Use a Phong shader.
• BLINN Blinn, Use a Blinn shader.
• TOON Toon, Use a toon shader.
• WARDISO WardIso, Use a Ward anisotropic shader.

Type:enum in [‘COOKTORR’, ‘PHONG’, ‘BLINN’, ‘TOON’, ‘WARDISO’], default ‘COOKTORR’

specular_slope

The standard deviation of surface slope

Type:float in [0, 0.4], default 0.0

specular_toon_size

Size of specular toon area

Type:float in [0, 1.53], default 0.0

specular_toon_smooth

Smoothness of specular toon area

Type:float in [0, 1], default 0.0

strand

Strand settings for the material

Type:MaterialStrand, (readonly, never None)

subsurface_scattering

Subsurface scattering settings for the material

Type:MaterialSubsurfaceScattering, (readonly, never None)

texture_slots

Texture slots defining the mapping and influence of textures

Type:MaterialTextureSlots bpy_prop_collection of MaterialTextureSlot, (readonly)

translucency

Amount of diffuse shading on the back side

Type:float in [0, 1], default 0.0

transparency_method

Method to use for rendering transparency

• MASK Mask, Mask the background.
• Z_TRANSPARENCY Z Transparency, Use alpha buffer for transparent faces.
• RAYTRACE Raytrace, Use raytracing for transparent refraction rendering.

Type:enum in [‘MASK’, ‘Z_TRANSPARENCY’, ‘RAYTRACE’], default ‘MASK’

type

Material type defining how the object is rendered

• SURFACE Surface, Render object as a surface.
• WIRE Wire, Render the edges of faces as wires (not supported in raytracing).
• VOLUME Volume, Render object as a volume.
• HALO Halo, Render object as halo particles.

Type:enum in [‘SURFACE’, ‘WIRE’, ‘VOLUME’, ‘HALO’], default ‘SURFACE’

use_cast_approximate

Allow this material to cast shadows when using approximate ambient occlusion

Type:boolean, default False

use_cast_buffer_shadows

Allow this material to cast shadows from shadow buffer lamps

Type:boolean, default False

use_cast_shadows_only

Make objects with this material appear invisible (not rendered), only casting shadows

Type:boolean, default False

use_cubic

Use cubic interpolation for diffuse values, for smoother transitions

Type:boolean, default False

use_diffuse_ramp

Toggle diffuse ramp operations

Type:boolean, default False

use_face_texture

Replace the object’s base color with color from UV map image textures

Type:boolean, default False

use_face_texture_alpha

Replace the object’s base alpha value with alpha from UV map image textures

Type:boolean, default False

use_full_oversampling

Force this material to render full shading/textures for all anti-aliasing samples

Type:boolean, default False

use_light_group_exclusive

Material uses the light group exclusively - these lamps are excluded from other scene lighting

Type:boolean, default False

use_light_group_local

When linked in, material uses local light group with the same name

Type:boolean, default False

use_mist

Use mist with this material (in world settings)

Type:boolean, default False

use_nodes

Use shader nodes to render the material

Type:boolean, default False

use_object_color

Modulate the result with a per-object color

Type:boolean, default False

use_only_shadow

Render shadows as the material’s alpha value, making the material transparent except for shadowed areas

Type:boolean, default False

use_ray_shadow_bias

Prevent raytraced shadow errors on surfaces with smooth shaded normals (terminator problem)

Type:boolean, default False

use_raytrace

Include this material and geometry that uses it in raytracing calculations

Type:boolean, default False

use_shadeless

Make this material insensitive to light or shadow

Type:boolean, default False

use_shadows

Allow this material to receive shadows

Type:boolean, default False

use_sky

Render this material with zero alpha, with sky background in place (scanline only)

Type:boolean, default False

use_specular_ramp

Toggle specular ramp operations

Type:boolean, default False

use_tangent_shading

Use the material’s tangent vector instead of the normal for shading - for anisotropic shading effects

Type:boolean, default False

use_textures

Enable/Disable each texture

Type:boolean array of 18 items, default (False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False)

use_transparency

Render material as transparent

Type:boolean, default False

use_transparent_shadows

Allow this object to receive transparent shadows cast through other objects

Type:boolean, default False

use_uv_project

Use to ensure UV interpolation is correct for camera projections (use with UV project modifier)

Type:boolean, default False

use_vertex_color_light

Add vertex colors as additional lighting

Type:boolean, default False

use_vertex_color_paint

Replace object base color with vertex colors (multiply with ‘texture face’ face assigned textures)

Type:boolean, default False

volume

Volume settings for the material

Type:MaterialVolume, (readonly, never None)

Inherited Properties

bpy_struct.id_data ID.name ID.users ID.use_fake_user ID.tag

ID.is_updated ID.is_updated_data ID.is_library_indirect ID.library

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.is_property_hidden bpy_struct.is_property_set bpy_struct.items bpy_struct.keyframe_delete bpy_struct.keyframe_insert bpy_struct.keys

bpy_struct.path_from_id bpy_struct.path_resolve bpy_struct.property_unset bpy_struct.type_recast bpy_struct.values ID.copy ID.user_clear ID.animation_data_create ID.animation_data_clear ID.update_tag

References

bpy.context.material BlendData.materials BlendDataMaterials.new BlendDataMaterials.remove Curve.materials DynamicPaintBrushSettings.material IDMaterials.append IDMaterials.pop Material.active_node_material

MaterialSlot.material Mesh.materials MetaBall.materials Object.active_material RenderLayer.material_override SceneRenderLayer.material_override ShaderNodeExtendedMaterial.material ShaderNodeMaterial.material