maxon::nodes::NODESPACE Namespace Reference

Detailed Description

The following attributes are constructed by Cinema4d and available for query.

The following attributes should be passed to the NodeSpaceInterface::Init() function and be available for query via NodeSpaceInterface::GetData() .

Typedefs
using	CreateMaterialGraphFunc = Delegate< Result< void >(const NodesGraphModelRef &graph)>
using	ConfigurePreviewImageRequestFunc = Delegate< Result< void >(DataDictionaryObjectRef request)>
using	ImageNodePortTuple = HomogenousTupleType< 4, NodePath >
using	LayerSetUrlDelegate = Delegate< Result< Url >(const GraphNode &)>
using	ImageNodeSetupDelegate = Delegate< Result< void >(const GraphNode &, const Url &)>
using	MaterialMessageHandlerFunc = Delegate< Result< Bool >(const NodesGraphModelRef &graph, Int32 messageId, void *messageData, void *nodeMaterial)>

Enumerations
enum class	KIND {   MATERIAL ,   SCENE }

Functions
	MAXON_ATTRIBUTE (Id, SPACEID, "net.maxon.nodes.nodespace.spaceid")
	MAXON_ATTRIBUTE (String, SPACENAME, "net.maxon.nodes.nodespace.spacename")
	MAXON_ATTRIBUTE (Array< Int >, RENDERERS, "net.maxon.nodes.nodespace.renderers")
enum maxon::nodes::NODESPACE::KIND	MAXON_ENUM_LIST (KIND)
	MAXON_ATTRIBUTE (KIND, SPACEKIND, "net.maxon.nodes.nodespace.kind")
	MAXON_ATTRIBUTE (CreateMaterialGraphFunc, CREATEMATERIALGRAPHFUNC, "net.maxon.nodes.nodespace.creatematerialgraphfunc")
	MAXON_ATTRIBUTE (ConfigurePreviewImageRequestFunc, CONFIGUREPREVIEWIMAGEREQUESTFUNC, "net.maxon.nodes.nodespace.configurepreviewimagerequestfunc")
	MAXON_ATTRIBUTE (Array< Id >, MATERIALENDNODEIDS, "net.maxon.nodes.nodespace.materialendnodeids")
	MAXON_ATTRIBUTE (Array< Id >, MATERIALPREVIEWIDS, "net.maxon.nodes.nodespace.materialpreviewids")
	MAXON_ATTRIBUTE (NodeSystemClass, NODESYSTEMCLASS, "net.maxon.nodes.nodespace.nodesystemclass")
	MAXON_ATTRIBUTE (Class< NimbusRef >, NIMBUSCLASS, "net.maxon.nodes.nodespace.nimbusclass")
	MAXON_ATTRIBUTE (Array< Id >, MATERIALEXCHANGEBUNDLEIDS, "net.maxon.nodes.nodespace.materialexchangebundleids")
	MAXON_ATTRIBUTE (Class< MaterialExchangeRef >, MATERIALEXCHANGECLASS, "net.maxon.nodes.nodespace.materialexchangeclass")
	MAXON_ATTRIBUTE (Class< NodeMaterialImportRef >, NODEMATERIALIMPORTCLASS, "net.maxon.nodes.nodespace.nodematerialimportclass")
	MAXON_ATTRIBUTE (Class< NodeMaterialExportRef >, NODEMATERIALEXPORTCLASS, "net.maxon.nodes.nodespace.nodematerialexportclass")
	MAXON_ATTRIBUTE (Id, IMAGENODEASSETID, "net.maxon.nodes.nodespace.imagenodeassetid")
	MAXON_ATTRIBUTE (ImageNodePortTuple, IMAGENODEPORTS, "net.maxon.nodes.nodespace.IMAGENODEPORTS")
	MAXON_ATTRIBUTE (LayerSetUrlDelegate, LAYERSETURL, "net.maxon.nodes.nodespace.layerseturl")
	MAXON_ATTRIBUTE (ImageNodeSetupDelegate, IMAGENODESETUP, "net.maxon.nodes.nodespace.imagenodesetup")
	MAXON_ATTRIBUTE (MaterialMessageHandlerFunc, MATERIALMESSAGEHANDLERFUNC, "net.maxon.nodes.nodespace.materialmessagehandlerfunc")
	MAXON_ATTRIBUTE (Bool, DISABLE_PREVIEWS, "net.maxon.nodes.nodespace.disablepreviews")
	MAXON_ATTRIBUTE (NodePath, STARTNODEPATH, "net.maxon.nodes.nodespace.startnodepath")
	MAXON_ATTRIBUTE (NodePath, SOLONODEPATH, "net.maxon.nodes.nodespace.solonodepath")
	MAXON_ATTRIBUTE (Url, DOCUMENTPATH, "net.maxon.nodes.nodespace.documentpath")
	MAXON_ATTRIBUTE (DataDictionary, NodeSpaceContext, "net.maxon.nodes.nodespace.nodespacecontext")

