BaseMaterial Manual

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:

See BaseDocument Materials

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

// 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.

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

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

// This example creates a new "Cheen" material and assigns it
// to the given object with a new TextureTag.
// make new material
// make 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:

// 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.

// 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.

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:

If needed the material calculation is initiated with:

The material can now be sampled and used with:

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()
material->InitCalculation(volumeData, INITCALCULATION::SURFACE);
// init
const INITRENDERRESULT res = material->InitTextures(irs);
// 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:

// 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.
{
BaseDocument* const doc = node->GetDocument();
if (doc == nullptr)
return false;
// get referenced material
GeData geData;
node->GetParameter(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)
{
// set new material
node->SetParameter(EXAMPLE_MATERIAL_LINK, markMaterial->nmat, DESCFLAGS_SET::NONE);
}
}
else // called when the element is copied, mark needed materials
{
if (mat)
}
break;
}

Further Reading

BaseVolumeData::uvw
Vector uvw
[READ ONLY] The surface UVW coordinates, this is invalid for volumetric shaders.
Definition: c4d_shader.h:887
MarkMaterials
Definition: c4d_baselist.h:756
BaseMaterial::UnlockTextures
void UnlockTextures()
Unlocks all textures used by the material.
Definition: c4d_basematerial.h:109
BaseVolumeData::ray
Ray * ray
[READ ONLY] The current eye ray. Always valid, not nullptr.
Definition: c4d_shader.h:880
MarkMaterials::omat
BaseMaterial * omat
Original material. Cinema&#160;4D owns the pointed material.
Definition: c4d_baselist.h:763
TextureTag
Definition: c4d_basetag.h:646
BaseVolumeData::n
Vector64 n
[READ ONLY] The surface phong normal.
Definition: c4d_shader.h:882
RENDERRESULT::OUTOFMEMORY
@ OUTOFMEMORY
Not enough memory.
BaseMaterial::InitTextures
INITRENDERRESULT InitTextures(const InitRenderStruct &irs)
Definition: c4d_basematerial.h:104
BaseDocument::AddUndo
Bool AddUndo(UNDOTYPE type, void *data, Bool allowFromThread=false)
BaseDocument::GetFirstMaterial
BaseMaterial * GetFirstMaterial(void)
VOLUMEINFO::INITCALCULATION
@ INITCALCULATION
Needs MaterialData::InitCalculation() call.
maxon::OK
return OK
Definition: apibase.h:2546
GeData::GetLink
BaseList2D * GetLink(const BaseDocument *doc, Int32 instanceof=0) const
UNDOTYPE::CHANGE_SMALL
@ CHANGE_SMALL
Change to local data only (e.g. data container). No substructures (e.g. no tags on an object) and no ...
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
MSG_MULTI_MARKMATERIALS
#define MSG_MULTI_MARKMATERIALS
Definition: c4d_baselist.h:506
BaseMaterial::CalcSurface
void CalcSurface(VolumeData *sd)
Definition: c4d_basematerial.h:139
BaseList2D::SetBit
void SetBit(Int32 mask)
Definition: c4d_baselist.h:2230
DESCFLAGS_SET::NONE
@ NONE
None.
BIT_MATMARK
#define BIT_MATMARK
Marked material.
Definition: ge_prepass.h:848
Mcheen
#define Mcheen
Cheen.
Definition: ge_prepass.h:962
INITCALCULATION::SURFACE
@ SURFACE
Called during rendering for surface calculation.
BaseMaterial::GetPreview
BaseBitmap * GetPreview(Int32 flags)
BaseDocument::InsertMaterial
void InsertMaterial(BaseMaterial *mat, BaseMaterial *pred=nullptr, Bool checknames=false)
TextureTag::SetMaterial
void SetMaterial(BaseMaterial *mat)
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
BaseVolumeData::col
Vector col
[READ WRITE] Set the calculated color within MaterialData::CalcSurface() and MaterialData::CalcVolume...
Definition: c4d_shader.h:871
maxon::Vec3< maxon::Float64, 1 >
InitRenderStruct
Definition: c4d_shader.h:179
INITRENDERRESULT
INITRENDERRESULT
Definition: ge_prepass.h:398
TextureTag::GetMaterial
BaseMaterial * GetMaterial(Bool ignoredoc=false)
BaseVideoPostStruct::doc
BaseDocument * doc
The active document.
Definition: c4d_videopostdata.h:91
BaseVolumeData::calc_illum
Int32 calc_illum
Definition: c4d_shader.h:906
BaseVolumeData::tex
const TexData * tex
[READ ONLY] The surface texture, never change this pointer.
Definition: c4d_shader.h:891
GeData
Definition: c4d_gedata.h:82
VolumeData
Definition: c4d_tools.h:1299
BaseVideoPostStruct::vd
VolumeData * vd
The current VolumeData. Only valid for VIDEOPOSTCALL::INNER and VIDEOPOSTCALL::RENDER calls.
Definition: c4d_videopostdata.h:90
GeListNode::GetDocument
BaseDocument * GetDocument()
Definition: c4d_baselist.h:1945
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
C4DAtom::Message
Bool Message(Int32 type, void *data=nullptr)
Definition: c4d_baselist.h:1424
ShowBitmap
Bool ShowBitmap(const Filename &fn)
Ttexture
#define Ttexture
Texture - TextureTag.
Definition: ge_prepass.h:1243
BaseMaterial::GetRenderInfo
VOLUMEINFO GetRenderInfo(void)
Definition: c4d_basematerial.h:210
MarkMaterials::nmat
BaseMaterial * nmat
New material. Cinema&#160;4D owns the pointed material.
Definition: c4d_baselist.h:764
BaseBitmap
Definition: c4d_basebitmap.h:413
AutoAlloc::Release
TYPE * Release()
Definition: ge_autoptr.h:120
AutoAlloc
Definition: ge_autoptr.h:36
DESCFLAGS_GET::NONE
@ NONE
None.
BaseMaterial::GetNext
BaseMaterial * GetNext(void)
Definition: c4d_basematerial.h:60
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
MSG_CHANGE
#define MSG_CHANGE
Definition: c4d_baselist.h:343
BaseVolumeData::p
Vector64 p
[READ WRITE] The surface point, this can only be modified by MaterialData::Displace().
Definition: c4d_shader.h:877
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
Mbase
#define Mbase
Base material.
Definition: ge_prepass.h:954
BaseMaterial::InitCalculation
void InitCalculation(VolumeData *sd, INITCALCULATION type)
Definition: c4d_basematerial.h:171
BaseMaterial
Definition: c4d_basematerial.h:27
INITRENDERRESULT::OK
@ OK
Everything is OK, there was no error.
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
BaseDocument
Definition: c4d_basedocument.h:490