Material Manual

About

A Material object represents a Cinema 4D standard material. It is based on BaseMaterial. A standard material offers multiple parameters organized in "channels".

Material objects are an instance of Mmaterial.

Access

A Material is accessed like any other material.

See also BaseMaterial Manual.

Allocation/Deallocation

Material objects are created with the usual tools.

// This example creates, configures and inserts a new standard material.
Material* const material = Material::Alloc();
if (material == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Vector blue { 0.0, 0.0, 1.0 };
material->SetName("Blue Material"_s);
doc->InsertMaterial(material);
void SetName(const maxon::String &name, Bool setDirty=true)
Definition: c4d_baselist.h:2419
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Definition: c4d_basematerial.h:241
static Material * Alloc()
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ConstDescID(...)
Definition: lib_description.h:594
@ MATERIAL_COLOR_COLOR
Definition: mmaterial.h:56
const char * doc
Definition: pyerrors.h:226
Represents a level within a DescID.
Definition: lib_description.h:298

Properties

The parameters of a Material can be edited as usual with C4DAtom::SetParameter() and C4DAtom::GetParameter(). The parameter IDs are defined in mmaterial.h. For convenience the parameters of a group are often combined to a "channel".

Channel States

These utility functions allow to edit the state of a "channel":

// This example reads the state of the color channel of the given material and inverts it.
void SetChannelState(Int32 channel, Bool state)
Definition: c4d_basematerial.h:280
Bool GetChannelState(Int32 channel)
Definition: c4d_basematerial.h:273
maxon::Bool Bool
Definition: ge_sys_math.h:55
#define CHANNEL_COLOR
The color channel of a material.
Definition: c4d_shader.h:95
Definition: grammar.h:37

Channels

Certain parameters and functionality of a parameter group are combined in a BaseChannel object:

The returned BaseChannel object can be used to handle the referenced shaders:

Between the call of InitTexture() and FreeTexture() the shader of the channel can be sampled:

Further operations are:

These functions are useful to get general settings of the channel and the settings of a used bitmap shader:

// This example accesses some material parameters using a BaseChannel object.
// get the BaseChannel
BaseChannel* const channel = material->GetChannel(CHANNEL_COLOR);
if (channel == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// check the shader
BaseShader* const shader = channel->GetShader();
if (shader != nullptr)
ApplicationOutput("Used Shader: " + shader->GetName());
// if the shader is a "Bitmap" shader, access some data
if (shader != nullptr && shader->IsInstanceOf(Xbitmap))
{
const BaseContainer bc = channel->GetData();
}
Definition: c4d_basechannel.h:231
BaseContainer GetData()
BaseShader * GetShader()
Definition: c4d_basecontainer.h:48
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:424
String GetName() const
Definition: c4d_baselist.h:2412
BaseChannel * GetChannel(Int32 id)
Definition: c4d_basematerial.h:92
Definition: c4d_basechannel.h:36
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1437
#define BASECHANNEL_TEXTURE
String. The texture for this channel.
Definition: c4d_shader.h:120
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
#define Xbitmap
Bitmap.
Definition: ge_prepass.h:1313

Reflection Layers

A standard material can manage multiple reflection layers. Such reflection layers can be created and edited. The used parameter IDs are defined in c4d_reflection.h, see REFLECTION_LAYER.

The settings of a ReflectionLayer object are:

Note
If a Material is created and configured in some import context (e.g. SceneLoaderData) one has to set the material parameter REFLECTION_LAYER_IMPORTED to true.
// This example creates and configures a new reflection layer.
// create a new layer
ReflectionLayer* const layer = material->AddReflectionLayer();
if (layer == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int32 layerID = layer->GetDataID();
// configure layer
layer->SetName("Gold Layer"_s);
const DescID fresnelModeID = CreateDescID(DescLevel(layerID + REFLECTION_LAYER_FRESNEL_MODE));
const DescID fresnelMetalID = CreateDescID(DescLevel(layerID + REFLECTION_LAYER_FRESNEL_METAL));
Definition: lib_description.h:355
ReflectionLayer * AddReflectionLayer()
Definition: c4d_basematerial.h:292
Definition: c4d_reflection.h:462
Int32 GetDataID() const
void SetName(const maxon::String &name)
void SetFlags(Int32 flags)
maxon::Int32 Int32
Definition: ge_sys_math.h:60
#define REFLECTION_DISTRIBUTION_BECKMANN
Beckmann.
Definition: c4d_reflection.h:50
#define REFLECTION_FLAG_ACTIVE
Active.
Definition: c4d_reflection.h:24
#define REFLECTION_FLAG_TAB
Tab.
Definition: c4d_reflection.h:25
#define REFLECTION_FLAG_SELECTED
Selected.
Definition: c4d_reflection.h:23
#define REFLECTION_FRESNEL_METAL_GOLD
Gold.
Definition: c4d_reflection.h:191
#define REFLECTION_FRESNEL_CONDUCTOR
Conductor.
Definition: c4d_reflection.h:154
#define REFLECTION_LAYER_FRESNEL_METAL
Int32 Metal preset: REFLECTION_FRESNEL_METAL
Definition: c4d_reflection.h:383
#define REFLECTION_LAYER_FRESNEL_MODE
Int32 Fresnel mode: REFLECTION_FRESNEL
Definition: c4d_reflection.h:381
#define REFLECTION_LAYER_MAIN_DISTRIBUTION
Int32 Distribution type: REFLECTION_DISTRIBUTION
Definition: c4d_reflection.h:288
#define CreateDescID(...)
Definition: lib_description.h:595

and

// This example loops through all layers of the given material.
const Int32 layerCount = material->GetReflectionLayerCount();
for (Int32 i = 0; i < layerCount; ++i)
{
ReflectionLayer* const layer = material->GetReflectionLayerIndex(i);
if (layer == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// print name
ApplicationOutput("Layer: " + layer->GetName());
const Int32 layerID = layer->GetDataID();
GeData data;
// access and print value
material->GetParameter(valueID, data, DESCFLAGS_GET::NONE);
const Float value = data.GetFloat();
// print mode
const DescID blendModeID = CreateDescID(layerID + REFLECTION_LAYER_MAIN_BLEND_MODE);
material->GetParameter(blendModeID, data, DESCFLAGS_GET::NONE);
// check if blend mode is "Normal"
ApplicationOutput("Mode: Normal");
// check if blend mode is "Add"
ApplicationOutput("Mode: Add");
}
Py_ssize_t i
Definition: abstract.h:645
PyObject * value
Definition: abstract.h:715
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags) const
Definition: c4d_gedata.h:83
Int32 GetInt32() const
Definition: c4d_gedata.h:456
Float GetFloat() const
Definition: c4d_gedata.h:468
Int32 GetReflectionLayerCount()
Definition: c4d_basematerial.h:322
ReflectionLayer * GetReflectionLayerIndex(Int32 index)
Definition: c4d_basematerial.h:308
String GetName() const
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:529
maxon::Float Float
Definition: ge_sys_math.h:66
#define REFLECTION_LAYER_MAIN_BLEND_MODE
Int32 Blend mode.
Definition: c4d_reflection.h:292
#define REFLECTION_LAYER_TRANS_BRIGHTNESS
Float Brightness.
Definition: c4d_reflection.h:338
@ MATERIAL_TEXTUREMIXING_ADD
Definition: mmaterial.h:61
@ MATERIAL_TEXTUREMIXING_NORMAL
Definition: mmaterial.h:60

See also Blog post: Cinema 4D R16 Reflectance channel's API

Further Reading