About

A BaseShader is the base class for shaders in Cinema 4D. Shaders are typically used with materials to define various surface properties. But shaders can also be used in other situations for example in combination with generator objects. BaseShader objects are not stored with the BaseDocument directly but must be inserted into the object that uses them.

BaseShader objects are an instance of Xbase.

  // This example lets the user select an image file. If a file was selected
  // a shader, material and texture tag are created that apply that image file
  // to the given object.
 
  Filename imageFile;
 
  // open file selector dialog to select an image file
  if (!imageFile.FileSelect(FILESELECTTYPE::IMAGES, FILESELECT::LOAD, "Select Image File"_s))
    return maxon::OK;
 
  // allocate elements
 
  BaseShader* bitmapShader = BaseShader::Alloc(Xbitmap);
  Material*   material = Material::Alloc();
  TextureTag* textureTag = TextureTag::Alloc();
 
  // check for successful allocation
  const Bool materialFailure = material == nullptr;
  const Bool shaderFailure = bitmapShader == nullptr;
  const Bool tagFailure = textureTag == nullptr;
 
  if (materialFailure || shaderFailure || tagFailure)
  {
    BaseShader::Free(bitmapShader);
    Material::Free(material);
    TextureTag::Free(textureTag);
 
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
  }
 
  // start undo for the complete task
  doc->StartUndo();
 
  // configure the texture tag
 
  const DescID projectionParam = ConstDescID(DescLevel(TEXTURETAG_PROJECTION));
  const Int32  projectionUVW = TEXTURETAG_PROJECTION_UVW;
  textureTag->SetParameter(projectionParam, projectionUVW, DESCFLAGS_SET::NONE);
 
  textureTag->SetMaterial(material);
  object->InsertTag(textureTag);
  doc->AddUndo(UNDOTYPE::NEWOBJ, textureTag);
 
  // configure the bitmap shader and the material
  bitmapShader->SetParameter(ConstDescID(DescLevel(BITMAPSHADER_FILENAME)), imageFile, DESCFLAGS_SET::NONE);
  material->SetParameter(ConstDescID(DescLevel(MATERIAL_COLOR_SHADER)), bitmapShader, DESCFLAGS_SET::NONE);
  material->InsertShader(bitmapShader);
 
  // insert the material
  doc->InsertMaterial(material);
  doc->AddUndo(UNDOTYPE::NEWOBJ, material);
 
  // finalize
  doc->EndUndo();

Access and Structure

Shaders are stored in a special shader branching relation of the nodes who own them. The first shader in the shader branch of a node can be retrieved with BaseList2D::GetFirstShader and inserted with BaseList2D::InsertShader . This primarily applies to BaseList2D shader owners such as BaseObject or BaseMaterial .

BaseShader instances which own shaders themselves tend to not insert shaders into their shader branch but as direct children although they are also BaseList2D instances. An example for this behaviour would be the type LayerShader which carries its owned shaders as direct children. When constructing such nested shader setups, one must call therefore GeListNode::InsertUnder on the root shader to insert child shaders, and not BaseList2D::InsertShader (Fig I).

BaseList2D::InsertShader(): Attaches a shader to an owning material or object.
BaseList2D::InsertUnder(): Attaches a child shader to a shader as commonly carried out by many shader types.

BaseDocument "doc"
+-- GeListHead "object"                // The object branch of the document.
|   +-- BaseObject "Shader Effector"   // A Mograph shader effector object in the document.
|   |   +-- GeListHead "shader"        // The shader branch in of the effector.
|   |       +-- BaseShader "Noise"     // A noise shader owned and used by the effector, it has no children.
|   +-- BaseObject "cube"              // A cube object, it owns no shaders. 
+-- GeListHead "material"              // The material branch of the document.
    +-- BaseMaterial "Material.1"      // The first material of the document, it owns a set of nested shaders.
    |   +-- GeListHead "shader"        // The shader branch in of the material.
    |       +-- BaseShader "Layer.1"   // A layer shader owned by the material with two children.
    |           +-- BaseShader "Noise" // A noise shader owned by by the "Layer.1" shader.
    |           +-- BaseShader "Noise" // Another noise shader owned by by the "Layer.1" shader.
    |       +-- BaseShader "Layer.2"   // Another layer shader owned by the material with one child.
    |           +-- BaseShader "Color" // A color shader owned by the "Layer.2" shader.
    +-- BaseMaterial "Material.2"      // The second material of the document, it owns no shaders.

Fig. I: How shaders are stored within a scene graph often changes with the BaseShader type itself.

Note: This behaviour is a rule of thumb, but there is no guarantee that all shader types who own shader dependencies handle their owned shaders in this manner. For native Cinema 4D shaders as the Layer or Fusion Shader this holds true, but one must always check how a specific shader handles its owned shaders when dealing with a specific type.

Traversing shaders therefore depends on the context:

BaseList2D::GetFirstShader(): Returns the first shader owned by a material or object.
BaseShader::GetDown(): Returns the first child shader for most shader types.
BaseShader::GetUp(): Returns the parent shader for most shader types.
BaseShader::GetListHead(): Returns the shader branch head owned by a material or object.

With either the list of shaders owned by a material or object, or within a hierarchy level of a set of nested shaders, one can navigate with the common GeListNode functions:

BaseShader::GetNext(): Returns the next shader in the list.
BaseShader::GetPred(): Returns the previous shader in the list.

  // This example loops through the shader list of the given material.
  // Note that this example does not handle child or sub-shaders.
 
  BaseShader* shader = material->GetFirstShader();
 
  while (shader != nullptr)
  {
    ApplicationOutput("Shader: " + shader->GetName());
 
    shader = shader->GetNext();
  }

