MaterialExchangeInterface Class Reference

#include <nodematerialexchange.h>

Inheritance diagram for MaterialExchangeInterface:

Detailed Description

MaterialExchangeInterface defines the external representation of a node material. If not specifically defined for a node space, all node materials are assumed to be gray dielectric materials for viewport and export purposes.

You may derive from this interface and indicate support for particular material types in your node space the following:

maxon::BaseArray<maxon::Id> materialExchangeBundleIds;
materialExchangeBundleIds.Append(maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::GetId()) iferr_return;
spaceData.Set(maxon::nodes::NODESPACE::MATERIALEXCHANGEBUNDLEIDS, std::move(materialExchangeBundleIds)) iferr_return;
spaceData.Set(maxon::nodes::NODESPACE::MATERIALEXCHANGECLASS, NodeSpaceViewportMaterialExample::GetClass()) iferr_return;
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:628
#define iferr_return
Definition: resultbase.h:1524

Currently, the material types are declared in the file "datadescription_node_spaces.h" as port bundles As of R21.1, only the "maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL" is used, solely for viewport representation. However, this may change in the future, we may export the delivered parameters into various output formats such as OBJ or FBX without any further requirements from the component. In addition, we may consider supporting differing bundle types that will enhance the visual quality by the viewport, for example Disney Principled BRDF, Standard Surface, or USD Preview Surface. Furthermore, we may offer the ability the extend this material collection dynamically to offer a quality-optimized export to a particular output format, e.g. GLTF.

The lifetime of MaterialExchangeRef instances is managed by C4D. Generally, a space-specific instance is constructed for each node material. However, it may be rather short-living.

The instance is released if a space is switched from, or created respectively when toggling the active space in the GUI.

It is also released and recreated if the topology of the material changes, for example enabling the solo mode on a node flushes all cached textures and results in a new MaterialExchangeRef instantiation.

The MaterialExchangeRef is kept alive over parameter changes. Effectively, such a change is assumed to be a gradual / continuous change from the previously displayed state of the material.

Public Member Functions

MAXON_METHOD Result< void > Initialize (const Id &intent, const Id &materialType, const NodesGraphModelRef &graph, const NodePath &endNodePath, const NodePath &soloNodePath)
 
MAXON_METHOD Result< DataDictionary > GetMaterialParameters ()
 
MAXON_METHOD Result< void > ConfigureTextureProviderRequest (DataDictionaryObjectRef request)
 

Static Public Member Functions

template<typename TYPE , typename KEY >
static Result< TypedMaterialParameter< TYPE > > Extract (const DataDictionaryInterface &parameters, KEY &&id)
 
template<typename TYPE , typename KEY >
static Result< TypedMaterialParameter< TYPE > > Extract (const DataDictionary &parameters, KEY &&id)
 
template<typename T , typename KEY >
static Result< void > Insert (DataDictionary &parameters, KEY &&id, T &&value, Bool isConstant, UInt dynamicTimestamp)
 
template<typename KEY >
static Result< void > InsertData (DataDictionary &parameters, KEY &&id, Data &&dataValue, Bool isConstant, UInt dynamicTimestamp)
 
static MAXON_METHOD Result< DataDictionary > LoadMaterialDefaults (const Id &materialType)
 

Private Member Functions

 MAXON_INTERFACE (MaterialExchangeInterface, MAXON_REFERENCE_NORMAL, "net.maxon.nodes.interface.materialexchangeinterface")
 

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE ( MaterialExchangeInterface  ,
MAXON_REFERENCE_NORMAL  ,
"net.maxon.nodes.interface.materialexchangeinterface"   
)
private

◆ Extract() [1/2]

static Result<TypedMaterialParameter<TYPE> > Extract ( const DataDictionaryInterface parameters,
KEY &&  id 
)
static

Extracts / gets an typed parameter from a DataDictionaryInterface object with type check between the requested value type and the attribute's type.

Template Parameters
TYPEThe value type of the parameter.
KEYThe type of the key attribute.
Parameters
[in]parametersThe DataDictionary holding the parameter.
[in]idThe parameter's attribute id.
Returns
The typed parameter on success.

◆ Extract() [2/2]

static Result<TypedMaterialParameter<TYPE> > Extract ( const DataDictionary &  parameters,
KEY &&  id 
)
static

Extracts / gets an typed parameter from a DataDictionary with type check between the requested value type and the attribute's type.

