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.
while (substance != nullptr)
{
substance = substance->GetNext();
}
AutoAlloc<AtomArray> substances;
if (substances == nullptr)
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)
}
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:69
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
void GetSubstances(BaseDocument *const doc, AtomArray *arr, Bool onlySelected)
BaseList2D * GetFirstSubstance(BaseDocument *const doc)
maxon::Int32 Int32
Definition: ge_sys_math.h:51
Add Assets
A Substance asset can be imported using the Filename of a Substance archive file (.sbsar).
BaseList2D* substance = nullptr;
const Bool invalidSubstance = substance ==
nullptr;
if (importFailure || invalidSubstance)
BaseList2D*
const copySubstance =
static_cast<BaseList2D*
>(substance->GetClone(
COPYFLAGS::NONE,
nullptr));
if (copySubstance == nullptr)
const String originalName = substance->GetName();
const String copyName = originalName + " Copy";
copySubstance->SetName(copyName);
NONE
Definition: asset_browser.h:1
NO
Definition: asset_downloads.h:0
SUBSTANCE_IMPORT_COPY
Definition: lib_substance.h:279
SUBSTANCE_IMPORT_RESULT
Definition: lib_substance.h:265
SUBSTANCE_IMPORT_RESULT ImportSubstance(BaseDocument *const doc, const Filename &fn, SUBSTANCE_IMPORT_COPY ©File, Bool errPopup, Bool addUndo, Bool createMaterial, BaseList2D **assetPtr)
Bool InsertLastSubstance(BaseDocument *const doc, BaseList2D *asset)
SUCCESS
Success.
Definition: lib_substance.h:0
maxon::Bool Bool
Definition: ge_sys_math.h:46
Get Assets
A Substance asset can contain one or multiple graphs, input parameters and output bitmaps.
void* graph = nullptr;
do
{
String name;
if (graph != nullptr)
{
void* input = nullptr;
do
{
String inputName;
input =
GetSubstanceInput(substance, graph, input, inputID, descID, numberElements, type, inputName);
if (input != nullptr)
} while (input != nullptr);
void* output = nullptr;
do
{
String outputName;
output =
GetSubstanceOutput(substance, graph, output, outputID, type, outputName,
nullptr);
if (output != nullptr)
} while (output != nullptr);
}
} while (graph != nullptr);
SUBSTANCE_INPUT_TYPE
Definition: lib_substance.h:291
SUBSTANCE_OUTPUT_TYPE
Definition: lib_substance.h:314
void * GetSubstanceGraph(BaseList2D *const asset, void *const prevGraph, String &name)
void * GetSubstanceInput(BaseList2D *const asset, void *const graph, void *const prevInput, UInt32 &inputUid, Int32 &firstId, Int32 &numElements, SUBSTANCE_INPUT_TYPE &type, String &name)
void * GetSubstanceOutput(BaseList2D *const asset, void *const graph, void *const prevOutput, UInt32 &outputUid, SUBSTANCE_OUTPUT_TYPE &type, String &name, BaseBitmap **bmpPtr)
maxon::UInt32 UInt32
Definition: ge_sys_math.h:52
Materials and Shaders
Substance assets are used in shaders and are typically applied (but not limited) to materials:
if (material == nullptr)
const String substanceName = substance->GetName();
const String materialName = substanceName + " Material";
material->SetName(materialName);
doc->InsertMaterial(material);
SUBSTANCE_MATERIAL_MODE
Definition: lib_substance.h:251
SUBSTANCE_MATERIAL_MODE PrefsGetMaterialModeSetting()
BaseMaterial * CreateMaterial(BaseList2D *const asset, Int32 graphIndex, SUBSTANCE_MATERIAL_MODE mode)
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.
Utility
Further utility functions are:
BaseMaterial* material = doc->GetFirstMaterial();
bool useSubstances = false;
while (material != nullptr)
{
{
useSubstances = true;
break;
}
material = material->GetNext();
}
if (useSubstances)
Bool MaterialUsesSubstance(BaseMaterial *const mat)
Further Reading