#include <c4d_materialdata.h>

Inheritance diagram for MaterialData:

[legend]

Detailed Description

A data class for creating material plugins.

See also: ShaderData

Use RegisterMaterialPlugin() to register a material plugin.

General notes
Here are some general comments on the material API:

Coordinate Systems: if there is no further note, all elements like points, normals etc. are always given in global coordinates.
Angle Systems: all angle values are always given in radians. Use maxon::RadToDeg macro for conversion if needed.
Vectors: all normals and ray vectors must be normalized. Also, all normals and ray vectors received from Cinema 4D are normalized.
Functions: no OS calls are allowed for CalcSurface, CalcVolumetric, Displace, ChangeNormal, CalcTransparency, and CalcAlpha. (These can be called within MP thread contexts.)
Radiosity: Cinema 4D automatically handles radiosity for shaders, but a description interface for the radiosity IDs must be provided manually. Please refer to the SimpleShader SDK example. Note that this means that IDs in the 1000 range are reserved, so start the material IDs above 2000.

Optimization
CalcSurface, CalcVolumetric, ChangeNormal, CalcTransparency and CalcAlpha are the speed critical routines; concentrate efforts optimizing them.
Do not allocate new classes in those routines; only if absolutely necessary! Most of classes can be pre-allocated in InitRender::
Avoid ANY function calls there. For instance to access the global render settings store the pointer in InitRender for later use. This can save a tremendous amount of time.

Public Member Functions
virtual Bool	Draw (BaseMaterial mat, BaseObject op, BaseTag tag, BaseDraw bd, BaseDrawHelp *bh)

virtual VOLUMEINFO	GetRenderInfo (BaseMaterial *mat)

virtual INITRENDERRESULT	InitRender (BaseMaterial *mat, const InitRenderStruct &irs)

virtual void	FreeRender (BaseMaterial *mat)

virtual void	InitCalculation (BaseMaterial mat, VolumeData vd, INITCALCULATION type)

virtual void	Displace (BaseMaterial mat, VolumeData vd)

virtual void	ChangeNormal (BaseMaterial mat, VolumeData vd)

virtual void	CalcSurface (BaseMaterial mat, VolumeData vd)

virtual void	CalcTransparency (BaseMaterial mat, VolumeData vd)

virtual void	CalcAlpha (BaseMaterial mat, VolumeData vd)

virtual void	CalcVolumetric (BaseMaterial mat, VolumeData vd)

virtual Bool	InitGLImage (BaseMaterial mat, BaseDocument doc, BaseThread th, BaseBitmap bmp, Int32 doccolorspace, Bool linearworkflow)

virtual UInt32	GlMessageDummy (BaseMaterial mat, Int32 type, void data)

virtual Bool	HasEditorTransparency (BaseMaterial *mat)

Public Member Functions inherited from NodeData
	NodeData ()

GeListNode *	Get ()

const GeListNode *	Get () const

virtual Bool	Message (GeListNode node, Int32 type, void data)

virtual void	GetBubbleHelp (GeListNode *node, maxon::String &str)

virtual const BaseDocument *	GetDocument (const GeListNode *node) const

virtual maxon::Result< Bool >	GetBranchInfo (const GeListNode *node, const maxon::ValueReceiver< const BranchInfo & > &info, GETBRANCHINFO flags) const

virtual Bool	IsInstanceOf (const GeListNode *node, Int32 type) const

virtual Bool	IsDocumentRelated (const GeListNode *node, Bool &docrelated) const

virtual maxon::Result< Bool >	GetAccessedObjects (const BaseList2D *node, METHOD_ID method, AccessedObjectsCallback &access) const

virtual maxon::Result< maxon::GenericData >	GroupChanges (BaseList2D *node)

virtual Bool	Init (GeListNode *node, Bool isCloneInit)

virtual void	Free (GeListNode *node)

