Blender V5.0
BKE_material.hh File Reference

General operations, lookup, etc. for materials. More...

#include <optional>

Go to the source code of this file.

Functions

Module
void BKE_materials_init ()
void BKE_materials_exit ()
Materials
void BKE_object_materials_sync_length (Main *bmain, Object *ob, ID *id)
void BKE_objects_materials_sync_length_all (Main *bmain, ID *id)
void BKE_object_material_resize (Main *bmain, Object *ob, short totcol, bool do_id_user)
void BKE_object_material_remap (Object *ob, const unsigned int *remap)
void BKE_object_material_remap_calc (Object *ob_dst, Object *ob_src, short *remap_src_to_dst)
void BKE_object_material_from_eval_data (Main *bmain, Object *ob_orig, const ID *data_eval)
MaterialBKE_material_add (Main *bmain, const char *name)
MaterialBKE_gpencil_material_add (Main *bmain, const char *name)
void BKE_gpencil_material_attr_init (Material *ma)
void BKE_material_make_node_previews_dirty (Material *ma)
RNA API
void BKE_id_materials_copy (Main *bmain, ID *id_src, ID *id_dst)
void BKE_id_material_resize (Main *bmain, ID *id, short totcol, bool do_id_user)
void BKE_id_material_append (Main *bmain, ID *id, Material *ma)
MaterialBKE_id_material_pop (Main *bmain, ID *id, int index)
void BKE_id_material_clear (Main *bmain, ID *id)
Evaluation API
MaterialBKE_object_material_get_eval (Object *ob, short act)
const MaterialBKE_object_material_get_eval (const Object &ob, const ID &data, short act)
int BKE_object_material_count_eval (const Object *ob)
int BKE_object_material_count_eval (const Object &ob, const ID &data)
std::optional< int > BKE_id_material_index_max_eval (const ID &id)
int BKE_id_material_used_eval (const ID &id)
int BKE_id_material_used_with_fallback_eval (const ID &id)
int BKE_object_material_used_with_fallback_eval (const Object &ob)
void BKE_id_material_eval_assign (ID *id, int slot, Material *material)
void BKE_id_material_eval_ensure_default_slot (ID *id)
Rendering
void ramp_blend (int type, float r_col[3], float fac, const float col[3])
Default Materials

TODO: Explain expected usages? Seems to be primarily defined for GPU/viewport code?

Warning
NEVER use these materials as fallback data for regular ID data. They should only be used as template/copy source, or in some very specific, local and short-lived contexts.
MaterialBKE_material_default_empty ()
MaterialBKE_material_default_holdout ()
MaterialBKE_material_default_surface ()
MaterialBKE_material_default_volume ()
MaterialBKE_material_default_gpencil ()
void BKE_material_defaults_free_gpu ()
Dependency graph evaluation
void BKE_material_eval (Depsgraph *depsgraph, Material *material)

Material Slots

enum  { BKE_MAT_ASSIGN_EXISTING , BKE_MAT_ASSIGN_USERPREF , BKE_MAT_ASSIGN_OBDATA , BKE_MAT_ASSIGN_OBJECT }
Material *** BKE_object_material_array_p (Object *ob)
short * BKE_object_material_len_p (Object *ob)
Material *** BKE_id_material_array_p (ID *id)
short * BKE_id_material_len_p (ID *id)
Material ** BKE_object_material_get_p (Object *ob, short act)
MaterialBKE_object_material_get (Object *ob, short act)
void BKE_id_material_assign (Main *bmain, ID *id, Material *ma, short act)
void BKE_object_material_assign (Main *bmain, Object *ob, Material *ma, short act, int assign_type)
void BKE_object_material_assign_single_obdata (Main *bmain, Object *ob, Material *ma, short act)
void BKE_object_material_array_assign (Main *bmain, Object *ob, Material ***matar, int totcol, bool to_object_only)
short BKE_object_material_slot_find_index (Object *ob, Material *ma)
bool BKE_object_material_slot_add (Main *bmain, Object *ob, bool set_active=true)
bool BKE_object_material_slot_remove (Main *bmain, Object *ob)
bool BKE_object_material_slot_used (Object *object, short actcol)
int BKE_object_material_index_get (Object *ob, const Material *ma)
int BKE_object_material_index_get_with_hint (Object *ob, const Material *ma, int hint_index)
int BKE_object_material_ensure (Main *bmain, Object *ob, Material *material)
MaterialBKE_gpencil_material (Object *ob, short act)
MaterialGPencilStyleBKE_gpencil_material_settings (Object *ob, short act)
void BKE_texpaint_slot_refresh_cache (Scene *scene, Material *ma, const Object *ob)
void BKE_texpaint_slots_refresh_object (Scene *scene, Object *ob)
bNodeBKE_texpaint_slot_material_find_node (Material *ma, short texpaint_slot)

