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.

Allocation/Deallocation

Material objects are created with the usual tools.

Material::Alloc(): Creates a new Material.
Material::Free(): Deletes the given Material.

 // 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->SetParameter(DescID(MATERIAL_COLOR_COLOR), blue, DESCFLAGS_SET::NONE);
 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":

Material::GetChannelState(): Returns the state of the given channel.
Material::SetChannelState(): Sets the state of the given 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:

BaseMaterial::GetChannel(): Returns a BaseChannel object.

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

BaseChannel::InitTexture(): Initializes the channel texture, loading any files required.
BaseChannel::FreeTexture(): Frees all resources used by this channel.

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

BaseChannel::GetBitmap(): Retrieves the channels bitmap texture.
BaseChannel::Sample(): Samples the channel's shader.

Further operations are:

BaseChannel::GetShaderID(): Returns the ID of the channel's shader.
BaseChannel::GetShader(): Returns the channel's shader.
BaseChannel::Compare(): Returns true if the given BaseChannel is identical.

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

BaseChannel::GetData(): Returns a BaseContainer with the settings.
BaseChannel::SetData(): Sets the settings with the values stored in the given BaseContainer.

 // 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();
 ApplicationOutput("Image File: " + bc.GetString(BASECHANNEL_TEXTURE));
 }

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.

Material::AddReflectionLayer(): Creates and returns a new reflection layer.
Material::GetReflectionLayerID(): Returns the reflection layer with the given ID.
Material::GetReflectionLayerIndex(): Returns the reflection layer at the given index.
Material::GetReflectionLayerTrans(): Returns the transparency layer.
Material::GetReflectionLayerCount(): Returns the number of reflection layers.
Material::RemoveReflectionLayerID(): Removes the reflection layer with the given ID.
Material::RemoveReflectionLayerIndex(): Removes the reflection layer at the given index.
Material::RemoveReflectionAllLayers(): Removes all reflection layers.
Material::GetAllReflectionShaders(): Gets an array of all shaders used by reflection layers.
Material::GetReflectionPrimaryLayers(): Gets the indices to the primary reflection and specular layers (can be -1 for empty).

The settings of a ReflectionLayer object are:

ReflectionLayer::GetDataID(): Returns the ID of the reflection layer.
ReflectionLayer::GetName(): Returns the name of the layer.
ReflectionLayer::SetName(): Sets the name of the layer.
ReflectionLayer::GetLayerID(): Returns the ID of the layer.
ReflectionLayer::GetFlags(): Returns the flags of the layer. See REFLECTION_FLAG.
ReflectionLayer::SetFlags() Sets the flags of the layer.

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);
 layer->SetFlags(REFLECTION_FLAG_SELECTED | REFLECTION_FLAG_TAB | REFLECTION_FLAG_ACTIVE);
 
 const Int32 distributionID = layerID + REFLECTION_LAYER_MAIN_DISTRIBUTION;
 material->SetParameter(distributionID, REFLECTION_DISTRIBUTION_BECKMANN, DESCFLAGS_SET::NONE);
 
 const Int32 fresnelModeID = layerID + REFLECTION_LAYER_FRESNEL_MODE;
 material->SetParameter(fresnelModeID, REFLECTION_FRESNEL_CONDUCTOR, DESCFLAGS_SET::NONE);
 
 const Int32 fresnelMetalID = layerID + REFLECTION_LAYER_FRESNEL_METAL;
 material->SetParameter(fresnelMetalID, REFLECTION_FRESNEL_METAL_GOLD, DESCFLAGS_SET::NONE);

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();
 ApplicationOutput("Value: " + String::FloatToString(value));
 
 // print mode
 const DescID blendModeID(layerID + REFLECTION_LAYER_MAIN_BLEND_MODE);
 material->GetParameter(blendModeID, data, DESCFLAGS_GET::NONE);
 
 // check if blend mode is "Normal"
 if (data.GetInt32() == MATERIAL_TEXTUREMIXING_NORMAL)
 ApplicationOutput("Mode: Normal");
 
 // check if blend mode is "Add"
 if (data.GetInt32() == MATERIAL_TEXTUREMIXING_ADD)
 ApplicationOutput("Mode: Add");
 }

Table of Contents