virtual Bool	Read (GeListNode node, HyperFile hf, Int32 level)

virtual Bool	Write (const GeListNode node, HyperFile hf) const

virtual Bool	CopyTo (NodeData dest, const GeListNode snode, GeListNode dnode, COPYFLAGS flags, AliasTrans trn) const

virtual Bool	GetDDescription (const GeListNode node, Description description, DESCFLAGS_DESC &flags) const

virtual Bool	GetDParameter (const GeListNode *node, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags) const

virtual Bool	SetDParameter (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)

virtual Bool	GetDEnabling (const GeListNode node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer itemdesc) const

virtual Bool	TranslateDescID (GeListNode node, const DescID &id, DescID &res_id, C4DAtom &res_at)

Public Member Functions inherited from BaseData
virtual	~BaseData ()

void	Destructor ()

Additional Inherited Members
Protected Attributes inherited from NodeData
GeListNode *	private_link

Member Function Documentation

◆ Draw()

virtual Bool Draw	(	BaseMaterial *	mat,
		BaseObject *	op,
		BaseTag *	tag,
		BaseDraw *	bd,
		BaseDrawHelp *	bh
	)

virtual

Called to draw additional information for the material in the editor. Called for every op/tag pair that references the material.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]	op	The object associated with the material. Cinema 4D owns the pointed object.
[in]	tag	The material tag. The caller owns the pointed tag.
[in]	bd	The editor's view. The caller owns the pointed view.
[in]	bh	The helper for the editor's view. The caller owns the pointed base draw helper.

Returns: true if successful, otherwise false.

◆ GetRenderInfo()

virtual VOLUMEINFO GetRenderInfo ( BaseMaterial * mat )

virtual

Called to get information about what the material plugin requires from the raytracer and what it returns.

Parameters

[in] mat The BaseMaterial connected with the MaterialData instance. Equal to static_cast<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.

Returns: The volume info: VOLUMEINFO

◆ InitRender()

virtual INITRENDERRESULT InitRender	(	BaseMaterial *	mat,
		const InitRenderStruct &	irs
	)

virtual

Called to initialize resources for rendering.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]	irs	A struct with information about the upcoming rendering.

Returns: The result of the initialization: INITRENDERRESULT

◆ FreeRender()

virtual void FreeRender ( BaseMaterial * mat )

virtual

Called to free any resources allocated in InitRender.

Parameters

[in] mat The BaseMaterial connected with the MaterialData instance. Equal to static_cast<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.

◆ InitCalculation()

virtual void InitCalculation	(	BaseMaterial *	mat,
		VolumeData *	vd,
		INITCALCULATION	type
	)

virtual

Called every time a new series of shader calls is made.
In InitCalculation precalculate values for the following calls. Store the resulting data for each processor (vd->GetCurrentCPU()) separately because InitCalculation may be entered multiple times on a MP thread contexts.
If all the routines are overridden and the flags are set properly Cinema 4D calls them in this order:

Before rendering:

InitRender() and GetRenderInfo()
InitCalculation(INITCALCULATION::DISPLACEMENT)
Displace()

During rendering:

InitCalculation(INITCALCULATION::SURFACE)
CalcAlpha()
ChangeNormal()
CalcSurface()
CalcVolumetric()

During rendering for e.g. shadow rays:

InitCalculation(INITCALCULATION::TRANSPARENCY)
CalcAlpha()

CalcTransparency()

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]	vd	The volume data to use. The caller owns the pointed volume data.
[in]	type	The upcoming call sequence: INITCALCULATION

◆ Displace()

virtual void Displace	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to displace a point on the surface.
Modify vd->p. Usually it elevates the point along its normal a certain extent such as vd->p += vd->dispn * factor.
Called after the render initialization (InitRender) but during the beginning phase.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ ChangeNormal()

