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

String::FloatToString
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:529
BaseChannel::GetShader
BaseShader * GetShader(void)
BaseShader
Definition: c4d_basechannel.h:35
Xbitmap
#define Xbitmap
Bitmap.
Definition: ge_prepass.h:1171
MATERIAL_TEXTUREMIXING_ADD
@ MATERIAL_TEXTUREMIXING_ADD
Definition: mmaterial.h:61
ReflectionLayer::GetName
String GetName() const
ReflectionLayer
Definition: c4d_reflection.h:461
BASECHANNEL_TEXTURE
#define BASECHANNEL_TEXTURE
String. The texture for this channel.
Definition: c4d_shader.h:119
DescID
Definition: lib_description.h:328
REFLECTION_FLAG_TAB
#define REFLECTION_FLAG_TAB
Tab.
Definition: c4d_reflection.h:25
ReflectionLayer::GetDataID
Int32 GetDataID() const
REFLECTION_LAYER_FRESNEL_MODE
#define REFLECTION_LAYER_FRESNEL_MODE
Int32 Fresnel mode: REFLECTION_FRESNEL
Definition: c4d_reflection.h:381
REFLECTION_LAYER_TRANS_BRIGHTNESS
#define REFLECTION_LAYER_TRANS_BRIGHTNESS
Float Brightness.
Definition: c4d_reflection.h:338
BaseChannel::GetData
BaseContainer GetData(void)
Float
maxon::Float Float
Definition: ge_sys_math.h:66
REFLECTION_FRESNEL_METAL_GOLD
#define REFLECTION_FRESNEL_METAL_GOLD
Gold.
Definition: c4d_reflection.h:191
MATERIAL_TEXTUREMIXING_NORMAL
@ MATERIAL_TEXTUREMIXING_NORMAL
Definition: mmaterial.h:60
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
REFLECTION_DISTRIBUTION_BECKMANN
#define REFLECTION_DISTRIBUTION_BECKMANN
Beckmann.
Definition: c4d_reflection.h:50
DESCFLAGS_SET::NONE
@ NONE
None.
REFLECTION_LAYER_MAIN_DISTRIBUTION
#define REFLECTION_LAYER_MAIN_DISTRIBUTION
Int32 Distribution type: REFLECTION_DISTRIBUTION
Definition: c4d_reflection.h:288
BaseChannel
Definition: c4d_basechannel.h:237
ReflectionLayer::SetFlags
void SetFlags(Int32 flags)
Material::GetReflectionLayerIndex
ReflectionLayer * GetReflectionLayerIndex(Int32 index)
Definition: c4d_basematerial.h:308
BaseDocument::InsertMaterial
void InsertMaterial(BaseMaterial *mat, BaseMaterial *pred=nullptr, Bool checknames=false)
REFLECTION_FRESNEL_CONDUCTOR
#define REFLECTION_FRESNEL_CONDUCTOR
Conductor.
Definition: c4d_reflection.h:154
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
maxon::Vec3< maxon::Float64, 1 >
Material
Definition: c4d_basematerial.h:240
GeData::GetInt32
Int32 GetInt32(void) const
Definition: c4d_gedata.h:427
Material::Alloc
static Material * Alloc()
REFLECTION_FLAG_SELECTED
#define REFLECTION_FLAG_SELECTED
Selected.
Definition: c4d_reflection.h:23
REFLECTION_LAYER_FRESNEL_METAL
#define REFLECTION_LAYER_FRESNEL_METAL
Int32 Metal preset: REFLECTION_FRESNEL_METAL
Definition: c4d_reflection.h:383
GeData
Definition: c4d_gedata.h:82
BaseList2D::SetName
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2354
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
BaseMaterial::GetChannel
BaseChannel * GetChannel(Int32 id)
Definition: c4d_basematerial.h:92
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
REFLECTION_FLAG_ACTIVE
#define REFLECTION_FLAG_ACTIVE
Active.
Definition: c4d_reflection.h:24
REFLECTION_LAYER_MAIN_BLEND_MODE
#define REFLECTION_LAYER_MAIN_BLEND_MODE
Int32 Blend mode.
Definition: c4d_reflection.h:292
ReflectionLayer::SetName
void SetName(const maxon::String &name)
DESCFLAGS_GET::NONE
@ NONE
None.
BaseContainer::GetString
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:387
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
Material::SetChannelState
void SetChannelState(Int32 channel, Bool state)
Definition: c4d_basematerial.h:280
MATERIAL_COLOR_COLOR
@ MATERIAL_COLOR_COLOR
Definition: mmaterial.h:56
C4DAtom::IsInstanceOf
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1403
Material::AddReflectionLayer
ReflectionLayer * AddReflectionLayer()
Definition: c4d_basematerial.h:292
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
Material::GetReflectionLayerCount
Int32 GetReflectionLayerCount()
Definition: c4d_basematerial.h:322
CHANNEL_COLOR
#define CHANNEL_COLOR
The color channel of a material.
Definition: c4d_shader.h:94
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
BaseContainer
Definition: c4d_basecontainer.h:46
Material::GetChannelState
Bool GetChannelState(Int32 channel)
Definition: c4d_basematerial.h:273
GeData::GetFloat
Float GetFloat(void) const
Definition: c4d_gedata.h:439