Detailed Description

General operations, lookup, etc. for materials.

Definition in file BKE_material.hh.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
BKE_MAT_ASSIGN_EXISTING 
BKE_MAT_ASSIGN_USERPREF 
BKE_MAT_ASSIGN_OBDATA 
BKE_MAT_ASSIGN_OBJECT 

Definition at line 77 of file BKE_material.hh.

Function Documentation

◆ BKE_gpencil_material()

◆ BKE_gpencil_material_add()

Material * BKE_gpencil_material_add ( Main * bmain,
const char * name )

◆ BKE_gpencil_material_attr_init()

◆ BKE_gpencil_material_settings()

◆ BKE_id_material_append()

◆ BKE_id_material_array_p()

◆ BKE_id_material_assign()

◆ BKE_id_material_clear()

◆ BKE_id_material_eval_assign()

◆ BKE_id_material_eval_ensure_default_slot()

◆ BKE_id_material_index_max_eval()

std::optional< int > BKE_id_material_index_max_eval ( const ID & id)

Returns the maximum material index used by the geometry. This returns zero if the geometry is empty or if all material indices are negative.

Definition at line 822 of file blenkernel/intern/material.cc.

References BLI_assert_unreachable, GS, ID_CU_LEGACY, ID_CV, ID_GD_LEGACY, ID_GP, ID_MB, ID_ME, ID_PT, ID_VO, and name.

Referenced by BKE_id_material_used_eval(), and BKE_id_material_used_with_fallback_eval().

◆ BKE_id_material_len_p()

◆ BKE_id_material_pop()

◆ BKE_id_material_resize()

◆ BKE_id_material_used_eval()

int BKE_id_material_used_eval ( const ID & id)

Returns how many material slots the geometry may use (based on the maximum material index).

Definition at line 849 of file blenkernel/intern/material.cc.

References BKE_id_material_index_max_eval().

Referenced by blender::ed::object::copy_materials_to_new_geometry_object().

◆ BKE_id_material_used_with_fallback_eval()

int BKE_id_material_used_with_fallback_eval ( const ID & id)

Gets the number of material slots used by the geometry. The corresponding material for each slot can be retrieved with BKE_object_material_get_eval.

These two functions give the same result when the mesh is provided itself, or an object that uses the mesh.

NOTE: This may be higher or lower than the number of material slots on the object or object-data. However, it is always at least 1 (the fallback).

Definition at line 857 of file blenkernel/intern/material.cc.

References BKE_id_material_index_max_eval().

Referenced by BKE_object_material_used_with_fallback_eval(), blender::draw::mesh_batch_cache_init(), blender::draw::mesh_batch_cache_valid(), blender::draw::pointcloud_batch_cache_init(), and blender::draw::pointcloud_batch_cache_valid().

◆ BKE_id_materials_copy()

◆ BKE_material_add()

◆ BKE_material_default_empty()

Material * BKE_material_default_empty ( )

◆ BKE_material_default_gpencil()

◆ BKE_material_default_holdout()

Material * BKE_material_default_holdout ( )

Definition at line 2152 of file blenkernel/intern/material.cc.

References default_material_holdout.

◆ BKE_material_default_surface()

Material * BKE_material_default_surface ( )

◆ BKE_material_default_volume()

Material * BKE_material_default_volume ( )

◆ BKE_material_defaults_free_gpu()

void BKE_material_defaults_free_gpu ( )

◆ BKE_material_eval()

void BKE_material_eval ( Depsgraph * depsgraph,
Material * material )

◆ BKE_material_make_node_previews_dirty()

void BKE_material_make_node_previews_dirty ( Material * ma)

◆ BKE_materials_exit()

◆ BKE_materials_init()

◆ BKE_object_material_array_assign()

◆ BKE_object_material_array_p()

◆ BKE_object_material_assign()

◆ BKE_object_material_assign_single_obdata()

void BKE_object_material_assign_single_obdata ( Main * bmain,
Object * ob,
Material * ma,
short act )

Similar to BKE_object_material_assign with BKE_MAT_ASSIGN_OBDATA type, but does not scan whole Main for other usages of the same obdata. Only use in cases where you know that the object's obdata is only used by this one object.

Definition at line 1227 of file blenkernel/intern/material.cc.

References BKE_MAT_ASSIGN_OBDATA, and object_material_assign().

Referenced by blender::io::alembic::utils::assign_materials(), and blender::io::usd::utils::assign_materials().

◆ BKE_object_material_count_eval() [1/2]

int BKE_object_material_count_eval ( const Object & ob,
const ID & data )

