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