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 { 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(DescID(BITMAPSHADER_FILENAME), imageFile, DESCFLAGS_SET::NONE);
  material->SetParameter(DescID(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

Shaders are owned by the object that uses them. The shaders owned by a given object are organized in a list:

BaseList2D::GetFirstShader(): Returns the first shader of the shader list.

Shaders are typically organized in a list but can also be organized in a tree:

BaseShader::GetNext(): Returns the next shader in the list.
BaseShader::GetPred(): Returns the previous shader in the list.
BaseShader::GetUp(): Returns the parent shader.
BaseShader::GetDown(): Returns the child shader.
BaseShader::GetDownLast(): Returns the last child shader.

  // 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(DescID(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