Same as above but allows using a custom ID as data instead of Object.data.

Definition at line 811 of file blenkernel/intern/material.cc.

References BKE_id_material_len_p(), BLI_assert, data, Object::data, DEG_is_evaluated(), OB_EMPTY, Object::totcol, and Object::type.

◆ BKE_object_material_count_eval() [2/2]

int BKE_object_material_count_eval ( const Object * ob)

Gets the number of material slots on the evaluated object. This is the maximum of the number of material slots on the object and geometry.

Definition at line 799 of file blenkernel/intern/material.cc.

References BKE_id_material_len_p(), BLI_assert, Object::data, DEG_is_evaluated(), get_evaluated_object_data_with_materials(), OB_EMPTY, Object::totcol, and Object::type.

Referenced by BKE_object_material_get_eval(), blender::draw::sculpt_batches_get_ex(), blender::io::hydra::CurvesData::write_materials(), and blender::io::hydra::VolumeData::write_materials().

◆ BKE_object_material_ensure()

◆ BKE_object_material_from_eval_data()

◆ BKE_object_material_get()

Material * BKE_object_material_get ( Object * ob,
short act )

Definition at line 725 of file blenkernel/intern/material.cc.

References BKE_object_material_get_p(), Material::gp_style, OB_GREASE_PENCIL, and Object::type.

Referenced by blender::ed::greasepencil::add_materials_to_map(), animdata_filter_ds_materials(), blender::io::usd::USDCurvesWriter::assign_materials(), blender::ed::greasepencil::bake_grease_pencil_animation_exec(), blender::ed::object::bake_object_check(), BKE_gpencil_material(), BKE_gpencil_material_settings(), BKE_grease_pencil_object_material_ensure_by_name(), BKE_grease_pencil_object_material_ensure_from_brush(), BKE_grease_pencil_object_material_from_brush_get(), BKE_grease_pencil_object_material_index_get_by_name(), BKE_object_material_index_get(), BKE_object_material_index_get_with_hint(), BKE_object_material_remap_calc(), BKE_texpaint_slots_refresh_object(), buttons_context_path_material(), blender::ed::greasepencil::GreasePencilPenToolOperation::can_create_new_curve(), blender::ed::greasepencil::image_render::draw_grease_pencil_strokes(), blender::ed::object::drop_named_material_tooltip(), ED_object_assign_active_image(), ED_object_get_active_image(), ED_object_texture_paint_mode_enter_ex(), ED_paint_proj_mesh_data_check(), blender::ui::greasepencil::eyedropper_add_material(), eyedropper_cryptomatte_sample_view3d_fl(), blender::io::grease_pencil::GreasePencilExporter::foreach_stroke_in_layer(), blender::bke::paint::canvas::get_active_slot(), blender::ed::sculpt_paint::canvas::get_active_slot(), blender::ed::greasepencil::get_boundary_bounds(), blender::ed::space_node::get_context_path_node_shader(), get_default_texture_layer_name_for_object(), blender::ed::greasepencil::get_fill_material_indices(), blender::modifier::greasepencil::get_grease_pencil_material_passes(), blender::ed::greasepencil::get_hidden_material_indices(), blender::ed::greasepencil::get_locked_material_indices(), get_or_create_current_material(), blender::ed::greasepencil::get_visible_boundary_strokes(), blender::ed::greasepencil::grease_pencil_copy_strokes_exec(), blender::ed::sculpt_paint::grease_pencil_fill_invoke(), blender::ed::greasepencil::grease_pencil_material_copy_to_object_exec(), blender::ed::greasepencil::grease_pencil_material_hide_exec(), blender::ed::greasepencil::grease_pencil_material_lock_all_exec(), blender::ed::greasepencil::grease_pencil_material_lock_unselected_exec(), blender::ed::greasepencil::grease_pencil_material_lock_unused_exec(), blender::ed::greasepencil::grease_pencil_material_unlock_all_exec(), imapaint_pick_uv(), CryptomatteSession::init(), Freestyle::BlenderFileLoader::insertShapeNode(), blender::ed::mesh::join_materials(), lineart_load_tri_task(), blender::ed::object::make_links_data_exec(), blender::ed::greasepencil::material_enum_itemf(), material_slot_assign_exec(), material_slot_de_select(), blender::ed::object::mesh_to_grease_pencil_get_material_list(), blender::modify_fill_color(), blender::modify_fill_color(), blender::modify_stroke_color(), blender::modify_stroke_color(), blender::ed::object::object_grease_pencil_add_exec(), blender::ed::object::object_select_all_by_material(), blender::ed::object::object_select_linked_exec(), paint_sample_color(), proj_paint_state_mesh_eval_init(), psys_cache_paths(), psys_get_particle_on_path(), psys_thread_context_init(), shader_get_from_context(), blender::ed::object::single_mat_users(), texture_paint_add_texture_paint_slot_invoke(), and versioning_eevee_shadow_settings().

