About

BaseMaterial is the base class for all materials in Cinema 4D. Materials are typically assigned to a BaseObject using a TextureTag. They can be configured like any other BaseList2D based entity. Materials often own BaseShader elements. The most often used material is the standard material (Material class).

BaseMaterial objects are an instance of Mbase.

Access

Materials are stored in a BaseDocument. They can be accessed with:

BaseDocument::GetFirstMaterial(): Returns the first BaseMaterial in the list.
BaseDocument::SearchMaterial(): Searches for a BaseMaterial with the given name.
BaseDocument::GetActiveMaterial(): Returns the currently selected BaseMaterial.
BaseDocument::GetActiveMaterials(): Returns the current multi-selection of BaseMaterial objects.
BaseDocument::SetActiveMaterial(): Adds or removes the given BaseMaterial to the selection or starts a new selection.

See BaseDocument Materials

A TextureTag stores a reference to a material. This referenced material is accessed with:

TextureTag::GetMaterial(): Returns the referenced material.

  // This example accesses the texture tag on the given BaseObject.
  // The texture tag returns the linked material.
 
  TextureTag* const ttag = static_cast<TextureTag*>(object->GetTag(Ttexture));
  if (ttag == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  BaseMaterial* const material = ttag->GetMaterial();
  if (material != nullptr)
  {
    ApplicationOutput("Used Material: " + material->GetName());
  }

See TextureTag Manual.

Allocation/Deallocation

BaseMaterial objects are created with the usual tools.

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

A newly created material is typically added to a BaseDocument that takes ownership:

BaseDocument::InsertMaterial(): Inserts a BaseMaterial into the list.

A material is assigned to a BaseObject using a TextureTag. The referenced material is set with:

TextureTag::SetMaterial(): Sets the referenced material.

  // This example creates a new "Cheen" material and assigns it
  // to the given object with a new TextureTag.
 
  // make new material
  AutoAlloc<BaseMaterial> cheen { Mcheen };
 
  // make TextureTag
  AutoAlloc<TextureTag> textureTag;
 
  // check if the "Cheen" material and the
  // "Texture" tag could be allocated
  const Bool noCheen = cheen == nullptr;
  const Bool noTextureTag = textureTag == nullptr;
  if (noCheen || noTextureTag)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // assign material
  textureTag->SetMaterial(cheen);
 
  // insert material and tag
  doc->InsertMaterial(cheen.Release(), nullptr);
  object->InsertTag(textureTag.Release());

Navigation

The BaseMaterial elements of a BaseDocument are stored in a list:

BaseMaterial::GetNext(): Returns the previous BaseMaterial in the list.
BaseMaterial::GetPred(): Returns the next BaseMaterial in the list.

  // This example loops through all materials of the given BaseDocument.
 
  BaseMaterial* material = doc->GetFirstMaterial();
 
  while (material != nullptr)
  {
    ApplicationOutput("Material: " + material->GetName());
 
    material = material->GetNext();
  }

Read-Only Properties

The following functions allow to access various properties of a BaseMaterial.

BaseMaterial::GetChannel(): Returns a BaseChannel object. This is only useful if the material in question is a standard Material.
BaseMaterial::GetPreview(): Returns the material preview image.
BaseMaterial::GetAverageColor(): Returns the average color. For standard materials this is mostly based on the color parameter. For other materials it is based on the viewport preview image.
BaseMaterial::GetRenderInfo(): Returns information about what the material requires from the raytracer and what it will return.
BaseMaterial::HasEditorTransparency(): Returns true if the material supports viewport transparency.

  // This example accesses the material preview bitmap and shows it in the Picture Viewer.
 
  BaseBitmap* const preview = material->GetPreview(0);
 
  ShowBitmap(preview);

Update

In certain situations it is needed to manually trigger an update of the material previews. This may be for example needed in a custom material plugin.

BaseMaterial::Update(): Recalculates the material's thumbnail and viewport preview.

Sample Material

Materials define the surface properties of objects. They are sampled in the rendering pipeline e.g. in a VideoPost, another material or a shader.

Internal material resources are initiated and freed with these functions:

BaseMaterial::InitTextures(): Initializes the material textures, loading any files required.
BaseMaterial::UnlockTextures(): Unlocks all textures used by the material.

If needed the material calculation is initiated with:

BaseMaterial::InitCalculation(): Must be called before any calculations if VOLUMEINFO::INITCALCULATION is set.

The material can now be sampled and used with:

BaseMaterial::Displace(): Calls the displacement routine of a material.
BaseMaterial::ChangeNormal(): Calls the bump routine of a material.
BaseMaterial::CalcSurface(): Computes the surface properties of the material.
BaseMaterial::CalcTransparency(): Computes the transparency properties of the material.
BaseMaterial::CalcAlpha(): Computes the alpha properties of the material.
BaseMaterial::CalcVolumetric(): Computes the color of a volumetric ray in the material.

These examples sample a BaseMaterial in a VideoPostData plugin:

          // This example prepares the material for usage within the rendering pipeline.
 
          VolumeData* const volumeData = vps->vd;
 
          // init material
 
          InitRenderStruct irs(vps->doc);
          irs.vd = volumeData;
 
          // if VOLUMEINFO_INITCALCULATION is set, call InitCalculation()
          if (material->GetRenderInfo() & VOLUMEINFO::INITCALCULATION)
            material->InitCalculation(volumeData, INITCALCULATION::SURFACE);
 
          // init
          const INITRENDERRESULT res = material->InitTextures(irs);
          if (res != INITRENDERRESULT::OK)
            return RENDERRESULT::OUTOFMEMORY;

                  // prepare VolumeData
 
                  volumeData->ray = &ray;
                  volumeData->n = si.n;
                  volumeData->p = si.p;
                  volumeData->tex = texData;
                  volumeData->calc_illum = 0;
                  volumeData->uvw = uvw;
 
                  // sample the material surface color
                  material->CalcSurface(volumeData);
 
                  // get result color
                  const Vector surfaceColor = volumeData->col;
 

          // This example unlocks a material after it has been
          // used in the rendering pipeline.
 
          // free material
          material->UnlockTextures();

Compare Entity

Two BaseMaterial elements can be compared with:

BaseMaterial::Compare(): Returns true if the materials are identical.

  // This example compares the given material with the first material of the document.
 
  BaseMaterial* firstMaterial = doc->GetFirstMaterial();
  if (firstMaterial == nullptr)
    return maxon::OK;
 
  // compare the selected material with the first material
  if (selectedMaterial->Compare(firstMaterial))
    ApplicationOutput("The selected material has the same settings as the first material");

Note: The comparison is mostly based on the material's BaseContainer. Other internal data may not be compared.

Bits

If an element is copied it must mark the materials it uses so that these materials are copied along with the actual element.

BIT_MATMARK: This bit defines the material as a "marked" material.

      // This example reacts to MSG_MULTI_MARKMATERIALS in an ObjectData::Message() function
      // and marks a linked BaseMaterial.
 
      case MSG_MULTI_MARKMATERIALS:
      {
        BaseDocument* const doc = node->GetDocument();
        if (doc == nullptr)
          return false;
 
        // get referenced material
        GeData geData;
        node->GetParameter(ConstDescID(DescLevel(EXAMPLE_MATERIAL_LINK)), geData, DESCFLAGS_GET::NONE);
        BaseMaterial* const mat = static_cast<BaseMaterial*>(geData.GetLink(doc, Mbase));
 
        if (data) // called when the element is pasted into the scene, update material links
        {
          MarkMaterials* const markMaterial = static_cast<MarkMaterials*>(data);
 
          // check original material
          if (markMaterial->omat == mat)
          {
            doc->AddUndo(UNDOTYPE::CHANGE_SMALL, node);
            // set new material
            node->SetParameter(ConstDescID(DescLevel(EXAMPLE_MATERIAL_LINK)), markMaterial->nmat, DESCFLAGS_SET::NONE);
 
            node->Message(MSG_CHANGE);
          }
        }
        else  // called when the element is copied, mark needed materials
        {
          if (mat)
            mat->SetBit(BIT_MATMARK);
        }
        break;
      }

Table of Contents