About

The Substance functions allow to import and handle Allegorithmic Substance assets into a BaseDocument. In a document they can be used with shaders and materials. The Substance functions are defined in the lib_substance.h header file.

Access Assets

Substance assets store a reference to a Substance archive file (.sbsar) and the current value set of its parameters. These assets are stored in the BaseDocument.

GetFirstSubstance(): Returns the first Substance asset stored in the given BaseDocument.
GetSubstances(): Stores the pointers to all Substance assets in the given AtomArray.

  // This example accesses the first Substance to loop through all Substances.
 
  BaseList2D* substance = GetFirstSubstance(doc);
  while (substance != nullptr)
  {
    ApplicationOutput("Substance: " + substance->GetName());
    substance = substance->GetNext();
  }
 
  // This example accesses all selected Substances
 
  AutoAlloc<AtomArray> substances;
  if (substances == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  GetSubstances(doc, substances, true);
 
  const Int32 substanceCount = substances->GetCount();
  for (Int32 i = 0; i < substanceCount; ++i)
  {
    C4DAtom* const atom = substances->GetIndex(i);
    const BaseList2D* const asset = static_cast<BaseList2D*>(atom);
    if (asset == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    ApplicationOutput("Selected Substance: " + asset->GetName());
  }

Add Assets

A Substance asset can be imported using the Filename of a Substance archive file (.sbsar).

ImportSubstance(): Imports the referenced Substance archive file into the given BaseDocument.
InsertLastSubstance() Inserts the given Substance asset into the given BaseDocument.

  // This example imports a Substance asset with the given filename.
  // Then a copy of that asset is created.
 
  BaseList2D* substance = nullptr;
  SUBSTANCE_IMPORT_COPY copy = SUBSTANCE_IMPORT_COPY::NO;
 
  // import Substance
  const SUBSTANCE_IMPORT_RESULT res = ImportSubstance(doc, filename, copy, false, false, true, &substance);
 
  // check if the Substance was imported successfully
  const Bool importFailure = res != SUBSTANCE_IMPORT_RESULT::SUCCESS;
  const Bool invalidSubstance = substance == nullptr;
 
  if (importFailure || invalidSubstance)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // copy Substance
  BaseList2D* const copySubstance = static_cast<BaseList2D*>(substance->GetClone(COPYFLAGS::NONE, nullptr));
  if (copySubstance == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  const String originalName = substance->GetName();
  const String copyName = originalName + " Copy";
  copySubstance->SetName(copyName);
 
  // insert copy
  if (!InsertLastSubstance(doc, copySubstance))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);

Get Assets

A Substance asset can contain one or multiple graphs, input parameters and output bitmaps.

GetSubstanceGraph(): Returns an asset graph and can be used to iterate over the graphs.
GetSubstanceInput() Returns an asset input and can be used to iterate over the inputs.
GetSubstanceOutput(): Returns an asset output and can be used to iterate over the outputs. The output IDs are needed to use CreateSubstanceShader() and AssignChannelToMaterial().

  // This example loops through the graphs of the given Substance asset.
  // The graph is then used to loop through the input parameters and output images.
 
  void* graph = nullptr;
 
  // loop through graphs
  do
  {
    String name;
    graph = GetSubstanceGraph(substance, graph, name);
 
    if (graph != nullptr)
    {
      ApplicationOutput("Graph Name: " + name);
 
      // loop through inputs
 
      void* input = nullptr;
 
      do
      {
        String inputName;
        UInt32 inputID;
        Int32  numberElements;
        Int32  descID;
        SUBSTANCE_INPUT_TYPE type;
 
        input = GetSubstanceInput(substance, graph, input, inputID, descID, numberElements, type, inputName);
 
        if (input != nullptr)
          ApplicationOutput("Input: " + inputName);
 
      } while (input != nullptr);
 
      // loop through outputs
 
      void* output = nullptr;
 
      do
      {
        UInt32 outputID;
        SUBSTANCE_OUTPUT_TYPE type;
        String outputName;
        output = GetSubstanceOutput(substance, graph, output, outputID, type, outputName, nullptr);
 
        if (output != nullptr)
          ApplicationOutput("Output: " + outputName);
 
      } while (output != nullptr);
    }
  } while (graph != nullptr);

Materials and Shaders

Substance assets are used in shaders and are typically applied (but not limited) to materials:

CreateMaterial(): Creates a standard material based on the given asset. See also Substance Preferences.
CreateSubstanceShader(): Creates a Substance shader based on the given asset. The created shader can be configured using the output IDs delivered by GetSubstanceOutput().
AssignChannelToMaterial(): Creates a Substance shader in the given channel of the given Material. This function needs the output IDs delivered by GetSubstanceOutput().

  // This example creates a material from a given Substance asset.
 
  const SUBSTANCE_MATERIAL_MODE mode = PrefsGetMaterialModeSetting();
  BaseMaterial* const material = CreateMaterial(substance, 0, mode);
  if (material == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  const String substanceName = substance->GetName();
  const String materialName  = substanceName + " Material";
  material->SetName(materialName);
 
  doc->InsertMaterial(material);

An example how to configure a Substance shader can be found on Substance Elements Manual.

Substance Preferences

These utility functions allow fast access to the most important Substance preferences.

PrefsGetMaterialModeSetting(): Returns how the automatically created material is set up (see CreateMaterial()).
::SUBSTANCE_MATERIAL_MODE: The creation mode.
- SUBSTANCE_MATERIAL_MODE::STANDARD : Create standard material.
- SUBSTANCE_MATERIAL_MODE::METALLIC : Create metallic material.
- SUBSTANCE_MATERIAL_MODE::GLOSSY : Create glossy material.
- SUBSTANCE_MATERIAL_MODE::AUTO : Use heuristic to choose one of the three above (see Cinema 4D's user manual).
- SUBSTANCE_MATERIAL_MODE::NONE : Do not create material.
PrefsGetPreviewSetting(): Returns the preview mode for the Content Browser.

Utility

Further utility functions are:

MaterialUsesSubstance(): Returns true if the given BaseMaterial uses Substances.
GetSubstanceMosaicPreview(): Returns an image with previews of the output channels of the given asset.

  // This example checks if the given scene uses Substance assets in the materials.
 
  // get first material
  BaseMaterial* material = doc->GetFirstMaterial();
 
  // check all materials
 
  bool useSubstances = false;
 
  while (material != nullptr)
  {
    // check if the given material uses Substances
    if (MaterialUsesSubstance(material))
    {
      useSubstances = true;
      break;
    }
 
    material = material->GetNext();
  }
 
  if (useSubstances)
    ApplicationOutput("This scene uses Substances.");

Table of Contents