◆ BKE_object_material_get_eval() [1/2]

const Material * BKE_object_material_get_eval ( const Object & ob,
const ID & data,
short act )

Same as above, but uses the given geometry data instead of ob.data. This is useful for instances. The alternative is to use BKE_object_replace_data_on_shallow_copy which is more hacky.

Definition at line 759 of file blenkernel/intern/material.cc.

References BKE_id_material_array_p(), BKE_id_material_len_p(), BKE_object_material_count_eval(), BLI_assert, clamp_i(), data, DEG_is_evaluated(), Object::mat, Object::matbits, and Object::totcol.

◆ BKE_object_material_get_eval() [2/2]

Material * BKE_object_material_get_eval ( Object * ob,
short act )

On evaluated objects the number of materials on an object and its data might go out of sync. This is because during evaluation materials can be added/removed on the object data.

For rendering or exporting we generally use the materials on the object data. However, some material indices might be overwritten by the object.

Definition at line 753 of file blenkernel/intern/material.cc.

References BKE_object_material_get_eval(), data, and get_evaluated_object_data_with_materials().

Referenced by BKE_object_material_get_eval(), blender::ed::object::copy_materials_to_new_geometry_object(), ED_object_get_active_image(), blender::workbench::Instance::get_material(), lineart_identify_corner_tri_feature_edges(), blender::draw::overlay::Particles::object_sync(), blender::io::obj::OBJMesh::OBJMesh(), blender::io::hydra::CurvesData::write_materials(), blender::io::hydra::MeshData::write_materials(), and blender::io::hydra::VolumeData::write_materials().

◆ BKE_object_material_get_p()

Material ** BKE_object_material_get_p ( Object * ob,
short act )

◆ BKE_object_material_index_get()

◆ BKE_object_material_index_get_with_hint()

int BKE_object_material_index_get_with_hint ( Object * ob,
const Material * ma,
int hint_index )

A version of BKE_object_material_index_get that takes an index to test first.

Parameters
hint_indexWhen this index is in a valid range, test it first. Useful when an active-index is preferred but may not match the material.

Definition at line 920 of file blenkernel/intern/material.cc.

References BKE_object_material_get(), BKE_object_material_index_get(), and BKE_object_material_len_p().

Referenced by material_slot_de_select().

◆ BKE_object_material_len_p()

◆ BKE_object_material_remap()

◆ BKE_object_material_remap_calc()

void BKE_object_material_remap_calc ( Object * ob_dst,
Object * ob_src,
short * remap_src_to_dst )

Calculate a material remapping from ob_src to ob_dst.

Parameters
remap_src_to_dstAn array the size of ob_src->totcol where index values are filled in which map to ob_dst materials.

Definition at line 1262 of file blenkernel/intern/material.cc.

References BKE_object_material_get(), BLI_ghash_free(), BLI_ghash_lookup_p(), BLI_ghash_ptr_new_ex(), BLI_ghash_reinsert(), i, POINTER_AS_INT, POINTER_FROM_INT, and Object::totcol.

Referenced by BMD_mesh_intersection().

◆ BKE_object_material_resize()

◆ BKE_object_material_slot_add()

bool BKE_object_material_slot_add ( Main * bmain,
Object * ob,
bool set_active = true )
Parameters
set_activeSet the newly added slot as active material slot of the object. Usually that is wanted when adding a material slot, so it's the default.

Definition at line 1399 of file blenkernel/intern/material.cc.

References Object::actcol, BKE_MAT_ASSIGN_USERPREF, BKE_object_material_assign(), MAXMAT, and Object::totcol.

Referenced by blender::ed::greasepencil::bake_grease_pencil_animation_exec(), BKE_grease_pencil_object_material_new(), BKE_object_material_ensure(), grease_pencil_object_material_ensure_from_brush_pinned(), material_slot_add_exec(), and new_material_exec().

◆ BKE_object_material_slot_find_index()

short BKE_object_material_slot_find_index ( Object * ob,
Material * ma )

◆ BKE_object_material_slot_remove()

◆ BKE_object_material_slot_used()

◆ BKE_object_material_used_with_fallback_eval()

◆ BKE_object_materials_sync_length()

◆ BKE_objects_materials_sync_length_all()

◆ BKE_texpaint_slot_material_find_node()

◆ BKE_texpaint_slot_refresh_cache()

◆ BKE_texpaint_slots_refresh_object()

◆ ramp_blend()