就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. C4D R23.110 C++ SDK
Groups | Classes

Substance Library Library

详细描述

由于
R18
另请参阅
The Substance Overview article.

The Substance library contains everything needed to control the Substance Engine integration in Cinema 4D . Main topics are:

Importing Substance Assets:

注意
There's also the command ID_SUBSTANCE_COMMAND_LOADASSET , which may be shorter, if user interaction is wanted.
void MySubstanceImport() { BaseDocument * const doc = GetActiveDocument (); if (doc == nullptr ) return ;

// Setup import parameters Filename fn = "some_path/nice_substance.sbsar" ; SUBSTANCE_IMPORT_COPY copyMode = SUBSTANCE_IMPORT_COPY::NO ; // do not copy the Substance archive into the project directory and use absolute path to refer to the file const Bool errPopup = false ; // Don't open any error messages const Bool addUndo = true ; // Yes, please add an undo step for the import const Bool noMaterial = true ; // No material will be created on import BaseList2D * myImportedAsset = nullptr ; SUBSTANCE_IMPORT_RESULT result;

// Import doc-> StartUndo (); // DON'T FORGET, mandatory since we chose to add an undo step result = ImportSubstance (doc, fn, copyMode, errPopup, addUndo, noMaterial, &myImportedAsset); doc-> EndUndo (); // DON'T FORGET, mandatory since we chose to add an undo step if (result != SUBSTANCE_IMPORT_RESULT::SUCCESS ) { // something went wrong, handle error here... return ; } // The substance got successfully inserted into the document // ... // return; }

Auto-creating basic material from a Substance:

void MySubstanceCreateMaterial() { BaseDocument * const doc = GetActiveDocument (); if (doc == nullptr ) return ; BaseList2D * asset = GetFirstSubstance (doc); if (asset == nullptr ) { // No Substance asset in the scene return ; } const Int32 graphIdx = 0; // Use the first graph of the Substance const SUBSTANCE_MATERIAL_MODE mode = SUBSTANCE_MATERIAL_MODE::METALLIC ; // Use PBR metallic/roughness workflow BaseMaterial * const mat = CreateMaterial (myImportedAsset, graphIdx, mode); if (mat == nullptr ) { // Failed to create material return ; } doc-> InsertMaterial (mat); }

Iterate over all graphs, inputs and outputs of a Substance:

void MyPrintAllSubstances() { BaseDocument * const doc = GetActiveDocument (); if (doc == nullptr ) return ; AutoAlloc<AtomArray> arrSubstances; if (arrSubstances == nullptr ) return ; const Bool onlySelected = false ; // Get all Substances in the document GetSubstances (doc, arrSubstances, onlySelected); for ( Int32 idxSubstance = 0; idxSubstance < arrSubstances-> GetCount (); ++idxSubstance) { BaseList2D * const asset = static_cast< BaseList2D * > (arrSubstances-> GetIndex (idxSubstance)); if (asset == nullptr ) continue ; // This should not happen, but safe is safe GePrint ( "Substance: " + asset-> GetName (); String graphName = "" ; void * lastGraph = nullptr , graph = nullptr ; while (graph = GetSubstanceGraph (asset, lastGraph, graphName)) { GePrint ( " Graph: " + graphName); UInt32 inputUid; Int32 inputDescId; Int32 inputNumElements; SUBSTANCE_INPUT_TYPE inputType; String inputName; void * lastInput = nullptr , input = nullptr ; GePrint ( " Inputs:" ); while (input = GetSubstanceInput (asset, graph, lastInput, inputUid, inputDescId, inputNumElements, inputType, inputName)) { GePrint ( " " + inputName + " (" + String::HexToString (inputUid) + ", " + String::IntToString (inputDescId) + ", " + String::IntToString (inputNuMElements) + ", " + String::IntToString (( Int32 )inputType) + ")" ); lastInput = input; } UInt32 outputUid; SUBSTANCE_OUTPUT_TYPE outputType; String outputName; void * lastOutput = nullptr , output = nullptr ; GePrint ( " Outputs:" ); while (output = GetSubstanceOutput (asset, graph, lastOutput, outputUid, outputType, outputName, nullptr )) { GePrint ( " " + outputName + " (" + String::HexToString (outputUid) + ", " + String::IntToString (( Int32 )outputType) + ")" ); lastOutput = output; } lastGraph = graph; } } }

Changing Substance input parameters:

This basically works the same as with every other NodeData based entity in Cinema 4D , via SetParameter().

另请参阅
SUBSTANCE_INPUT_TYPE
警告
Under no circumstances the BaseContainer of a Substance assets should be accessed directly. The IDs for use with SetParameter() can be obtained via GetSubstanceInput() .

Chapter Substance shader and its parameters:

The Substance shader has two parameters, SUBSTANCESHADER_ASSET and SUBSTANCESHADER_CHANNEL .

Groups

  SUBSTANCE_IMPORT_COPY
  SUBSTANCE_IMPORT_RESULT
  SUBSTANCE_INPUT_TYPE
  SUBSTANCE_MATERIAL_MODE
  SUBSTANCE_OUTPUT_TYPE
  Substance Command IDs
  Substance Message IDs
  Substance Plugin IDs

Classes

struct   SubstanceShdGetBitmap

创建

SUBSTANCE_IMPORT_RESULT   ImportSubstance ( BaseDocument *const doc, const Filename &fn, SUBSTANCE_IMPORT_COPY ©File, Bool errPopup, Bool addUndo, Bool createMaterial, BaseList2D **assetPtr)
BaseMaterial *  CreateMaterial ( BaseList2D *const asset, Int32 graphIndex, SUBSTANCE_MATERIAL_MODE mode)
BaseShader *  CreateSubstanceShader ( BaseList2D *const asset)
Bool   AssignChannelToMaterial ( BaseList2D *const asset, 材质 *const c4dMaterial, Int32 channelId, Int32 outputUid, Bool addUndo)

Get and Insert

BaseList2D *  GetFirstSubstance ( BaseDocument *const doc)
void  GetSubstances ( BaseDocument *const doc, AtomArray *arr, Bool onlySelected)
Bool   InsertLastSubstance ( BaseDocument *const doc, BaseList2D *asset)

Graphs, Inputs, Outputs

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)

首选项

SUBSTANCE_MATERIAL_MODE   PrefsGetMaterialModeSetting ()
Int32   PrefsGetPreviewSetting ()

Misc

Bool   MaterialUsesSubstance ( BaseMaterial *const mat)
BaseBitmap *  GetSubstanceMosaicPreview ( BaseList2D *const asset, Int32 w, Int32 h)

Private

void  UpdateImageInputPaths ( BaseList2D *const asset, String &path)
void  CloneReferencedSubstances ( BaseDocument *const doc, BaseShader *const shd, BaseDocument *const ddoc, BaseShader *const dshd)
void  CloneReferencedSubstancesObject ( BaseDocument *const docSrc, BaseObject *const opSrc, BaseDocument *const docDst, BaseObject *const opDst)
void  InsertSubstancePreviewScene ( BaseDocument *const doc, BaseList2D *const asset)
const BaseBitmap *  GetContentBrowserOverlay ()

Function Documentation

◆  ImportSubstance()

SUBSTANCE_IMPORT_RESULT ImportSubstance ( BaseDocument *const  doc ,
const Filename &  fn ,
SUBSTANCE_IMPORT_COPY &  copyFile ,
Bool   errPopup ,
Bool   addUndo ,
Bool   createMaterial ,
BaseList2D **  assetPtr  
)

Imports a Substance Asset file (.sbsar) into doc .

由于
R18
参数
[in] doc The document to import into.
[in] fn The Substance Asset file.
[in,out] copyFile The copy file flag: SUBSTANCE_IMPORT_COPY . Determines if Substance Asset files are copied into the project folder (and therefore referenced with relative path).
若设为 SUBSTANCE_IMPORT_COPY::ASK , user's choice will be returned.
Note: When set to SUBSTANCE_IMPORT_COPY::ASK , the function obviously has to be called in a context, where user interaction is allowed.
[in] errPopup 若设为 true , problems will be communicated to the user with a message requester.
Note: When set to true , the function obviously has to be called in a context, where user interaction is allowed.
[in] addUndo 若设为 true , an undo step will be added for the import. Caller has to care for the surrounding BaseDocument::StartUndo() and BaseDocument::EndUndo() calls.
[in] createMaterial Set to true , to have a material created based on the configuration in preferences. Set to false , to suppress any creation of materials.
[in,out] assetPtr A pointer to a Substance asset pointer. If not nullptr , the pointer to the imported Substance Asset will be returned here.
返回
The result for the import: SUBSTANCE_IMPORT_RESULT

◆  CreateMaterial()

BaseMaterial * CreateMaterial ( BaseList2D *const  asset ,
Int32   graphIndex ,
SUBSTANCE_MATERIAL_MODE   mode  
)

Creates a Cinema 4D standard material from asset .

由于
R18
参数
[in] asset The Substance asset.
[in] graphIndex The index of the graph to use (for multi-graph Substances).
[in] mode The material creation mode: SUBSTANCE_MATERIAL_MODE
返回
The created material. The caller owns the pointed material.

◆  CreateSubstanceShader()

BaseShader * CreateSubstanceShader ( BaseList2D *const  asset )

Creates a Substance shader linked to asset .

由于
R18
参数
[in] asset The Substance asset (may be nullptr ).
返回
The created Substance shader. The caller owns the pointed shader.

◆  AssignChannelToMaterial()

Bool AssignChannelToMaterial ( BaseList2D *const  asset ,
材质 *const  c4dMaterial ,
Int32   channelId ,
Int32   outputUid ,
Bool   addUndo  
)

Creates a Substance shader, links it to asset , sets the Substance output to outputUid and assigns the shader to channelId of c4dMaterial .

由于
R18
参数
[in] asset The Substance asset, the pointed Substance asset needs to be part of the document.
[in] c4dMaterial The 材质 .
[in] channelId The channel ID: CHANNEL
[in] outputUid The unique ID of the Substance output to use.
[in] addUndo 若设为 true , an undo step will be added for the import. Caller has to care for the surrounding BaseDocument::StartUndo() and BaseDocument::EndUndo() calls.
返回
true if successful, otherwise false .

◆  GetFirstSubstance()

BaseList2D * GetFirstSubstance ( BaseDocument *const  doc )

Retrieves a pointer to the first Substance asset in doc .

由于
R18
参数
[in] doc The document.
返回
The first Substance asset or nullptr , if none exists. Cinema 4D owns the pointed Substance asset.

◆  GetSubstances()

void GetSubstances ( BaseDocument *const  doc ,
AtomArray *  arr ,
Bool   onlySelected  
)

Retrieves all (or only selected) substances assets doc .

由于
R18
参数
[in] doc The document.
[in] arr The AtomArray to fill. The caller owns the pointed array.
[in] onlySelected Set to true to get only selected Substance assets.

◆  InsertLastSubstance()

Bool InsertLastSubstance ( BaseDocument *const  doc ,
BaseList2D *  asset  
)

Inserts asset into doc (as last element).

由于
R18
参数
[in] doc The document.
[in] asset The Substance asset. On success Cinema 4D takes over the ownership of the pointed Substance asset.
返回
true if success, otherwise false .

◆  GetSubstanceGraph()

void* GetSubstanceGraph ( BaseList2D *const  asset ,
void *const  prevGraph ,
String &  name  
)

Retrieves the Substance graph. This function may be used to iterate over the graphs of asset .

由于
R18
参数
[in] asset The Substance asset.
[in] prevGraph Pass nullptr to get the first graph, pass a graph pointer to get the following graph.
[out] name Name of the returned graph. Only valid if return value != nullptr .
返回
A pointer to identify the graph, may not be dereferenced. nullptr if graph is not available. Cinema 4D owns the pointed graph.

◆  GetSubstanceInput()

void* GetSubstanceInput ( BaseList2D *const  asset ,
void *const  graph ,
void *const  prevInput ,
UInt32 &  inputUid ,
Int32 &  firstId ,
Int32 &  numElements ,
SUBSTANCE_INPUT_TYPE &  type ,
String &  name  
)

Retrieves a Substance input of an asset. This function may be used to iterate over the inputs of a graph of asset .

由于
R18
参数
[in] asset The Substance asset.
[in] graph The graph.
[in] prevInput Pass nullptr to get the first input, pass an input pointer to get the following input.
[out] inputUid The unique ID of the input. Only valid if return value != nullptr .
[out] firstId The ID of the first component of the input parameter in Cinema 4D (see also numElements ). This ID can be used to create a DescID for C4DAtom::SetParameter() . Only valid if return value != nullptr .
[out] numElements The number of description elements used in Cinema 4D to represent the Substance input parameter. Only valid if return value != nullptr .
[out] type The data type of the input: SUBSTANCE_INPUT_TYPE . Only valid if return value != nullptr .
[out] name Name of the returned input. Only valid if return value != nullptr .
返回
A pointer to identify the input, may not be dereferenced. nullptr if input is not available. Cinema 4D owns the pointed input.

◆  GetSubstanceOutput()

void* GetSubstanceOutput ( BaseList2D *const  asset ,
void *const  graph ,
void *const  prevOutput ,
UInt32 &  outputUid ,
SUBSTANCE_OUTPUT_TYPE &  type ,
String &  name ,
BaseBitmap **  bmpPtr  
)

Retrieves a Substance input of an asset. This function may be used to iterate over the outputs of a graph of asset .

由于
R18
参数
[in] asset The Substance asset.
[in] graph The graph.
[in] prevOutput Pass nullptr to get the first output, pass an output pointer to get the following output.
[out] outputUid The unique ID of the output. Only valid if return value != nullptr .
[out] type The output type ID. Only valid if return value != nullptr .
[out] name The name of the returned output. Only valid if return value != nullptr .
[in,out] bmpPtr A pointer to a BaseBitmap pointer. If not nullptr , a pointer to a clone of the output channel bitmap will be returned here. The caller owns the pointed BaseBitmap .. Only valid if return value != nullptr .
返回
A pointer to identify the output, may not be dereferenced, Cinema 4D owns the pointed output., or nullptr if output is not available

◆  PrefsGetMaterialModeSetting()

SUBSTANCE_MATERIAL_MODE PrefsGetMaterialModeSetting ( )

Convenience function to get the material creation mode set in Substance preferences.

由于
R18
返回
The material creation mode: SUBSTANCE_MATERIAL_MODE

◆  PrefsGetPreviewSetting()

Int32 PrefsGetPreviewSetting ( )

Convenience function to get the preview mode for Content Browser set in Substance preferences.

由于
R18
返回
Zero for mosaic preview, otherwise rendered preview scene.

◆  MaterialUsesSubstance()

Bool MaterialUsesSubstance ( BaseMaterial *const  mat )

Checks if mat contains any Substance shaders.

由于
R18
参数
[in] mat The material to check for Substance shaders.
返回
true if the material uses a Substance shader, otherwise false .

◆  GetSubstanceMosaicPreview()

BaseBitmap * GetSubstanceMosaicPreview ( BaseList2D *const  asset ,
Int32   w ,
Int32   h  
)

Returns an image with previews of the output channels of asset .

由于
R18
注意
While the Substance asset won't have to be re-rendered, this operation still involves downscaling of all Substance outputs.
参数
[in] asset The Substance asset.
[in] w The width of the preview image.
[in] h The weight of the preview image.
返回
A pointer to the resulting bitmap. The caller owns the pointed BaseBitmap .

◆  UpdateImageInputPaths()

void UpdateImageInputPaths ( BaseList2D *const  asset ,
String &  path  
)

Private .

由于
R18

◆  CloneReferencedSubstances()

void CloneReferencedSubstances ( BaseDocument *const  doc ,
BaseShader *const  shd ,
BaseDocument *const  ddoc ,
BaseShader *const  dshd  
)

Private .

由于
R18

◆  CloneReferencedSubstancesObject()

void CloneReferencedSubstancesObject ( BaseDocument *const  docSrc ,
BaseObject *const  opSrc ,
BaseDocument *const  docDst ,
BaseObject *const  opDst  
)

Private .

由于
R18

◆  InsertSubstancePreviewScene()

void InsertSubstancePreviewScene ( BaseDocument *const  doc ,
BaseList2D *const  asset  
)

Private .

由于
R18

◆  GetContentBrowserOverlay()

const BaseBitmap * GetContentBrowserOverlay ( )

Returns the Substance logo bitmap. Private .

由于
R19
返回
The logo bitmap. Cinema 4D owns the pointed BaseBitmap .
SUBSTANCE_MATERIAL_MODE::METALLIC
@ METALLIC
Create metallic material.
String::HexToString
static String HexToString(UInt32 v, Bool prefix0x=true)
定义： c4d_string.h:478
GetFirstSubstance
BaseList2D * GetFirstSubstance(BaseDocument *const doc)
BaseList2D
定义： c4d_baselist.h:2144
GetActiveDocument
BaseDocument * GetActiveDocument(void)
SUBSTANCE_IMPORT_RESULT::SUCCESS
@ SUCCESS
Success.
GetSubstanceInput
void * GetSubstanceInput(BaseList2D *const asset, void *const graph, void *const prevInput, UInt32 &inputUid, Int32 &firstId, Int32 &numElements, SUBSTANCE_INPUT_TYPE &type, String &name)
UInt32
maxon::UInt32 UInt32
定义： ge_sys_math.h:59
CreateMaterial
BaseMaterial * CreateMaterial(BaseList2D *const asset, Int32 graphIndex, SUBSTANCE_MATERIAL_MODE mode)
Filename
Manages file and path names.
定义： c4d_file.h:93
AtomArray::GetCount
Int32 GetCount() const
定义： c4d_baselist.h:1619
GetSubstanceGraph
void * GetSubstanceGraph(BaseList2D *const asset, void *const prevGraph, String &name)
GePrint
void GePrint(const maxon::String &str)
ImportSubstance
SUBSTANCE_IMPORT_RESULT ImportSubstance(BaseDocument *const doc, const Filename &fn, SUBSTANCE_IMPORT_COPY ©File, Bool errPopup, Bool addUndo, Bool createMaterial, BaseList2D **assetPtr)
SUBSTANCE_OUTPUT_TYPE
SUBSTANCE_OUTPUT_TYPE
定义： lib_substance.h:314
String
定义： c4d_string.h:38
BaseDocument::InsertMaterial
void InsertMaterial(BaseMaterial *mat, BaseMaterial *pred=nullptr, Bool checknames=false)
GetSubstanceOutput
void * GetSubstanceOutput(BaseList2D *const asset, void *const graph, void *const prevOutput, UInt32 &outputUid, SUBSTANCE_OUTPUT_TYPE &type, String &name, BaseBitmap **bmpPtr)
String::IntToString
static String IntToString(Int32 v)
定义： c4d_string.h:495
SUBSTANCE_IMPORT_RESULT
SUBSTANCE_IMPORT_RESULT
定义： lib_substance.h:265
SUBSTANCE_MATERIAL_MODE
SUBSTANCE_MATERIAL_MODE
定义： lib_substance.h:251
SUBSTANCE_IMPORT_COPY::NO
@ NO
Do not copy file to project directory (absolute file path).
BaseDocument::StartUndo
Bool StartUndo(void)
Int32
maxon::Int32 Int32
定义： ge_sys_math.h:58
SUBSTANCE_INPUT_TYPE
SUBSTANCE_INPUT_TYPE
定义： lib_substance.h:291
BaseDocument::EndUndo
Bool EndUndo(void)
AutoAlloc
定义： ge_autoptr.h:36
GetSubstances
void GetSubstances(BaseDocument *const doc, AtomArray *arr, Bool onlySelected)
Bool
maxon::Bool Bool
定义： ge_sys_math.h:53
BaseList2D::GetName
String GetName() const
定义： c4d_baselist.h:2318
SUBSTANCE_IMPORT_COPY
SUBSTANCE_IMPORT_COPY
定义： lib_substance.h:279
BaseMaterial
定义： c4d_basematerial.h:27
BaseDocument
定义： c4d_basedocument.h:490
AtomArray::GetIndex
C4DAtom * GetIndex(Int32 idx) const
定义： c4d_baselist.h:1634

Copyright  © 2014-2025 乐数软件    

工业和信息化部： 粤ICP备14079481号-1