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;

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

TYPE	The value type of the parameter.
KEY	The type of the key attribute.

Parameters

[in]	parameters	The DataDictionary holding the parameter.
[in]	id	The 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

TYPE	The value type of the parameter.
KEY	The type of the key attribute.

Parameters

[in]	parameters	The DataDictionary holding the parameter.
[in]	id	The 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;

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

KEY	The type of the key attribute.

Parameters

[out]	parameters	The DataDictionary to hold on the parameter.
[in]	id	The parameter's attribute id.
[in]	value	The typed constant / default value of the parameter.
[in]	isConstant	True if the parameter is constant (and requires no texture-driven representation).
[in]	dynamicTimestamp	The 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;

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

KEY	The type of the key attribute.

Parameters

[out]	parameters	The DataDictionary to hold on the parameter.
[in]	id	The parameter's attribute id.
[in]	dataValue	The opaque constant / default value of the parameter.
[in]	isConstant	True if the parameter is constant (and requires no texture-driven representation).
[in]	dynamicTimestamp	The 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]

materialType

The (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]	intent	The intention behind the material exchange request.
[in]	materialType	The (bundle) type of the external material representation.
[in]	graph	The node graph of the node material.
[in]	endNodePath	The path to the end node as it is known to C4D.
[in]	soloNodePath	The 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]

request

The data container of the preview request that is handed over to the PreviewImageProviderInterface::Initialize() method.

Returns

OK on success.