Main Index : Reference :

ChannelPlugin

Description

A channel plugin class.

Definition

class ChannelPlugin
{
public:
  ChannelPlugin();

  [string] GetName();
  [int] GetID();
  [int] GetInfo([BaseContainer] settings);
  [bool] InitSettings([BaseContainer] settings);
  [custom] InitRender([BaseContainer] settings);
  [bool] Message([BaseContainer] settings, [BaseContainer] message);
  [bool] EditData([BaseContainer] settings);
  [vector] Output([BaseContainer] settings, [custom] renderdata, [vector] p, [vector] n, [vector] d, [float] t, [int] texflag, [VolumeData] vd);
}

Explanation

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 )

CHANNEL_DIRECTBUMP is set if the shader returns a bump vector instead of a bump color
CHANNEL_RAYTRACING is set if the shader needs the raytracer to calculate custom rays (e.g. through TraceGeometry).

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.

Message( settings, message )

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

EditData( settings )

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

Output( settings, renderdata, p, n, d, t, texflag, vd )

calculates (and returns) the channel color at point 'p'
no OS calls are allowed (like file->Open are allowed within this routine; as it is MP executed you risk a crash - besides it makes absolutely no sense...)

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)
'p' is the projected point (according to the projection the user has set in the texture geometry dialog in object manager)
'n' is the normal for 'p'
'd' is the spot size (radius) for MIP/SAT mapping. d.x and d.y define the radius for the area around 'p' that needs to be sampled. If you ignore this value your shader will work, but produce awful aliasing artefacts during animation (sometimes even for stills)
't' is the current render time
'texflag' can be a combination of one of the following flags:
TEX_TILE : (C4D texture dialog option 'Tiling') the texture is tiled, the shader can (but needn't) calculate tiling
TEX_MIRROR: (C4D texture dialog option 'Seamless') the texture is seamlessly mirrored, only of interest if TEX_TILE is set.
TEX_ALPHA : the alpha channel of the shader shall be calculated (this is optional)
TEX_BUMP : bump channel is calculated. if CHANNEL_DIRECTBUMP was set before Output must now return the bumped vector

vd is the VolumeData structure (explained below). Important: 'vd' can be NULL (!) - this is the case when 2d previews for the shader are calculated (e.g. in material editor or for realtime texture mapping). you can in this case return 'best fit data' for previewing purposes or return a default color; just make sure you check vd!=NULL if you're accessing this structure!

To find out in which channel the shader is used:

In COFFEE just use settings->GetId().

The channel values are called CHANNEL_COLOR,CHANNEL_LUMINANCE,CHANNEL_TRANSPARENCY,CHANNEL_REFLECTION,CHANNEL_ENVIRONMENT,CHANNEL_FOG,CHANNEL_BUMP,CHANNEL_ALPHA,CHANNEL_SPECULAR,CHANNEL_SPECULARCOLOR,CHANNEL_GLOW,CHANNEL_DISPLACEMENT,CHANNEL_DIFFUSION
The channel value can be none of those types (e.g. -1) which means that the shader is inside of an (unknown) plugin channel.

See Also