Allocation/Deallocation

Shaders are created with the usual tools.

BaseShader::Alloc(): Creates a new shader.
BaseShader::Free(): Deletes the given shader.

Newly created shaders are typically handed over to the object that uses them:

BaseList2D::InsertShader(): Inserts the given shader into the shader list.

For a list of shader IDs see Shader Types.

  // This example creates a noise shader and assigns it to the given material.
 
  BaseShader* const noiseShader = BaseShader::Alloc(Xnoise);
  if (noiseShader == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  material->InsertShader(noiseShader);
  material->SetParameter(ConstDescID(DescLevel(MATERIAL_BUMP_SHADER)), noiseShader, DESCFLAGS_SET::NONE);

Read-Only Properties

BaseShader::GetRenderInfo(): Returns information about what the plugin requires from the raytracer and what it will return.
BaseShader::IsColorManagementOff(): Returns true if color management is disabled for shaders within reflectance, bump, alpha, displacement or normal channels when linear workflow is enabled.
BaseShader::GetSubsurfaceShader(): Returns the best SSS shader.
BaseShader::HasGPURendererSupport(): Returns true if the shader is supported natively by the Cinema 4D GPU Renderer. If the shader is not supported, it will be baked into a texture.

Note: Also supported shaders may be baked into a texture, depending on the used material channel and shader context.

Sampling a Shader

A shader returns a color value for a given point. This point can be a point in world or object space or a set of UV-coordinates. A shader is sampled this way typically in the rendering pipeline.

A shader has to be initiated:

BaseShader::InitRender(): Initiates the shader and its resources.

After the shader has been initiated these functions can be used:

BaseShader::GetBitmap(): Utility function that returns the BaseBitmap of a bitmap shader (Xbitmap).
BaseShader::Sample(): Samples the shader.
BaseShader::SampleBump(): Samples the shader to modify a normal vector.

In the end the resources of the shader must be released:

BaseShader::FreeRender(): Frees all resources used by this shader that were allocated by calling BaseShader::InitRender().

Warning: Without properly initiated InitRenderStruct::vd argument it is not safe to sample a shader multi-threaded.

A shader can sipmply be baked into a BaseBitmap using:

BaseShader::BakeShaderIntoBaseBitmap(): Creates a 2D representation of the shader.

  // This example bakes the given BaseShader into the given BaseBitmap
  // and displays the result in the Picture Viewer window.
 
  const InitRenderStruct irs { doc };
  const maxon::Int32     colorProfile = irs.document_colorprofile;
  const maxon::Bool      linearWorkflow = irs.linear_workflow;
 
  const maxon::Bool alpha = false;
  const maxon::Bool hdr  = true;
  const maxon::Int  xmin = 0;
  const maxon::Int  ymin = 0;
  const maxon::Int  xmax = sizeX - 1;
  const maxon::Int  ymax = sizeY - 1;
 
  // bake shader
  const Bool bakeResult = shader->BakeShaderIntoBaseBitmap(bitmap, *doc, parentThread, alpha, colorProfile, linearWorkflow, hdr, xmin, xmax, ymin, ymax);
  if (bakeResult == false)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // show result
  ShowBitmap(bitmap);

  // This example samples the given shader in UV space.
 
  // init the shader
 
  InitRenderStruct irs { doc };
 
  COLORSPACETRANSFORMATION transform = COLORSPACETRANSFORMATION::NONE;
  // check if linear workflow is enabled
  if (irs.linear_workflow)
    transform = COLORSPACETRANSFORMATION::LINEAR_TO_SRGB;
 
  const INITRENDERRESULT res = shader->InitRender(irs);
  if (res != INITRENDERRESULT::OK)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // sample the shader in UV space
 
  ChannelData channelData;
  channelData.off = 0;
  channelData.scale = 0;
  channelData.t = doc->GetTime().Get();
  channelData.texflag = CALC_TEXINFO(0, CHANNEL_COLOR);
 
  channelData.d  = Vector { 1, 1, 1 };
  channelData.n  = Vector { 0, 1, 0 };
  channelData.vd = nullptr; // VolumeData is nullptr
 
  for (Int32 y = 0; y < height; ++y)
  {
    for (Int32 x = 0; x < width; ++x)
    {
      // generate UV coordinates
      const Float64 xFloat = (Float64)x;
      const Float64 yFloat = (Float64)y;
      const Float64 u = xFloat / widthFloat;
      const Float64 v = yFloat / heightFloat;
 
      channelData.p.x = u;
      channelData.p.y = v;
      channelData.p.z = 0.0f;
 
      const Vector color = shader->Sample(&channelData);
      const Vector transformedColor = TransformColor(color, transform).Clamp01();
 
      // write into the given BaseBitmap
      const Int32 r = SAFEINT32(transformedColor.x * COLORTOINT_MULTIPLIER);
      const Int32 g = SAFEINT32(transformedColor.y * COLORTOINT_MULTIPLIER);
      const Int32 b = SAFEINT32(transformedColor.z * COLORTOINT_MULTIPLIER);
 
      bitmap->SetPixel(x, y, r, g, b);
    }
  }
 
  // free shader resources
  shader->FreeRender();

Compare

Two BaseShader elements can be compared with:

BaseShader::Compare(): Returns true if the given shader is identical.

Note: The comparison is mostly based on the shader's BaseContainer. Other internal data may not be compared.

Table of Contents