Main Index : Reference :

VolumePlugin

Description

A volume plugin class.

Definition

class VolumePlugin
{
public:
  VolumePlugin();

  [string] GetName();
  [int] GetID();

  [int] GetInfo([BaseContainer] settings);
  [void] FillInfoData([BaseContainer] settings,[InfoStruct] is);

  [bool] InitSettings([BaseContainer] settings);
  [custom] InitRender([BaseContainer] settings);
  [bool] EditData([BaseContainer] settings);
  [bool] Message([BaseContainer] settings, [BaseContainer] message);

  [void] CalcSurface([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
  [void] CalcVolumetric([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
  [void] Displace([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
  [void] ChangeNormal([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
  [void] CalcTransparency([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
  [void] CalcAlpha([BaseContainer] settings, [custom] renderdata, [VolumeData] vd);
}

Explanation

A class for volume shader plugins. A registered VolumePlugin will appear under "New 3D Shader" in the Materials Manager.
All of the member functions except for GetName(), GetID(), and CalcSurface() are optional
No OS calls are allowed for: CalcSurface(), CalcVolumetric(), Displace(), ChangeNormal(), CalcTransparency(), or CalcAlpha()
(like file->Open as it is MP executed you risk a crash - besides it makes absolutely no sense...)

Members

GetName()

returns the name. If you set a prefix separated by '/' you can create a group. E.g. imagine the following: your plugin adds 10 shaders.
E.g. to group the first 5 shaders in a group called "Noise Shader" just let GetName return names like "Noise Shader/Shader 1".
Please note that if you put a shader into a folder on disk this folder will show up also.
Please also note that all groups with one element only will be eliminated during the optimization process.

GetID()

GetInfo( settings )

SHADER_RAYTRACING is set if the shader needs the raytracer to calculate custom rays (e.g. through TraceGeometry). it should NOT be set if standard transparency/reflection calculations are done
SHADER_REFLECTANCE is set if shader calculations reflections
SHADER_TRANSPARENCY is set if shader calculates transparency (or is a volumetric shader)
SHADER_ALPHA is set if shader is only partially visible (has alpha)
SHADER_CHANGENORMAL is set if shader changes surface normal
SHADER_DISPLACE is set if shader changes surface points
SHADER_SOFTSHADOW is set if surface casts soft shadows (for lights without transparency calculation checked)
SHADER_ENVREQUIRED is set if reflected ray needs to be precalculated even when no SHADER_REFLECTANCE is set (used in environment mapping)
SHADER_DUDVREQUIRED is set if ddu/ddv variables need to be precalculated (used in bump mapping)
SHADER_MIPSAT is set if shader needs MIP/SAT information (should always be set)
SHADER_VOLUMETRIC is set if the shader performs volumetric calculations

FillInfoData( settings, is )

Set midcol, midtrans and midrefl
These three colors help to define the editor's gouraud shading preview
If this routine is left out midcol, midtrans and midrefl are set to black
FillInfoData is called every time a material is created or updated

InitSettings( settings )

fills the shader's BaseContainer with default values
e.g. for a WoodShader the wood color, graininess etc.
If this routine is left out no values are stored
returns success
InitSettings is called every time a material is created or updated

InitRender( settings )

allocates a custom class with all the data that is necessary for CalcSurface later. the class is returned.
this routine is called before rendering for each shader instance.
a typical use would be to precalculate trigonometric functions like Sin, Cos, allocating noises etc.

EditData( settings )

edits the shader data (settings BaseContainer)
typical use would be to open a modal dialog that changes the settings data
If this routine is left out the shader cannot be edited
EditData is called when you double click (or call Edit... from the menu) on a material in the material editor
Returning TRUE tells Cinema 4D to re-render the preview icon & RTTM map, since
changes were made to the shader. Returning FALSE tells Cinema 4D that
the user canceled

Message( settings, message )

allows other plugins to send the shader any message. the message id can be retrieved by using message.GetId().
E.g. you could program your shaders in a way that every time it receives the command MSG_CHANGECOLOR it cycles its color...

CalcSurface( settings, renderdata, vd )

calculates the actual surface
the settings BaseContainers can be used for calculations (if InitSettings has been overloaded) / the render data structure can be used (if InitRender has been overloaded)
vd is the VolumeData structure (explained below)
CalcSurface can set vd->col, vd->trans and vd->refl
besides, vd->rray and vd->tray (the reflecting and the transparent rays) can be modified
please note that vd->tray is only valid if SHADER_TRANSPARENCY was set
please note that vd->rray is only valid if SHADER_REFLECTANCE or SHADER_ENVREQUIRED was set
CalcSurface is called during rendering (see order of calls during rendering below)

CalcVolumetric( settings, renderdata, vd )

If SHADER_VOLUMETRIC is not set, this function is not needed. If it is set, this function is required.
the settings BaseContainers can be used for calculations (if InitSettings has been overloaded) / the render data structure can be used (if InitRender has been overloaded)
vd is the VolumeData structure (explained below)
CalcVolumetric can set vd->col and vd->trans
CalcVolumetric is called during rendering (see order of calls during rendering below)
CalcVolumetric is called for spans (ray->p to vd->p). ray->p is the entry point, vd->p the exit point!
Volumetric shaders that do no surface calculation can set vd->trans=vector(1.0) in CalcSurface and CalcTransparency!

Displace( settings, renderdata, vd )

displaces a point
the settings and renderdata BaseContainers can be used (only if InitSettings / InitRender are there of course)
vd is the VolumeData structure (explained below)
Displace can modify vd->p. Usually it elevates the point along its normal a certain extent: vd->p += vd->dispn * factor;
If this routine is left out no displacement takes place
Displace is called after the render initializations (InitRender), but during the beginning phase

ChangeNormal( settings, renderdata, vd )

creates bump effect
the settings and renderdata BaseContainers can be used (only if InitSettings / InitRender are there of course)
ChangeNormal can modify vd->bumpn. If SHADER_DUDVREQUIRED was set you can use vd->ddu and vd->ddv as modification directions perpendicular to the face normal.
If this routine is left out no bumping takes place
ChangeNormal is called during rendering (see order of calls during rendering below)

CalcTransparency( settings, renderdata, vd )

speeds up transparency calculation (several times C4D only needs the transparency information; e.g. for fast shadow calculation)
the settings and renderdata BaseContainers can be used (only if InitSettings / InitRender are there of course)
CalcTransparency can set vd->trans
Please note that vd->tray is not valid and need not be modified
If this routine is left out you get slow shadow calculations
CalcTransparency is called during rendering (see order of calls during rendering below)

CalcAlpha( settings, renderdata, vd )

calculates alpha information
the settings and renderdata BaseContainers can be used (only if InitSettings / InitRender are there of course)
CalcAlpha can set vd->alpha
If this routine is left out you get no alpha
CalcAlpha is called during rendering (see order of calls during rendering below)

See Also