Typedef Documentation

CreateMaterialGraphFunc

using CreateMaterialGraphFunc = Delegate<Result<void>(const NodesGraphModelRef& graph)>

This callback is executed for the active space if a node material is created, and for the user-selected add space command.

The provided function has exclusive write access and can instantiate nodes the following:

iferr_scope;
 
maxon::nodes::NodeTemplate endNodeSystem = maxon::nodes::NodesLib::LoadTemplate(maxon::AssetInterface::GetBuiltinRepository(), maxonexample::NODE::ENDNODE::GetId()) iferr_return;
maxon::GraphNode endGraphNode = graph.AddChild(maxon::Id("end node instance"), endNodeSystem) iferr_return;
 
return maxon::OK;

Parameters

[in,out]

graph

The empty node graph for filling with a default setup.

Returns

OK on success.

Future consideration: we may extend the signature of this function by providing read-only access to other node graphs that are already present in the particular material. This may fulfill the use case for migrating a node material from one space to another. The implementer would then be able to implement a (complex and lossy) conversion from another source node graph (from another space) to the target node space.

ConfigurePreviewImageRequestFunc

using ConfigurePreviewImageRequestFunc = Delegate<Result<void>(DataDictionaryObjectRef request)>

This callback is executed for the active space if a preview for the current node material is requested. The origin of the preview may lie in GUI components such as the Attribute Manager, Node Editor, or Material Manager.

It is mandatory to provide a valid maxon::nodes::PREVIEWIMAGEREQUEST::PROVIDER class.

Parameters

[in,out]

request

The container to be filled that is passed into PreviewImageProviderInterface::Initialize() function later.

Returns

OK on success.

ImageNodePortTuple

using ImageNodePortTuple = HomogenousTupleType<4, NodePath>

LayerSetUrlDelegate

using LayerSetUrlDelegate = Delegate<Result<Url>(const GraphNode&)>

ImageNodeSetupDelegate

using ImageNodeSetupDelegate = Delegate<Result<void>(const GraphNode&, const Url&)>

MaterialMessageHandlerFunc

using MaterialMessageHandlerFunc = Delegate<Result<Bool>(const NodesGraphModelRef& graph, Int32 messageId, void* messageData, void* nodeMaterial)>

Is executed on every message that sent to the owning BaseMaterial. This message may be used to react and mutate the graph.

The node material comes with a default message handling behavior that can be disabled when returning true (indicating complete consume of the message). Note that the default behavior handles the undo system and other state changes outside of the node graph.

Parameters

[in]	graph	The node graph associated with the particular space.
[in]	messageId	The id of the message.
[in]	messageData	The (opaque) content of the message.
[in]	nodeMaterial	The (opaque) pointer to the BaseMaterial (of type NodeMaterial).

Returns

true if message is declared consumed, false if default consume behavior should follow.

Enumeration Type Documentation

KIND

enum KIND

strong

An enum to represent the different node space kinds (such as materials or scene nodes).

Enumerator
MATERIAL	The node space is used for materials.
SCENE	The node space is used for scene nodes.

Function Documentation

MAXON_ATTRIBUTE() [1/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Id	,
		SPACEID	,
		"net.maxon.nodes.nodespace.spaceid"
	)

Defines the identifier for all space-related data, such as node graph storage within C4D files.

MAXON_ATTRIBUTE() [2/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	String	,
		SPACENAME	,
		"net.maxon.nodes.nodespace.spacename"
	)

Defines the GUI-visible string for the space-related components, such as node space switch and the Basic tab of node materials.

MAXON_ATTRIBUTE() [3/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Array< Int >	,
		RENDERERS	,
		"net.maxon.nodes.nodespace.renderers"
	)

Defines the list of renderers that support the node space. Multiple renderers may be supported. This is the case for the MaterialNodeSpaces::Standard space which is supported by Standard renderer, Physical Renderer and Hardware Renderer.

However it is invalid to have multiple spaces that indicate support for one particular renderer. In such a case, the "Current (Renderer)" binding is ambiguous and made with no well-defined priority.

MAXON_ENUM_LIST()

