Substance Elements Manual

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.

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());
@ SUBSTANCEASSET_FILENAME
Definition: Nsubstanceasset.h:9
@ SUBSTANCEASSET_STATUS
Definition: Nsubstanceasset.h:8
@ SUBSTANCEASSET_ENABLED
Definition: Nsubstanceasset.h:12
String GetString() const
Definition: c4d_gedata.h:83
const Filename & GetFilename() const
Definition: c4d_gedata.h:475
Bool GetBool() const
Definition: c4d_gedata.h:421
const String & GetString() const
Definition: c4d_gedata.h:463
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
static const Int32 ID_SUBSTANCE_ASSET
ID of the Substance asset.
Definition: lib_substance.h:171
Represents a level within a DescID.
Definition: lib_description.h:289

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.

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;
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)
{
}
} while (output != nullptr);
@ SUBSTANCESHADER_CHANNEL
Definition: Xsubstance.h:8
Definition: c4d_basechannel.h:36
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
Definition: c4d_string.h:39
Py_ssize_t char * output
Definition: unicodeobject.h:985
maxon::Bool Bool
Definition: ge_sys_math.h:55
maxon::Int32 Int32
Definition: ge_sys_math.h:60
maxon::UInt32 UInt32
Definition: ge_sys_math.h:61
SUBSTANCE_OUTPUT_TYPE
Definition: lib_substance.h:315
BaseShader * CreateSubstanceShader(BaseList2D *const asset)
void * GetSubstanceOutput(BaseList2D *const asset, void *const graph, void *const prevOutput, UInt32 &outputUid, SUBSTANCE_OUTPUT_TYPE &type, String &name, BaseBitmap **bmpPtr)
@ MATERIAL_BUMP_SHADER
Definition: mmaterial.h:300
@ MATERIAL_USE_BUMP
Definition: mmaterial.h:34
PyObject ** type
Definition: pycore_pyerrors.h:34

Substance Presets

Substance presets can be stored in the Content Browser.

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(PREFS_SUBSTANCE);
if (bc == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
Definition: c4d_basecontainer.h:47
BaseContainer * GetContainerInstance(Int32 id)
Definition: c4d_basecontainer.h:425
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:505
#define PREFS_SUBSTANCE
Substance Engine.
Definition: lib_prefs.h:55
@ PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL
Definition: prefssubstance.h:15
@ PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL_NO
Definition: prefssubstance.h:16

Further Reading