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());

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);
// 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);

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);

Further Reading

GeData::GetBool
Bool GetBool(void) const
Definition: c4d_gedata.h:421
PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL_NO
@ PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL_NO
Definition: prefssubstance.h:16
BaseShader
Definition: c4d_basechannel.h:35
MATERIAL_BUMP_SHADER
@ MATERIAL_BUMP_SHADER
Definition: mmaterial.h:278
BaseContainer::SetInt32
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:505
UInt32
maxon::UInt32 UInt32
Definition: ge_sys_math.h:59
BaseContainer::GetContainerInstance
BaseContainer * GetContainerInstance(Int32 id)
Definition: c4d_basecontainer.h:425
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
DESCFLAGS_SET::NONE
@ NONE
None.
SUBSTANCE_OUTPUT_TYPE
SUBSTANCE_OUTPUT_TYPE
Definition: lib_substance.h:314
Filename::GetString
String GetString(void) const
String
Definition: c4d_string.h:38
GetSubstanceOutput
void * GetSubstanceOutput(BaseList2D *const asset, void *const graph, void *const prevOutput, UInt32 &outputUid, SUBSTANCE_OUTPUT_TYPE &type, String &name, BaseBitmap **bmpPtr)
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
MATERIAL_USE_BUMP
@ MATERIAL_USE_BUMP
Definition: mmaterial.h:34
SUBSTANCE_OUTPUT_TYPE::BUMP
@ BUMP
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:286
SUBSTANCESHADER_CHANNEL
@ SUBSTANCESHADER_CHANNEL
Definition: Xsubstance.h:8
GeData
Definition: c4d_gedata.h:82
GeData::GetFilename
const Filename & GetFilename(void) const
Definition: c4d_gedata.h:475
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:58
PREFS_SUBSTANCE
#define PREFS_SUBSTANCE
Substance Engine.
Definition: lib_prefs.h:56
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
ID_SUBSTANCE_ASSET
static const Int32 ID_SUBSTANCE_ASSET
ID of the Substance asset.
Definition: lib_substance.h:171
PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL
@ PREFS_SUBSTANCE_ENGINE_CREATE_MATERIAL
Definition: prefssubstance.h:15
GeData::GetString
const String & GetString(void) const
Definition: c4d_gedata.h:463
CreateSubstanceShader
BaseShader * CreateSubstanceShader(BaseList2D *const asset)
DESCFLAGS_GET::NONE
@ NONE
None.
SUBSTANCEASSET_FILENAME
@ SUBSTANCEASSET_FILENAME
Definition: Nsubstanceasset.h:9
SUBSTANCEASSET_ENABLED
@ SUBSTANCEASSET_ENABLED
Definition: Nsubstanceasset.h:12
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:53
SUBSTANCEASSET_STATUS
@ SUBSTANCEASSET_STATUS
Definition: Nsubstanceasset.h:8
BaseContainer
Definition: c4d_basecontainer.h:46
BaseList2D::InsertShader
void InsertShader(BaseShader *shader, BaseShader *pred=nullptr)
Definition: c4d_baselist.h:2528