virtual void ChangeNormal	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to create a bump effect.
Modify vd->bumpn. If VOLUMEINFO::DUDVREQUIRED was set for the material registration then use vd->ddu and vd->ddv as modification directions perpendicular to the face normal.
Called during rendering. See InitCalculation for the order of calls.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ CalcSurface()

virtual void CalcSurface	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to calculate the surface color.
Set vd->col, vd->trans and vd->refl. Also vd->rray and vd->tray (the reflecting and transparent rays) can be modified.
Called during rendering. See InitCalculation for the order of calls.

Note: vd->tray is only valid if VOLUMEINFO::TRANSPARENCY was set for the material registration, and vd->rray is only valid if VOLUMEINFO::REFLECTION or VOLUMEINFO::ENVREQUIRED was set.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ CalcTransparency()

virtual void CalcTransparency	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to speed up the transparency calculation.
Several times Cinema 4D needs the transparency information, for example for fast shadow calculation.
Set vd->trans. Use vd->xlight to find out which light is being evaluated.
If this routine is not supplied then the result will be slower shadow calculations.
Called during rendering. See InitCalculation for the order of calls.

Note: vd->tray is not valid and must not be modified.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ CalcAlpha()

virtual void CalcAlpha	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to calculate the alpha.
Set vd->alpha.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ CalcVolumetric()

virtual void CalcVolumetric	(	BaseMaterial *	mat,
		VolumeData *	vd
	)

virtual

Called to calculate volumetric information.

Note: If VOLUMEINFO::VOLUMETRIC is not set for the material registration this function is not needed. If VOLUMEINFO::VOLUMETRIC is set this function is required.
Set vd->col and vd->trans.
Called for spans; vd->ray->p to vd->p where vd->ray->p is the entry point and vd->p is the exit point.
Volumetric shaders that do not have a surface calculation can set vd->trans = vector(1.0) in CalcSurface and CalcTransparency::
Called during rendering. See InitCalculation for the order of calls.

Warning: No OS calls are allowed during this function. Doing so could cause a crash, since it can be called in a multi-processor context.

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in,out]	vd	The volume data to use and modify. The caller owns the pointed volume data.

◆ InitGLImage()

virtual Bool InitGLImage	(	BaseMaterial *	mat,
		BaseDocument *	doc,
		BaseThread *	th,
		BaseBitmap *	bmp,
		Int32	doccolorspace,
		Bool	linearworkflow
	)

virtual

Called to return a 2D representation of the material for use in the editor.
The image is shown both in OpenGL and Software mode.

Note: After you set the content of the image you have to call BaseBitmap::SetDirty().

Parameters

[in]	mat	The BaseMaterial connected with the MaterialData instance. Equal to `static_cast`<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]	doc	The document. The caller owns the pointed document.
[in]	th	The thread. The caller owns the pointed thread.
[in,out]	bmp	The bitmap to fill, initialized to the right size. The caller owns the pointed bitmap.
[in]	doccolorspace	The document's color space: DOCUMENT_COLORPROFILE
[in]	linearworkflow	true if Linear Workflow is enabled, otherwise false.

Returns: true if successful, otherwise false.

◆ GlMessageDummy()

virtual UInt32 GlMessageDummy	(	BaseMaterial *	mat,
		Int32	type,
		void *	data
	)

virtual

To ensure SDK compatibility Private.

◆ HasEditorTransparency()

virtual Bool HasEditorTransparency ( BaseMaterial * mat )

virtual

Called to check if the material has editor transparency.

Since: R17.032

Returns: true if if the material supports editor transparency, otherwise false.

Detailed Description

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ Draw()

◆ GetRenderInfo()

◆ InitRender()

◆ FreeRender()

◆ InitCalculation()

◆ Displace()

◆ ChangeNormal()

◆ CalcSurface()

◆ CalcTransparency()

◆ CalcAlpha()

◆ CalcVolumetric()

◆ InitGLImage()

◆ GlMessageDummy()

◆ HasEditorTransparency()