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);

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.
const Bool state = material->GetChannelState(CHANNEL_COLOR);
material->SetChannelState(CHANNEL_COLOR, !state);

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();
}

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 Int32 distributionID = layerID + REFLECTION_LAYER_MAIN_DISTRIBUTION;
const Int32 fresnelModeID = layerID + REFLECTION_LAYER_FRESNEL_MODE;
const Int32 fresnelMetalID = layerID + REFLECTION_LAYER_FRESNEL_METAL;

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
const DescID valueID(layerID + REFLECTION_LAYER_TRANS_BRIGHTNESS);
material->GetParameter(valueID, data, DESCFLAGS_GET::NONE);
const Float value = data.GetFloat();
// print mode
const DescID blendModeID(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");
}

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

Further Reading