enum maxon::nodes::NODESPACE::KIND maxon::nodes::NODESPACE::MAXON_ENUM_LIST

(

KIND

)

MAXON_ATTRIBUTE() [4/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	KIND	,
		SPACEKIND	,
		"net.maxon.nodes.nodespace.kind"
	)

Defines the node space kind of this node space.

MAXON_ATTRIBUTE() [5/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	CreateMaterialGraphFunc	,
		CREATEMATERIALGRAPHFUNC	,
		"net.maxon.nodes.nodespace.creatematerialgraphfunc"
	)

MAXON_ATTRIBUTE() [6/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	ConfigurePreviewImageRequestFunc	,
		CONFIGUREPREVIEWIMAGEREQUESTFUNC	,
		"net.maxon.nodes.nodespace.configurepreviewimagerequestfunc"
	)

MAXON_ATTRIBUTE() [7/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Array< Id >	,
		MATERIALENDNODEIDS	,
		"net.maxon.nodes.nodespace.materialendnodeids"
	)

The set of asset identifiers for end nodes. An end node acts as an entry point to the node graph within the Attribute Manager, if no specific start node has been specified by the user. Multiple identifiers should be defined in ascending priority order. A node instance of the first Id type is preferred for ambiguous cases.

MAXON_ATTRIBUTE() [8/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Array< Id >	,
		MATERIALPREVIEWIDS	,
		"net.maxon.nodes.nodespace.materialpreviewids"
	)

The set of Ids that require a 3d preview along with the user choice over the 3d scene. It can be expected that a valid value for maxon::nodes::PREVIEW::SCENETYPE is then provided to PreviewImageProviderInterface::Initialize().

MAXON_ATTRIBUTE() [9/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	NodeSystemClass	,
		NODESYSTEMCLASS	,
		"net.maxon.nodes.nodespace.nodesystemclass"
	)

The type of node system this space supports. The node system defines which types of nodes are available for the user in the GUI for the particular node space. Node instances are bound to one node system class.

MAXON_ATTRIBUTE() [10/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Class< NimbusRef >	,
		NIMBUSCLASS	,
		"net.maxon.nodes.nodespace.nimbusclass"
	)

The class to use for the NimbusRef of this node space.

MAXON_ATTRIBUTE() [11/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Array< Id >	,
		MATERIALEXCHANGEBUNDLEIDS	,
		"net.maxon.nodes.nodespace.materialexchangebundleids"
	)

Defines the collection of compatible material types.

MAXON_ATTRIBUTE() [12/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Class< MaterialExchangeRef >	,
		MATERIALEXCHANGECLASS	,
		"net.maxon.nodes.nodespace.materialexchangeclass"
	)

Defines which component implementing the maxon::nodes::MaterialExchangeInterface is queried for the representation of the node material in the viewport and for exchange purposes like material export.

MAXON_ATTRIBUTE() [13/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Class< NodeMaterialImportRef >	,
		NODEMATERIALIMPORTCLASS	,
		"net.maxon.nodes.nodespace.nodematerialimportclass"
	)

This callback is executed on import of material data, potentially from a file format such as FBX or by migrating data from one space to another.

MAXON_ATTRIBUTE() [14/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Class< NodeMaterialExportRef >	,
		NODEMATERIALEXPORTCLASS	,
		"net.maxon.nodes.nodespace.nodematerialexportclass"
	)

This callback is executed on export of material data, potentially from a file format such as FBX or by migrating data from one space to another. If not provided, the export will fallback to the extraction of the material definition provided for viewport display.

MAXON_ATTRIBUTE() [15/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Id	,
		IMAGENODEASSETID	,
		"net.maxon.nodes.nodespace.imagenodeassetid"
	)

Defines the type of node that acts as an image / texture node. An instance of this type is created if users drag & drop an image onto the ports connectors or the Node Editor canvas.

MAXON_ATTRIBUTE() [16/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	ImageNodePortTuple	,
		IMAGENODEPORTS	,
		"net.maxon.nodes.nodespace.IMAGENODEPORTS"
	)

Makes a set of ports on the image / texture node type known to Cinema4D's business logic. For each port you have to specify the relative node path within its port list, so for the simple case of a non-nested path you have to specify a path of just one identifier.

The four ports must have the following signature:

Index in Tuple | Port Type | Data Type | Description

0 | Output Port | maxon::Color | The result port. 1 | Input Port | maxon::Url | The URL of the input image. 2 | Input Port | maxon::Int | The index of the starting frame. 3 | Input Port | maxon::Int | The index of the ending frame.

The setup could be the following:

nodes::NODESPACE::ImageNodePortTuple imageTuple;
imageTuple.first = NodePath::Create(ToSingletonBlock<InternedId>(MYSPACE::NODE::IMAGE::RESULT)) iferr_return;
imageTuple.second = NodePath::Create(ToSingletonBlock<InternedId>(MYSPACE::NODE::IMAGE::URL)) iferr_return;
imageTuple.third = NodePath::Create(ToSingletonBlock<InternedId>(MYSPACE::NODE::IMAGE::SEQUENCE_FRAMESTART)) iferr_return;
imageTuple.fourth = NodePath::Create(ToSingletonBlock<InternedId>(MYSPACE::NODE::IMAGE::SEQUENCE_FRAMEEND)) iferr_return;
spaceData.Set(nodes::NODESPACE::IMAGENODEPORTS, std::move(imageTuple)) iferr_return;

MAXON_ATTRIBUTE() [17/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	LayerSetUrlDelegate	,
		LAYERSETURL	,
		"net.maxon.nodes.nodespace.layerseturl"
	)

A node space can set this property if it wants to use the built-in layerset UI for more than the image node. The layerset UI calls the delegate to obtain the Url to use for the given layerset port. For example, if the layerset port is in a port bundle which also contains a Url port with id "url", you can use code like this:

nodes::NODESPACE::LayerSetUrlDelegate d = [] (const GraphNode& port) -> Result<Url>
{
  iferr_scope;
  GraphNode urlPort = port.GetParent().FindChild(Id("url")) iferr_return;
  if (urlPort.IsValid())
  {
    return urlPort.GetDefaultValue(Url());
  }
  return {};
};
spaceData.Set(nodes::NODESPACE::LAYERSETURL, std::move(d)) iferr_return;

If the node space doesn't set this property or if the delegate returns an empty Url, the port determined by IMAGENODEPORTS is used as fallback.

MAXON_ATTRIBUTE() [18/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	ImageNodeSetupDelegate	,
		IMAGENODESETUP	,
		"net.maxon.nodes.nodespace.imagenodesetup"
	)

A node space can set this property if it wants to handle the setup of an image node for a given Url. The delegate receives the GraphNode of a newly create image node and the Url to use. Before the delegate is called, the ports determined by IMAGENODEPORTS have been set up (Url, start and end frame).

MAXON_ATTRIBUTE() [19/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	MaterialMessageHandlerFunc	,
		MATERIALMESSAGEHANDLERFUNC	,
		"net.maxon.nodes.nodespace.materialmessagehandlerfunc"
	)

MAXON_ATTRIBUTE() [20/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Bool	,
		DISABLE_PREVIEWS	,
		"net.maxon.nodes.nodespace.disablepreviews"
	)

A node space can set this property to true to completely disable previews in the node editor.

MAXON_ATTRIBUTE() [21/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	NodePath	,
		STARTNODEPATH	,
		"net.maxon.nodes.nodespace.startnodepath"
	)

Defines the path to the currently defined start node, as used in the Attribute Manager.

MAXON_ATTRIBUTE() [22/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	NodePath	,
		SOLONODEPATH	,
		"net.maxon.nodes.nodespace.solonodepath"
	)

Defines the path to the currently defined solo node, as used in the Node Editor and Viewport.

MAXON_ATTRIBUTE() [23/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	Url	,
		DOCUMENTPATH	,
		"net.maxon.nodes.nodespace.documentpath"
	)

Defines the directory of the owning BaseDocument. This path may help resolving absolute paths to assets defined in a relative fashion, such as images.

MAXON_ATTRIBUTE() [24/24]

maxon::nodes::NODESPACE::MAXON_ATTRIBUTE	(	DataDictionary	,
		NodeSpaceContext	,
		"net.maxon.nodes.nodespace.nodespacecontext"
	)

Defines a generic data container that exists on root GraphNode of every material node graph. It defines the connection between the node space-agnostic node graph and the space-specific embedding of the node graph into Cinema4d business logic.

Its content is currently restricted to supports maxon::nodes::NODESPACE::SPACEID supports maxon::nodes::NODESPACE::SOLONODEPATH supports maxon::nodes::NODESPACE::DOCUMENTPATH

The data can be extracted as such from a graph:

const maxon::DataDictionary graphContext = graph.GetRoot().GetValue(maxon::nodes::NODESPACE::NodeSpaceContext).GetValueOrNull() iferr_return;
const maxon::Url documentPath = graphContext.Get(maxon::nodes::NODESPACE::DOCUMENTPATH, maxon::Url());