Substance Elements Manual

Table of Contents

• About
• Substance Assets
• Substance Shader
• Substance Presets
• Substance Preferences
• Further Reading

About

The Substance integration introduces a few new elements. These elements are:

• The Substance asset references a Substance archive file (.sbsar) and stores its set of current parameter values.
• The Substance shader references a Substance asset.
• The Substance preset is used to store a Substance asset including the Substance archive file and a parameter set in the Content Browser.

These elements are typically handled with the functions described in Substance Functions Manual.

Substance Assets

A Substance asset is not represented by a dedicated class. Instead a basic BaseList2D element is used. The parameter IDs are stored in nsubstanceasset.h.

• ID_SUBSTANCE_ASSET: The type ID of a Substance asset.

Note

To get the parameter IDs of input parameters use GetSubstanceInput(). To get the IDs of the output channels use GetSubstanceOutput().

  // This example checks if the given object is a Substance asset.
  // If so some of its parameters are accessed.
 
  // check if the given C4DAtom is a Substance asset
  if (substance->GetType() != ID_SUBSTANCE_ASSET)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  GeData data;
 
  // print filename
  if (!substance->GetParameter(DescLevel(SUBSTANCEASSET_FILENAME), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  ApplicationOutput("Substance File: " + data.GetFilename().GetString());
 
  // read SUBSTANCEASSET_ENABLED parameter
  if (!substance->GetParameter(DescLevel(SUBSTANCEASSET_ENABLED), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // check if enabled
  if (data.GetBool())
    ApplicationOutput("Substance is enabled");
 
  // get status
  if (!substance->GetParameter(DescLevel(SUBSTANCEASSET_STATUS), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  ApplicationOutput("Status: " + data.GetString());

Substance Shader

The Substance shader references a Substance asset and a selected output channel in Cinema 4D's material system (or all other places, where shaders can be used). The parameters are defined in xsubstance.h.

• ID_SUBSTANCE_SHADER: The ID of the Substance shader.

See also Materials and Shaders Overview.

  // This example creates a new Substance shader linked to the given Substance asset.
  // The asset is scanned for a bump output channel that is used in that shader.
 
  // create a new Substance shader
  BaseShader* const shader = CreateSubstanceShader(substance);
  if (shader == nullptr)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // insert shader into material and use in bump channel
  material->InsertShader(shader);
  material->SetParameter(DescLevel(MATERIAL_BUMP_SHADER), shader, DESCFLAGS_SET::NONE);
  material->SetParameter(DescLevel(MATERIAL_USE_BUMP), true, DESCFLAGS_SET::NONE);
 
  // check all output channels
  void* output = nullptr;
 
  do
  {
    UInt32 outputID;
    SUBSTANCE_OUTPUT_TYPE type;
    String outputName;
 
    output = GetSubstanceOutput(substance, graph, output, outputID, type, outputName, nullptr);
 
    // check if the output could be obtained and if that output is a "Bump" output
    const Bool validOutput = output != nullptr;
    const Bool typeIsBump  = type == SUBSTANCE_OUTPUT_TYPE::BUMP;
    if (validOutput && typeIsBump)
    {
      shader->SetParameter(DescLevel(SUBSTANCESHADER_CHANNEL), Int32(outputID), DESCFLAGS_SET::NONE);
    }
 
  } while (output != nullptr);

Substance Presets

Substance presets can be stored in the Content Browser.

• ID_SUBSTANCE_PRESET: The type ID of a Substance preset.

Substance Preferences

The Substance preferences define the type and behaviour of the integrated Substance Engine and influence the workflow of working with Substance assets. The parameters are defined in prefssubstance.h.

• ID_SUBSTANCE_PREFERENCES: The ID of the Substance parameter group.

  // This example changes a parameter of the Substance preferences.
 
  BaseContainer* const bc = worldContainer->GetContainerInstance(ID_SUBSTANCE_PREFERENCES);
  if (bc == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  bc->SetInt32(PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL, PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL_NO);

Further Reading

• Substance Functions Manual
• BaseList2D Manual
• Materials and Shaders Overview
• BaseShader Manual