Introduction

To export a custom Material definition (read ExchangeMapper Material Definition Manual), from your own custom Cinema 4D material, the next interfaces need to be implemented according to your need:

maxon::material::MaterialExportInterface to create a material description given a Cinema API Material Data.
maxon::nodes::NodeMaterialExportInterface to create a material description given a Node Material through the Node API.

One material can have multiple maxon::material::MaterialExportInterface or maxon::nodes::NodeMaterialExportInterface implementations describing how the export process will work.

The export process provides automatic baking if a given material description is not handled by the maxon::material::MaterialExportInterface or maxon::nodes::NodeMaterialExportInterface implementations through the maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL material description.

As an example, if an FBX is exported but the implemented exporter only handles a VIEWPORTMATERIAL material definition for the given material, the VIEWPORTMATERIAL material description provided by the exporter will be mapped to an FBX material description automatically.
However, it's relevant to remind that this translation is a lossy translation, with data being sacrificed.
For better handling, it's instead suggested to directly output an FBX material definition. For more information read ExchangeMapper Material Definition Manual.

Note: Within the material export implementation, it is recommended monitoring the thread cancellation state when executing time-consuming operations (e.g. baking) to react immediately upon user aborting an export process.

MaterialExportInterface

A maxon::material::MaterialExportInterface can be called at any time, e.g. from a SceneLoaderData but also from a regular CommandData or anything else.

A maxon::material::MaterialExportInterface provides few methods:

maxon::material::MaterialExportInterface::Export: static method, not to be overridden, performing a lookup into the MaterialExporters registry to find a valid exporter and exporting the given *BaseMaterial to a maxon::material::MaterialExchangeData using the next methods (execution order from top to bottom).
maxon::material::MaterialExportInterface::Initialize: method initializing the export operation by providing the BaseMaterial and the export configuration.
maxon::material::MaterialExportInterface::GetParameters: method returning the constant-values parameters and the information of whether they require texture representation to provide texture baking in the GetTextures() stage.
maxon::material::MaterialExportInterface::GetTextures: method creating textures (maxon::material::TextureBuffer, maxon::material::ImageReference or maxon::material::SubstanceReference) for the provided parameters.

All MaterialExportInterface shall be registered using a maxon::material::MaterialExportDescription into the maxon::material::MaterialExporters registry.

A maxon::material::MaterialExportDescription links a given Cinema API Plugin ID to a maxon::material::MaterialExportRef.

Example of an implementation using the SimpleMaterial from the Cinema 4D SDK as the source of the export process.

maxon::Result<void> SimpleMaterialExport::Initialize(const BaseMaterial& baseMaterial, const maxon::DataDictionary& config)
{
  iferr_scope;
 
  _baseMaterial = &baseMaterial;
  maxon::material::MaterialTypesMap materialTypes = config.Get(maxon::material::EXPORT::CONFIG::MATERIALTYPESWITHSUPPORT) iferr_return;
 
  // We only support Standard Surface in this example.
  CheckArgument(materialTypes.Contains(maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::GetId()) == true);
 
  return maxon::OK;
}
 
maxon::Result<maxon::Tuple<maxon::Id, maxon::DataDictionary>>SimpleMaterialExport::GetParameters()
{
  iferr_scope;
 
  maxon::Tuple<maxon::Id, maxon::DataDictionary> result;
  result.first = maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::GetId();
  result.second = maxon::material::ParameterStorageInterface::LoadDefaults(maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::GetId()) iferr_return;
 
  if (_baseMaterial != nullptr)
  {
    const Int32 SIMPLEMATERIAL_COLOR = 1000;
    const maxon::Color simpleMaterialColor = _baseMaterial->GetDataInstanceRef().GetVector(SIMPLEMATERIAL_COLOR).GetColor();
    maxon::material::ParameterStorageInterface::Insert(result.second, maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::BASE_COLOR, simpleMaterialColor, true, 0) iferr_return;
  }
 
  return result;
}
 
maxon::Result<maxon::HashMap<maxon::Id, maxon::Data>> SimpleMaterialExport::GetTextures(const maxon::HashSet<maxon::Id>& texturedChannels)
{
  maxon::HashMap<maxon::Id, maxon::Data> textures;
 
  // No textures to declare.
  return textures;
}
 
// The Registration Process
static maxon::GenericData g_materialExportRegistration;
maxon::Result<void> SimpleMaterialExport::Register()
{
  iferr_scope;
 
  const Int32 ID_SIMPLEMAT = 1001164;
 
  maxon::material::MaterialExportDescription description;
  description._type = ID_SIMPLEMAT;
  description._class = SimpleMaterialExport::GetClass();
  g_materialExportRegistration = maxon::material::MaterialExporters::Register(SimpleMaterialExport::GetDescriptor().GetId(), std::move(description)) iferr_return;
  return maxon::OK;
}
 
void SimpleMaterialExport::Free()
{
  g_materialExportRegistration = maxon::GenericData();
}
 
MAXON_COMPONENT_OBJECT_REGISTER(SimpleMaterialExport, "net.maxonsdk.doc_cpp.class.simplematerialexport");

NodeMaterialExportInterface

maxon::nodes::NodeMaterialExportInterface can be called at any time, e.g. from a SceneLoaderData but also from a regular CommandData or anything else.

A maxon::nodes::NodeMaterialExportInterface provides few methods:

maxon::nodes::NodeMaterialExportInterface::Initialize: method initializing the export operation by providing the NodesGraphModelRef that should be exported, the *BaseDocument and the export configuration for the context.
maxon::nodes::NodeMaterialExportInterface::GetParameters: method returning the constant-values parameters and the information of whether they require texture representation to support texture baking in the GetTextures() stage.
maxon::nodes::NodeMaterialExportInterface::GetTextures: method creating textures (maxon::material::TextureBuffer, maxon::material::ImageReference or maxon::material::SubstanceReference) for the provided parameters.

To register a supported material definition, the maxon::nodes::NODESPACE::MATERIALEXCHANGEBUNDLEIDS attribute of the node space shall be filled with a maxon::BaseArray of material bundle maxon::Id.

  maxon::BaseArray<maxon::Id> materialExchangeBundleIds;
  materialExchangeBundleIds.Append(maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::GetId()) iferr_return;
  nodeSpaceData.Set(maxon::nodes::NODESPACE::MATERIALEXCHANGEBUNDLEIDS, std::move(materialExchangeBundleIds)) iferr_return;

To register the custom exporter, the maxon::nodes::NODESPACE::MATERIALEXCHANGECLASS attribute of the node space shall be filled with the maxon::nodes::NodeMaterialExportInterface maxon::Class object.

// nodeSpaceData.Set(maxon::nodes::NODESPACE::MATERIALEXCHANGECLASS, YourMaterialNodeExportInterfaceImplementation::GetClass()) iferr_return;

If no exporter is defined for a given node space, a fall-back is performed by the maxon::nodes::MaterialExchangeInterface to create a textured material of type maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL.

Table of Contents

Introduction

MaterialExportInterface

NodeMaterialExportInterface

Further Reading