Template Parameters
TYPEThe value type of the parameter.
KEYThe type of the key attribute.
Parameters
[in]parametersThe DataDictionary holding the parameter.
[in]idThe parameter's attribute id.
Returns
The typed parameter on success. For example, a base color can be extracted the following:
maxon::nodes::TypedMaterialParameter<Color> baseColor = maxon::nodes::MaterialExchangeInterface::Extract<Color>(parameters, maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::BASE_COLOR) iferr_return;
#define parameters
Definition: graminit.h:11
Definition: nodematerialexchange.h:66

◆ Insert()

static Result<void> Insert ( DataDictionary &  parameters,
KEY &&  id,
T &&  value,
Bool  isConstant,
UInt  dynamicTimestamp 
)
static

Inserts a typed parameter into the provided DataDictionary with type check between the provided value and the attribute's type.

Template Parameters
KEYThe type of the key attribute.
Parameters
[out]parametersThe DataDictionary to hold on the parameter.
[in]idThe parameter's attribute id.
[in]valueThe typed constant / default value of the parameter.
[in]isConstantTrue if the parameter is constant (and requires no texture-driven representation).
[in]dynamicTimestampThe timestamp of the texture-driven representation.
Returns
OK on success. For example, a red base color can be inserted the following:
maxon::nodes::MaterialExchangeInterface::Insert(parameters, maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::BASE_COLOR, Color(1, 0, 0), true, 0) iferr_return;
static Result< void > Insert(DataDictionary &parameters, KEY &&id, T &&value, Bool isConstant, UInt dynamicTimestamp)
Definition: nodematerialexchange.h:204
Col3< Float, 1 > Color
Definition: vector.h:84

◆ InsertData()

static Result<void> InsertData ( DataDictionary &  parameters,
KEY &&  id,
Data &&  dataValue,
Bool  isConstant,
UInt  dynamicTimestamp 
)
static

Inserts an opaque parameter into the provided DataDictionary.

Template Parameters
KEYThe type of the key attribute.
Parameters
[out]parametersThe DataDictionary to hold on the parameter.
[in]idThe parameter's attribute id.
[in]dataValueThe opaque constant / default value of the parameter.
[in]isConstantTrue if the parameter is constant (and requires no texture-driven representation).
[in]dynamicTimestampThe timestamp of the texture-driven representation.
Returns
OK on success.

◆ LoadMaterialDefaults()

static MAXON_METHOD Result<DataDictionary> LoadMaterialDefaults ( const Id materialType)
static

Loads and parses the data description of material and inserts the defined default values into a DataDictionary. This method caches once-loaded description for performance.

Parameters
[in]materialTypeThe (bundle) type of the material representation.
Returns
The parameter set on success.

◆ Initialize()

MAXON_METHOD Result<void> Initialize ( const Id intent,
const Id materialType,
const NodesGraphModelRef &  graph,
const NodePath &  endNodePath,
const NodePath &  soloNodePath 
)

Initializes the exchange representation for a node material. This method is called immediately after a change to the node graph by the viewport. In this method it is safe to access the original node graph.

Parameters
[in]intentThe intention behind the material exchange request.
[in]materialTypeThe (bundle) type of the external material representation.
[in]graphThe node graph of the node material.
[in]endNodePathThe path to the end node as it is known to C4D.
[in]soloNodePathThe path to the solo node as it is known to C4D.
Returns
OK on success.

◆ GetMaterialParameters()

MAXON_METHOD Result<DataDictionary> GetMaterialParameters ( )

Fetches the parameters for the external material representation. The returned container is expected to be populated with the appropriate configuration for all bundle members. Parameters that are marked as non-constant may result in a texture baking request through ConfigureTextureProviderRequest() later on if demanded by the viewport, or by the export functionality. In this method it is safe to access the original node graph.

◆ ConfigureTextureProviderRequest()

MAXON_METHOD Result<void> ConfigureTextureProviderRequest ( DataDictionaryObjectRef  request)

Offers configuration of the preview request. The call to this function is made during viewport redraw if any non-constant texture-driven value is demanded.

In this method it is not safe to access the original node graph.

It expected that the attribute maxon::nodes::PREVIEWIMAGEREQUEST::PROVIDER is defined, e.g.

request.Set(maxon::nodes::PREVIEWIMAGEREQUEST::PROVIDER, ViewportTextureProviderExample::GetClass()) iferr_return;
Parameters
[in,out]requestThe data container of the preview request that is handed over to the PreviewImageProviderInterface::Initialize() method.
Returns
OK on success.