MaterialData Class Reference

#include <c4d_materialdata.h>

Inheritance diagram for MaterialData:

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 GL_MESSAGE GlMessage (BaseMaterial *mat, Int32 type, void *data)
 
virtual Bool HasEditorTransparency (BaseMaterial *mat)
 
- Public Member Functions inherited from NodeData
 NodeData ()
 
GeListNodeGet (void) const
 
virtual Bool Message (GeListNode *node, Int32 type, void *data)
 
virtual void GetBubbleHelp (GeListNode *node, String &str)
 
virtual BaseDocumentGetDocument (GeListNode *node)
 
virtual Int32 GetBranchInfo (GeListNode *node, BranchInfo *info, Int32 max, GETBRANCHINFO flags)
 
virtual Bool IsInstanceOf (const GeListNode *node, Int32 type) const
 
virtual Bool IsDocumentRelated (const GeListNode *node, Bool &docrelated) const
 
virtual Bool Init (GeListNode *node)
 
virtual void Free (GeListNode *node)
 
virtual Bool Read (GeListNode *node, HyperFile *hf, Int32 level)
 
virtual Bool Write (GeListNode *node, HyperFile *hf)
 
virtual Bool CopyTo (NodeData *dest, GeListNode *snode, GeListNode *dnode, COPYFLAGS flags, AliasTrans *trn)
 
virtual Bool GetDDescription (GeListNode *node, Description *description, DESCFLAGS_DESC &flags)
 
virtual Bool GetDParameter (GeListNode *node, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags)
 
virtual Bool SetDParameter (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)
 
virtual Bool GetDEnabling (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer *itemdesc)
 
virtual Bool TranslateDescID (GeListNode *node, const DescID &id, DescID &res_id, C4DAtom *&res_at)
 
- Public Member Functions inherited from BaseData
 BaseData ()
 
virtual ~BaseData (void)
 
void Destructor (void)
 

Additional Inherited Members

- Protected Attributes inherited from NodeData
GeListNodeprivate_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]matThe BaseMaterial connected with the MaterialData instance. Equal to static_cast<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]opThe object associated with the material. Cinema 4D owns the pointed object.
[in]tagThe material tag. The caller owns the pointed tag.
[in]bdThe editor's view. The caller owns the pointed view.
[in]bhThe 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]matThe 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]matThe BaseMaterial connected with the MaterialData instance. Equal to static_cast<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]irsA 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]matThe 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:

During rendering:

During rendering for e.g. shadow rays:

§ 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]matThe 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]vdThe 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]matThe 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]vdThe 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]matThe 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]vdThe 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]matThe 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]vdThe 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]matThe 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]vdThe 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]matThe 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]vdThe 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]matThe BaseMaterial connected with the MaterialData instance. Equal to static_cast<BaseMaterial*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed material.
[in]docThe document. The caller owns the pointed document.
[in]thThe thread. The caller owns the pointed thread.
[in,out]bmpThe bitmap to fill, initialized to the right size. The caller owns the pointed bitmap.
[in]doccolorspaceThe document's color space: DOCUMENT_COLORPROFILE
[in]linearworkflowtrue if Linear Workflow is enabled, otherwise false.
Returns
true if successful, otherwise false.

§ GlMessage()

virtual GL_MESSAGE GlMessage ( BaseMaterial mat,
Int32  type,
void *  data 
)
virtual

Extended OpenGL mode. This mode is not documented. See c4d_gl.h for definitions.

§ 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.