Posts made by ferdinand

Hey @ECHekman,

I assume you are looking here for some kind of approval from my side? That looks fine, but it is hard to give a concrete assessment with mock code. But as lined out above, there is little which can go wrong here. Splitting up your data into sub-containers could help with access times when you plan to add lots of 'attributes' and 'pins'. So, it is good that you do that. And shifting your application IDs into lower ranges for Cinema 4D is probably not technically necessary but will lead to more 'natural' IDs. I cannot really see much going wrong here.

The only thing which is not so nice, is the unsafe C-style cast in BaseContainer *data = ((BaseShader*)node)->GetDataInstance();. We recommend using static_cast for safe casts and reinterpret_cast for casts which are explicitly meant to be unsafe.

Cheers,
Ferdinand

Hey @ECHekman,

Thank you for reaching out to us. As you know, you should avoid topics with multiple questions, as they have a tendency to get out of hand.

However im running into two issues. Some of these symbols clash with existing symbols in c4d.

Yes, many symbols in Cinema 4D collide, dialog message symbols (BFM_SOMETHING) collide for example with atom message (MSG_SOMETHING) which again collide with core and event messages (EVMSG_SOMETHING). The symbols for values inside the data containers of scene elements also collide with each other. This is for once because the address space of Int32 might not be big enough to address everything Cinema 4D has to address, and the curation of that would be very cumbersome or even impossible in the case of third parties.

The larger problem than value collision (both ID_FOO and ID_BAR resolve to 1000) is actual symbol collision (you have the plugins A and B which both define an ID_FOO which then resolves to different numeric values). In C++ this is offset by the fact that you can selectively include header files. In Python you cannot do this and all symbol labels must fit here collision free into the c4d package namespace. One should therefore always prefix node symbols with the node they are for. E.g., for an ObjectData plugin omyobject.res, the symbols should look like this: ID_MYOBJECT_FOO, ID_MYOBJECT_BAR and not ID_FOO or ID_BAR.

I have read that the first 1000 are reserved. And that I shouldn't go above 1 million?

That is true, the parameter slots 0 to 1000 are reserved for the Basic tab each node has (with different content based on the node type) and some internal things. The name of a node is for example stored under ID_BASELIST_NAME which is an alias for 900.

I know that there is this information floating around that one should not use high numbers like a million. For stuff like plugin IDs (which you should not invent in the first place) it is true that we use the end of the Int32 address space for special purposes, so you REALLY should not invent a plugin ID that is 2^32 - 5. But that would not be millions but billions. It could be that we in the past did occupy slots at the end of the Int32 space for scene elements. But I am currently not aware of any cases.

But for readability and conformance reasons I would recommend to stick to the Cinema 4D pattern of staying in the low hundreds of thousands. Due to how BaseContainer works, there could also be a performance argument for small key values, but I am (a) not 100% sure and (b) it can probably be ignored on modern hardware.

What should not be ignored is that BaseContainer is neither a hash map not a fixed size array but a list of key value pairs at its core. Storing 100, 1000, or 10 000 values is fine, and you can also store 100 000 values if you really have to. But you should be aware that access times are not constant (at the advantage that for the common case of small container sizes of ~1000 items, this will outperform hashing).

My other related issue is that I would like to reuse symbols in the same NodeData plugin.

You can reuse symbols between nodes as much as you want. What I would personally consider formally not so nice, is when you would just define a symbol in the resource of a node A and then also use it to store things in the data container of node B. But it is technically totally fine, I would just consider it poor code hygiene.

• You can always just define a symbol in the resource header file of your plugin. I.e., not every smybol in omyobject.h must appear in omyobject.res and omyobject.str. When you want to define a 'global' symbol, you should do that in your c4d_symbols.h.
• The built-in mechanism for symbol sharing are includes, e.g., INCLUDE Obase; is the line which includes the file obase.res and its symbols into your object plugin and makes sure that it has the common UI elements and parameters all object nodes have. You can define your own base descriptions and include them. I would invite you to have a look at {C4D_FOLDER}/resource.zip/modules/c4d_base/description to check out how Cinema 4D composes complex descriptions. All node types have a base, e.g., Obase, Tbase, Xbase, etc., which are all based on the atomic description Obaselist. But there is more modularization, things like spline interpolations, field handling, and more are all encapsulated in reusable description elements.

You can also build dynamically descriptions or allocate data. In a node, we then usually define a base symbol ID_MYOBJECT_ITEMS_BASE = 50000 at a safe offset tp the rest of the data (so that we have room for adding other static parameters in the future), a stride ID_MYOBJECT_ITEMS_STRIDE = 100 (it does not matter that we define here the stride as 100 as we are not going to write with it into the data container at that value) and optionally a few named offsets (ID_MYOBJECT_ITEM_NAME = 0, _COLOR = 2, _LAYER = 3, ..) and then write with these values at runtime into the data container of the node; e.g.,

const Int32 i = ID_MYOBJECT_ITEMS_BASE  + ID_MYOBJECT_ITEMS_STRIDE * layer;
bc.SetString(i + ID_MYOBJECT_ITEM_NAME, "MyName"_s);
bc.SetVector(i + ID_MYOBJECT_ITEM_COLOR, myColor);
...

My solution idea was to use sub-containers to avoid both of these symbol clashes. However I cannot find in the sdk if the same symbol restrictions apply for subcontainers.

You can do whatever you want to in sub-containers. But I would avoid overly large containers (holding millions of items) for performance reasons. Only the data container of a scene element (BaseList2D::GetDataInstance) comes with the restriction that you should not write into the 0 to 1000 range, as there it is where scene elements store their atomic data. A BaseContainer itself is free of restrictions.

Additionally, do links work the same as with normal BaseContainers?

Are you talking about BaseLink fields of a container? And what is here the implicitly referred counter part of 'normal' containers? A sub container? Links are stored document agnostic, i.e., you have to pass a document within which you want to resolve the link. It does not matter if you store that link in the top level of a nodes data container, in a sub-container of that data container, a bare BaseContainer instance in memory, or a hyper file on disk. They all will be able to resolve their link when passed the correct document which contains a node with the matching marker stored in the link.

Cheers,
Ferdinand

Dear development community,

On December the 4th, 2024, Maxon Computer released Cinema 4D 2025.1.0. For an overview of the new features of Cinema 4D 2025.1, please refer to the release announcement. Alongside this release, a new Cinema 4D SDK and SDK documentation have been released, reflecting the API changes for 2025.1.0. The major changes are:

General

The PluginCafe GitHub organization has been deprecated in favour of a new Maxon-Computer GitHub organization. The legacy repositories have been moved, renamed, and brought into a consistent metadata form. Local clones of the legacy repositories will continue to work as they are.

C++ API

• No larger changes have been made.

Python API

• Documented new graph description features exposed in 2025.0 in the Graph Descriptions Manual. Referencing Entities has been reworked and the sections Explicit Connections and Graph Commands have been added.

Head to our download section for the newest SDK downloads, or the C++ and Python API change notes for an in detail overview of the changes.

The graph description code examples on GitHub have not been uploaded yet, they will be added later.

Happy Christmas and coding,
the Maxon SDK Team

Cloudflare unfortunately still does interfere with our server cache. You might have to refresh your cache manually to see new data when you read this posting within 24 hours of its release.

Well, my answer answers that, check out the posting I linked to. You must insert a MENURESOURCE_SUBTITLE:

menu.InsData(c4d.MENURESOURCE_SUBTITLE, "My Heading")

Hey @Gemini,

Thank you for reaching out to us. I am struggling a bit with understanding all details of your question(s). Please also note that we do not allow for multi question topics, see Support Procedures: How to ask Questions for details.

Is there a way to add not pickable items like a title written with capital letter to custom menus created by python.

I assume you are talking about sub-titles in menus here, @i_mazlov has shown here how to do that.

How a toggle line be added and how can be get its sate?

I assume you mean here a menu entry with a checkbox/checkmark next to it? Menus allow you to mark entries as checked or disabled with the label suffixes 'c' and 'd'. E.g.: "I am a checked label&c&" and "I am a disabled label&d&". See ShowPopupDialog() for an example. But one usually does this on a popup menu or dialog menu level.

The code you show us as "yours", is code I have written in the context of the main menu of Cinema 4D. So, the question is: Do you want to inject things into the main menu of Cinema 4D, or are you just populating a dialog or popup menu.

I am not sure if you are allowed to place checkmarks there and manually disable menu entries, as Cinema 4D itself owns its main menu. It might ignore such markup there, you would have to try yourself.

Cheers,
Ferdinand

addendum, I briefly spoke with the dev:

In SetDParameter, there is code that sets the correct group automatically if force_type or force_type_mode is specified, and the other way around. One thing to keep in mind is that, when you set the parameter force_type_group, the mode is set to default value for that group, i.e., ball and socket for spherical, hinge for angular, slider for linear. This is what you see ig you play in with the dropdown menus in the UI as well. So, if one first sets force_type_mode and then force_type_group, the latter resets the mode to a possibly different value. But in the code snippet attached it looks though like the order is correct (assuming is the actual code used in the plugin).

In a way, I understand that if you are setting mode and group manually from you plugin and you know what you are doing, you are setting a combination that makes sense. But in general, to be extra safe, I decided to go with this solution, so if you change the group the mode is automatically set to something that makes sense. And, btw, also when you set the mode there is a check on the group, and if the values don't match it gets overwritten with the correct group.

so, valid options are:

• simply set force_type (as before)
• set force_type_group and force_type_mode (in this order)
• only set force_type_mode (group set automatically)

If any of these don't give the expected combination it is a bug

I think he too struggled a bit with understanding what you did concretely, so I would recommend creating a bug report as lined out above.

Cheers,
Ferdinand

Hello @yaya,

Thank you for reaching out to us. Although your problem might be related to your old problem for you (as introduced by the connector object changes in 2024.4), I would say this is an entirely new issue. Please open a new thread for a new issue, as lined out in our Support Procedures.

Your problem description is also rather hard to follow, at least for me. I would recommend that you follow the pattern shown in Support Procedures: Examples - Reporting Bugs & Crashes very closely.

Cheers,
Ferdinand

Hello @ECHekman,

Thank you for reaching out to us. When you run into compiler errors, you should always include them, because how should we otherwise help you? Sure, I could throw your code into our code base, guess some things, and then try to compile it, but the guessing and compiling is unnecessary and makes our answers more imprecise.

But this should work:

iferr_scope;

maxon::String myString = "Hello/World"_s;
maxon::BaseArray<maxon::String> parts; // could also be const
myString.Split("/"_s, true, parts) iferr_return;
if (MAXON_UNLIKELY(parts.GetCount() < 1))
  return maxon::IllegalStateError(MAXON_SOURCE_LOCATION, "Splitting path failed."_s);

FYI: There is also UrlInterface::GetComponents.

Cheers,
Ferdinand

Hey @peter_horvath,

So, you do call InstanceObject.GetInstanceMatrices() etc. and construct the clones yourself. That was what confused me in your fist posting, as you talked about 'clones' in 'We'd need this index to be able to export MoGraph attributes to each clone/instance.'

What you effectively want to do, is associate the matrices/colors in an multi InstanceObject with the MoGraph particle IDs they have been created for, right? That is not possible, at least for all cloners which have more than one particle geometry. I briefly talked with the current developer of MoGraph, and he does not see an option either.

I also tried to have a look at the Redshift code base, and as far as I can see, they simply seem to unravel things from the MoData side and mostly ignore the true cache and then end up with the ability to match a clone with its particle index even in Multi Instance mode (that is at least what it looks like to me, I have reached out to one of their devs). In the end I do not see anything particularly bad with this approach, because when syncing scene graphs, you have to reallocate geometry anyway. The problem with this is that MODATA_MATRIX does not reflect the deformed matrix, i.e., it does not respect BaseObject::GetDeformMatrix and with that simulations like for example RBD. I have absolultely no idea how Redshift handles that, I might be misinterpreting their code.

So, long story short, what you want to do, does not seem possible at the moment for externals. But the MoGraph Developer mentioned that we could try to store the InstanceObject::GetInstanceUniqueIP in the MODATA_ALT_INDEX . But we would have to check first that this does not break anything. When you really want this, I would suggest filing a feature request (your Nodes API menu sorting thing is still cooking btw.)

Cheers,
Ferdinand

Hey @peter_horvath,

Thank you for reaching out to us. I am a little bit confused as I do not truly understand your question. You are an experienced developer, so it seems a bit unlikely that you overlooked what I am explaining next.

In the video below I have unfolded the cache of a MoGraph cloner and switch through the modes, which are admittedly named quite confusingly, but the docs mostly clear up their purpose:

• Instances: Nothing is really being instantiated here at all, there are three copies of the clone geometry in the cache of the cloner. Not the most memory efficient thing in the world when you have many clones. Would probably be better named as Copies.
• Render Instances: Here we have one copy and two instance objects pointing to that copy. So, we pay the price of one original, a the low price of two objects pointing to that one original. Would probably be better named just as Instances.
• Multi-Instances: Again, there are no instances going on here, and also no 'multi' at all. Opposed to the previous modes, this mode only holds a singular object in its cache (wrapped in an additional null) which is a copy of the input. The cloning will only happen at render time (at least that was always what I thought would happen).

So, in the Multi-Instances case, there is neither a cloner nor some geometry where we could store additional information. Because that singular object is cloned just for the renderer. Just to be sure, I looked effectively into what is GetVirtualObjects for the cloner and set breakpoints on all cases where BC_ID_MODATAINDEX is written. As to be expected, Instances writes the indices 0, 1, and 2 on its three copies, Render Instances writes 0, 1, 2 on its one copy and two instances, and Multi-Instances only writes 0 on its one copy because there is nothing other to write into?

What I haven't done here, is looked into how both our viewport and render engine implementations deal with this. I do not see in the object implementation any signal that would tell you that a cache content is Multi-Instances blueprint copy. The only thing which stands out, is that Multi-Instances copies (there can be more than one particle geometry other than in my example) are wrapped into an additional null. You can of course just check the cloner but that strikes me as a bit iffy, but could very well that we handle it like this.

As I wrote in the beginning, I assume you did not overlook all that. And I assume the scene tree you get passed in your render document looks differently, with mock data already being inserted for the "multi-instances"? I would have quite frankly assumed that to be the task of the render engine, but I must be wrong.

Cheers,
Ferdinand

Hey @T1001,

find below an example for a user area which draws multiple semi-transparent bitmaps on top of each other. I will likely add this code example to the SDK at some point, as this is a common task. Please provide feedback when you think things are missing.

The example focuses on the core problem of having an 'alien' app which places bitmap data in memory and the Image API wrapping around that data with transparencies. What I have not yet done here, is that I avoided all copying altogether and directly operate on the raw memory managed and owned by the alien app. Which is possible to do in the public API I think, but one would have to write a component for ImageBaseInterface so that one can modify the Get/SetPixelHandler's. This would have been out of scope for this example. But I have it on my backlog, as I can see how this would be a desirable feature for render engine vendors and similar plugin types.

Cheers,
Ferdinand

Result

Code

/* Demonstrates how to implement a dialog that wraps around image buffers provided by an alien
   application.

   The buffers are of type RGBA-32 but could also follow any other pixel format the Image API 
   supports. The buffers are drawn with their transparencies on top of each other in a user area
   and automatically scaled to the size of the user area.

   The example contains the following sections:

   * namespace alien: Contains code that generates image data in memory, mocking an alien app.
   * namespace cinema: Contains the code to wrap that alien image data in Cinema 4D with:
       * class ImageLayersArea: The UI element which wraps the buffers concretely.
       * class ImageLayersAreaDialog: The dialog implementation which uses an #ImageLayersArea.
       * class ImageLayersAreaCommand: The command which wraps the dialog as a menu/palette item
         which can be invoked by the user to open the dialog.
*/

// std is here only used to simulate an alien app, do not use std in your regular Cinema projects.
#include <vector>
#include <algorithm>

#include "c4d_basedocument.h"
#include "c4d_colors.h"
#include "c4d_commandplugin.h"
#include "c4d_general.h"
#include "c4d_gui.h"

#include "maxon/gfx_image.h"
#include "maxon/gfx_image_colorprofile.h"
#include "maxon/gfx_image_colorspaces.h"
#include "maxon/gfx_image_pixelformats.h"
#include "maxon/gfx_image_storage.h"
#include "maxon/mediasession_image_export.h" // Must be included before the specialization.
#include "maxon/mediasession_image_export_psd.h"
#include "maxon/lib_math.h"

// The plugin ID of the #ImageLayersAreaCommand. You must register unique plugin IDs for your plugins
// via https://developers.maxon.net/.
static const cinema::Int32 g_image_layers_command = 1064549;

// The definition of bitmap buffers generated by the alien application.
static const cinema::Int32 g_buffer_height = 2048;
static const cinema::Int32 g_buffer_width = 2048;
static const cinema::Int32 g_buffer_channel_count = 4;
static const cinema::Int32 g_buffer_line_size = g_buffer_width * g_buffer_channel_count;
static const cinema::Int32 g_buffer_size = g_buffer_line_size * g_buffer_height;

// Title used by the dialog and command, and the IDs of the dialog gadgets.
#define CMD_TITLE "C++ SDK: Image Layers Area"_s
#define ID_GRP_BUTTONS 1000
#define ID_UA_IMAGE_LAYERS 2000
#define ID_BTN_ADD 2001
#define ID_BTN_REMOVE 2002
#define ID_BTN_SAVE 2003

/// We need this because IMAGEINTERPOLATIONMODE is currently not exposed in the public API, I
/// will fix this in a future release.
namespace maxon 
{
enum class IMAGEINTERPOLATIONMODE
{
  NEARESTNEIGHBOR, ///< worst quality, no interpolation at all
  LINEAR,					 ///< linear interpolation between pixels
  BICUBIC,				 ///< best quality using bicubic interpolation
} MAXON_ENUM_LIST(IMAGEINTERPOLATIONMODE);

} // end of namespace maxon

// --- Alien Application Code

/// This namespace is meant to simulate some alien application which places bitmap data in memory
/// which we are going to wrap with the Image API. The example is using here the std library for 
/// the sole purpose of simulating an alien application. PLEASE NOTE THAT THE USE OF STD IN CINEMA
/// PROJECTS IS STRONGLY DISCOURAGED.
namespace alien
{

// A list of alien bitmap buffers held and managed by an alien application. Each float* in the 
// vector is a head to a buffer as defined by the g_buffer_ constants.
std::vector<float*> g_alien_buffers;

// A random number generator used by the alien application.
maxon::LinearCongruentialRandom<maxon::Float32> g_random;

/// Places an RGBA buffer in memory which holds a horizontal gradient in an otherwise largely 
/// transparent bitmap. This could for example be a buffer of an render engine which stores
/// its data as #float.
///
/// We are going to draw something like this, a horizontal gradient that only covers a portion
/// of the height of the bitmap buffer, leaving the rest of the buffer entirely transparent.
///
///   ----------------------------------------
///
///
///   @@@@@%%%%#####****+++++====-----::::....
///
///
///   ----------------------------------------
float* AddAlienBuffer()
{
  iferr_scope;

  // The starting position and height of the horizontal gradient bar.
  const int32_t  gradientHeight = std::max(
    3, int32_t (g_random.Get01() * float(g_buffer_height) * 0.333));
  const int32_t  gradientStart = std::min(
    g_buffer_height - gradientHeight, int32_t (g_random.Get01() * float(g_buffer_height)));
  const int32_t  gradientEnd = gradientStart + gradientHeight - 1;

  // The knots of the gradient. We either interpolate from opaque to transparent or vice versa. We 
  // dip here our toes a bit into the Maxon API with ColorA32 so that we later use its color 
  // interpolation function.
  const float alphaA = g_random.Get01() > .5 ? 0.0 : 1.0;
  const float alphaB = alphaA > 0.5 ? 0.0 : 1.0;
  const maxon::ColorA32 gradientColorA(
    g_random.Get01(), g_random.Get01(), g_random.Get01(), alphaA);
  const maxon::ColorA32 gradientColorB(
    g_random.Get01(), g_random.Get01(), g_random.Get01(), alphaB);

  // Allocate a new buffer.
  float* buffer = new float[g_buffer_size];

  // Now we write a gradient into an otherwise fully transparent image. We write  RGBA float data 
  // in an at this point undefined color profile. We will then on the Cinema 4D side interpret 
  // this data as PixelFormats::RGBA::F32() with an sRGB-2.1 profile.
  for (int32_t  y = 0; y < g_buffer_height; ++y)
  {
    // We are outside of the gradient strip, we fill the line with fully transparent pure black.
    if (MAXON_LIKELY((y < gradientStart) || (y > gradientEnd)))
    {
      for (int32_t  x = 0; x < g_buffer_width; x++)
      {
        const int32_t  i = (y * g_buffer_line_size) + (x * g_buffer_channel_count);
        buffer[i + 0] = 0.0; // R
        buffer[i + 1] = 0.0; // G
        buffer[i + 2] = 0.0; // B
        buffer[i + 3] = 0.0; // A
      }
    }
    // We are inside the gradient strip, we write a gradient into the buffer.
    else
    {
      for (int32_t  x = 0; x < g_buffer_width; x++)
      {
        const int32_t  i = (y * g_buffer_line_size) + (x * g_buffer_channel_count);
        const maxon::ColorA32 color = maxon::BlendColor(
          gradientColorA, gradientColorB, float(x) / float(g_buffer_width));

        buffer[i + 0] = color.r;
        buffer[i + 1] = color.g;
        buffer[i + 2] = color.b;
        buffer[i + 3] = color.a;
      }
    }
  }

  // Append the buffer to the global buffers and return the buffer.
  g_alien_buffers.push_back(buffer);

  return buffer;
}

/// Removes the last element from the alien buffer list and frees its memory.
void PopAlienBuffer()
{
  if (g_alien_buffers.empty())
    return;

  float* last = g_alien_buffers.back();
  delete[] last;
  g_alien_buffers.pop_back();
}

} // end of alien


// --- Cinema 4D Application Code
namespace cinema
{

using namespace maxon;

// --- UserArea Implementation --------------------------------------------------------------------

/// Implements a custom GUI that wraps around the bitmap buffers of an alien application.
class ImageLayersArea : public GeUserArea 
{
private:
  // Holds the images wrapping the alien buffers. Since we later want save out these buffers as
  // multi layer PSD files, we right away pick ImageLayerRef and not ImageRef as our image class.
  BaseArray<ImageLayerRef> _layers;

public:

  // --- Custom Methods

  // Adds an image layer to the user area from the given #buffer. We rely here on the globally defined
  // buffer metadata, otherwise we would have to describe the layout of #buffer with more arguments.
  Result<void> AddLayer(float* buffer)
  {
    iferr_scope;

    // Allocate a new maxon Image API (layer) bitmap that uses the default non-linear RGB profile 
    // (sRGB 2.1) and an RGBA four bytes per channel float pixel format, i.e., 16 bytes per pixel. 
    // We could also import here an ICC profile from disk to match an exotic color profile used
    // by alien app. But when that is the case, we would have to convert colors here to sRGB 2.1 as 
    // shown in the example_color_management examples.
    const ImageLayerRef layer = ImageLayerClasses::RASTER().Create() iferr_return;
    const maxon::ColorProfile profile = ColorSpaces::RGBspace().GetDefaultNonlinearColorProfile();
    const PixelFormat format = PixelFormats::RGBA::F32();
    const Int32 channelCount = format.GetChannelCount();

    // Init the bitmap with its size, storage convention, and pixel format. Whe choose here the
    // "normal", i.e., consecutive layout. An alternative could be a planar layout.
    layer.Init(g_buffer_width, g_buffer_height, ImagePixelStorageClasses::Normal(), format) iferr_return;

    // Set some metadata on the image layer. Setting a name is irrelevant, the rest is not.
    layer.Set(IMAGEPROPERTIES::NAME, FormatString("layer_@", _layers.GetCount() + 1)) iferr_return;
    layer.Set(IMAGEPROPERTIES::IMAGE::COLORPROFILE, profile) iferr_return;
    layer.Set(IMAGEPROPERTIES::TYPE, IMAGEPROPERTIES::ITYPE::LAYER) iferr_return;

    // Get the pixel handler to write data into the image.
    const maxon::SetPixelHandlerStruct handler = layer.SetPixelHandler(
      format, format.GetChannelOffsets(), profile, maxon::SETPIXELHANDLERFLAGS::NONE) iferr_return;

    // Copy the data line by line.
    for (Int32 y = 0; y < g_buffer_height; ++y)
    {
      // Construct a Pix, i.e., UChar , line buffer pointer for our current buffer pointer. The 
      // Image API handles all data at its lowest level as UChar. E.g., a line with 10 RGBA::F32 
      // pixels, i.e, 10 * 4, elements will be actually stored as, 10 * 4 * 4 elements, as an F32 
      // is decomposed into four UChar bytes.
      Pix* head = reinterpret_cast<Pix*>(buffer);

      // Write the line buffer into the image. Despite its name, an ImagePos can express up to
      // a line in an image.
      handler.SetPixel(
        ImagePos(0, y, g_buffer_width), 
        PixelMutableBuffer(head, format.GetBitsPerPixel()),
        SETPIXELFLAGS::NONE) iferr_return;

      // Advance the buffer to the next line.
      buffer += g_buffer_line_size;
    }

    // Append our layer to list of layers.
    _layers.Append(layer) iferr_return;

    return OK;
  }

  /// Pops the last layer from the list of layers.
  Bool PopImage() 
  {
    return _layers.Pop();
  }

  /// Saves the whole layer list as a PSD to disk.
  Result<void> Save()
  {
    iferr_scope;

    // Check that we are on the main thread and then ask the user for a save location.
    if (!GeIsMainThreadAndNoDrawThread())
      return IllegalStateError(
        MAXON_SOURCE_LOCATION, "This function cannot be run off main-thread"_s);

    Filename file;
    if (!file.FileSelect(
      FILESELECTTYPE::IMAGES, FILESELECT::SAVE, "Select file path:"_s, "psd"_s))
      return OK;

    // Insatiate an ImageTextureRef, the root level bitmap type required to save images.
    // A texture can only hold entries of type IMAGEHIERARCHY::IMAGE, adding multiple images
    // to a ImageTextureRef will not result in layers, but all data being put into the "background"
    // layer of the image.
    const ImageTextureRef texture = ImageTextureClasses::TEXTURE().Create() iferr_return;
    const ImageRef base = ImageClasses::IMAGE().Create() iferr_return;

    base.Init(g_buffer_width, g_buffer_height, ImagePixelStorageClasses::Normal(), 
              PixelFormats::RGBA::F32()) iferr_return;
    base.Set(IMAGEPROPERTIES::IMAGE::COLORPROFILE, maxon::ColorProfile()) iferr_return;
    texture.AddChildren(IMAGEHIERARCHY::IMAGE, base, ImageBaseRef()) iferr_return;

    // Now iterate over our layers with transparencies and add them one by one to the image.
    for (const ImageLayerRef layer : _layers)
    {
      // It is really importan that #layer has IMAGEPROPERTIES::TYPE set to LAYER.
      base.AddChildren(IMAGEHIERARCHY::LAYER, layer, ImageBaseRef()) iferr_return;
    }

    // Save #texture as a PSD.
    const MediaOutputUrlRef psd = ImageSaverClasses::Psd().Create() iferr_return;
    texture.Save(MaxonConvert(
      file, MAXONCONVERTMODE::NONE), psd, MEDIASESSIONFLAGS::NONE) iferr_return;

    return OK;
  }

  // --- GeUserArea Methods

  /// Called by Cinema 4D to request the minium #width and #height for the area.
  Bool GetMinSize(Int32& w, Int32& h)
  {
    w = h = 256;
    return true;
  }

  /// Called by Cinema 4D to let the area draw its content.
  void DrawMsg(Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer& msg)
{
  // Enable some drawing optimizations.
  OffScreenOn();
  SetClippingRegion(x1, y1, x2, y2);

  // Draw the background with the default background color.
  DrawSetPen(COLOR_BG);
  DrawRectangle(x1, y1, x2, y2);

  Float32 wx = Float32(x1);
  Float32 wy = Float32(y1);
  Float32 ww = Float32(x2 - x1);
  Float32 wh = Float32(y2 - y1);

  // Draw our layers on top of each other with bicubic interpolation.
  for (ImageBaseRef image : _layers)
    DrawImageRef(image, wx, wy, ww, wh, 1.0, IMAGEINTERPOLATIONMODE::BICUBIC);
}

};

// --- Dialog Implementation ----------------------------------------------------------------------

/// Realizes a dialog that displays a bitmap with multiple layers with transparencies.
class ImageLayersAreaDialog : public GeDialog 
{
private:
  // The custom user area and the default number of layers which are being added.
  ImageLayersArea _layers;
  const Int32 _defaultLayerCount = 3;

public:

  // --- Custom Methods 

  /// Adds an alien buffer and wraps it with an image in the #ImageLayersArea in tandem.
  Result<void> AddBuffer()
  {
    iferr_scope;

    float* buffer = alien::AddAlienBuffer();
    _layers.AddLayer(buffer) iferr_return;

    return OK;
  }

  /// Pops an alien buffer and its wrapping image in the #ImageLayersArea in tandem.
  Result<void> PopBuffer()
  {
    _layers.PopImage();
    alien::PopAlienBuffer();

    return OK;
  }

  // --- GeDialog Methods 

  /// Called by Cinema 4D to let the dialog populate itself with gadgets.
  Bool CreateLayout()
  {
    Bool result = true;
    static const Int32 margin = 5;

    // Set the title and the margin between the group and the border and between items in the 
    // group. We are defining here the implicitly existing outmost group.
    SetTitle(CMD_TITLE);

    result &= GroupBorderSpace(margin, margin, margin, margin);
    result &= GroupSpace(margin, margin);

    // Add the image layers user area.
    result &= AddUserArea(ID_UA_IMAGE_LAYERS, BFH_SCALEFIT | BFV_SCALEFIT, 0, 200) != nullptr;
    result &= AttachUserArea(_layers, ID_UA_IMAGE_LAYERS);

    // Add a group with holds three elements pre row (opposed to the one element by row of the
    // default group and add the three buttons.
    result &= GroupBegin(ID_GRP_BUTTONS, BFH_SCALEFIT, 3, 0, ""_s, 0);
    {
      result &= GroupSpace(margin, margin);
      result &= AddButton(ID_BTN_ADD, BFH_SCALE, 0, 0, "Add"_s) != nullptr;
      result &= AddButton(ID_BTN_REMOVE, BFH_SCALE, 0, 0, "Remove"_s) != nullptr;
      result &= AddButton(ID_BTN_SAVE, BFH_SCALE, 0, 0, "Save"_s) != nullptr;
    }
    result &= GroupEnd();

    return result;
  }

  /// Called by Cinema 4D to let the dialog init its values once its UI has been built. 
  Bool InitValues()
  {
    // We implemented many methods here as Result<T>, the error system of the Maxon API. This method
    // is not of type Result<T> and we must therefore terimate the error handling in this function.
    // When an error is bubbling up through the 'iferr_return' of the #AddBuffer call, the function
    // will exit through this scope handler with #err being the error which is raised.
    iferr_scope_handler
    {
      // This is for demo purposes only, please avoid console spam in production code, use loggers
      // like DiagnosticsOutput instead.
      ApplicationOutput("@ failed with error: @", MAXON_FUNCTIONNAME, err);
      return false;
    };

    // Add a few layers by default.
    for (Int32 i = 0; i < _defaultLayerCount; i++)
    {
      AddBuffer() iferr_return;
    }

    return true;
  }

  /// Called by Cinema 4D when the user clicks elements in the UI.
  ///
  /// Propagated are here only true click events, to realize things like scrubbing, mouse-over, 
  /// etc, one has to implement GeDialog::Message (where one can also handle clicks).
  Bool Command(Int32 cid, const BaseContainer& msg)
  {
    iferr_scope_handler
    {
      // This is for demo purposes only, please avoid console spam in production code, use loggers
      // like DiagnosticsOutput instead. #err is the error exposed to the scope handler.
      ApplicationOutput("@ failed with error: @", MAXON_FUNCTIONNAME, err);
      return false;
    };

    // We handle the buttons, when we add or pop layers, we force the user area to redraw.
    if (cid == ID_BTN_ADD)
    {
      AddBuffer() iferr_return;
      _layers.Redraw();
    }
    else if (cid == ID_BTN_REMOVE)
    {
      PopBuffer() iferr_return;
      _layers.Redraw();
    }
    else if (cid == ID_BTN_SAVE)
    {
      _layers.Save() iferr_return;
    }

    return true;
  }
};

// --- Command Implementation ---------------------------------------------------------------------

/// Realizes the command with which the user can open and close an the #ImageLayersAreaDialog.
class ImageLayersAreaCommand : public CommandData 
{
private:
  // The dialog of the command, we keep using the same instance over the life time of Cinema 4D.
  ImageLayersAreaDialog _dialog;

public:
  /// Returns an instance of the #ImageLayersCommand.
  static ImageLayersAreaCommand* Alloc()
  { 
    return NewObjClear(ImageLayersAreaCommand); 
  }

  /// Called by Cinema 4D when the user invokes the command.
  Bool Execute(BaseDocument* doc, GeDialog* parentManager) 
  {
    // Fold the dialog when open and unfolded, otherwise unfold it (Open both opens a never opened
    // dialog and unfolds a folded dialog).
    if (_dialog.IsOpen() && !_dialog.GetFolding())
      _dialog.SetFolding(true);
    else
      _dialog.Open(DLG_TYPE::ASYNC, g_image_layers_command);

    return true;
  }

  /// Called by Cinema 4D to restore the UI associated with a command on layout switches.
  Bool RestoreLayout(void* secret) 
  {
    return _dialog.RestoreLayout(g_image_layers_command, 0, secret);
  }
};
} // namespace cinema

/// Registers the #ImageLayersAreaCommand as a CommandData plugin.
/// 
/// Must be called in the main.cpp of this module when #PluginStart() is emitted.
cinema::Bool RegisterImageLayersAreaExample() 
{
  return cinema::RegisterCommandPlugin(
    g_image_layers_command, CMD_TITLE, 0, nullptr, 
    "Opens a dialog holding a custom UI element that stacks multiple bitmaps with transparencies."_s, 
    cinema::ImageLayersAreaCommand::Alloc());
}

Hey @Gemini,

as I just said, there aren't any, even in the non-public C++ API. When you want to provide a layout, you must save it as a layout file and then load it via LoadFile.

Cheers,
Ferdinand

Hey @ECHekman,

COLORA and VECTOR4D are both Maxon datatypes. For how to deal with custom data types, you can have a look at this. But since this is a maxon data type and not a cinema data type, you cannot use a static_cast. When you do not want to store your maxon data wrapped as data, the only thing which remains is unsafely casting the data (but our style guide recommends using reinterpret_cast to make the unsafe nature obvious).

const maxon::ColorA* myColor = reinterpret_cast<const maxon::ColorA*>(geData.GetCustomDataTypeI(DTYPE_COLORA));

I had a look and we do this in some UI related places too, so this might be a side effect of the 2024 changes to data types in relation to that specific custom gui.

Cheers,
Ferdinand

Hey,

I appreciate you separating questions But there is code for this exact question in the old thread:

https://developers.maxon.net/forum/topic/15823/data-datatypes-python-and-gui/2.

You must wrap the Data as GeData. One can of course play pointer games, as with pretty much everything, Cinema API types are usually just Maxon API types in disguise, but I would not recommend that. GeData, i.e., a BaseContainer, cannot store Data directly.

Cheers,
Ferdinand

Hi @ECHekman,

I have shown the very thing in the other threads of yours.

Cheers,
Ferdinand

Hey @Gemini,

Thank you for reaching out to us. Please have a look at Programmatically create a palette?. The TLDR is: There is no API for interacting with palettes, even internally we do not dynamically inject things into palettes (except for a few special cases) and instead rely on layout files.

Cheers,
Ferdinand

Hey @ECHekman,

you are right, IntVector32 has been wrapped by Maxime, my bad. Regarding being a new specialization or not, I guess that depends a bit on the perspective. IntVector32 is an alias for a specialization of Vec3.

And what I was hinting at, is that when you define your own specialization, as I did above for my bool vector example BoolVec3, the Python API won't automatically know how to deal with it (although it knows what a Vec3 is). But you can wrap a data type relatively easily with pure Python code yourself (check out {C4D}\resource\modules\python\libs\python311\maxon and the files vec, vec4, and vector). To then use that type you would have to either put that binding into each script, import the binding from a module in each script, or make it so that your plugin puts it into \python311\_maxon_init so that it is automatically exposed in the maxon package (please be careful with patching a users __init__.py, as it could be customized, so you cannot blindly overwrite that file).

Regarding the rest, I already lined out your options above. Maybe I am still misunderstanding you, but you cannot use a Maxon datatype as a parameter, nor can you implement your own Cinema datatype and have the Python API understand it (1). As lined out above, the best option for you is likely writing a custom GUI which emulates 2, 3, or 4 component integer vector type and sits on top of the existing data type Vector4D.

Regarding your concerns about precsion: The error in a Float64 (the underlying component type of Vector/DYTPE_VECTOR) becomes larger than 1 when the value exceeds 2^53. That is outside of the interval [-2^31, 2^31 - 1] of Int32.

Regarding the 'UI working for maxon::IntVector32': I can only speculate what you are doing there, my assumption would be that you probably have some form of dynamic description and shove that IntVector32 into the data container of the node. Feel free to expore this route, but that is not supported. (Cinema API) Descriptions must be composed out of Cinema API datatypes. The interpolation issues you encounter are like tied to how CKey::Set/GetValue and CKey::Set/GetData work and the API then getting confused about the datatype in the data container of the scene element which does not conform to a registered DTYPE_ (or on point, it likely treats your values as data although they are values).

To stress it gain, a custom GUI which wraps arround Vector4D is porbably what you want to do here. If this is not a fit, please share concrete code and a concrete usage scneario, as we won't get anywhere otherwise.

Cheers,
Ferdinand

(1) With the exception of data types which are decomposable into channels, e.g., what DTYPE_VECTOR does and many datatypes in Redshift do. So, you would then end up with a custom datatype DTYPE_FOO and the Python API would still have no clue what to with it when the user calls myNode[c4d.FOO_PARAMETER] and then raise an error. But when your data type is decomposable into known types (three DTYPE_LONG in your case), the user could call myNode[c4d.FOO_PARAMETER, c4d.VECTOR_X] to directly access the x-component of it.

Hello @Gregor-M,

when you have a problem with bit depths, please open a new thread. This is now a bug thread and we should keep it clean.

What I forgot to mention here is that there is one way to sort of fix this right now for you. There is an undocumented flag named RDATA_BAKE_OCIO_VIEW_TRANSFORM_RENDER on the render data (not the same as RDATA_BAKE_OCIO_VIEW_TRANSFORM which is exposed in the UI tto the user). With that you can bake the full transform chain into the bitmap. Such bitmap will then be displayed correctly in the PV. But when you save it to disk, it will be "incorrect", as it got the view and display transform baked into it (which is usually not what you want).

But it could be an option if you only volatiely render documents for displaying purposes only or are okay with rendering things twice (once with the flag for displaying, and once without it for saving). But that is of course very much a hack why we will fix this.

Cheers,
Ferdinand

Hey @Mats,

Thank you for reaching out to us. Is it intentional that you posted in General Talk? Because this strikes me more as an API question; although very broad in scope, which might be why you posted here.

What to use depends a bit on your goals. Graph descriptions are currently most geared towards creating new graphs from scratch. But with graph queries you can also modify existing graphs. Graph descriptions are still actively being developed, for 2025.0.0, when the docs only contained the change note about having fixed varidaic port handling I actually implemented much more, but that is currently all undocumented.

Documenting this is in my backlog, and planned for the upcoming release. Generally speaking graph descriptions are also not a new way, and the Nodes API an old way. Graph descriptions are just a more streamlined way to interact with nodes graphs (something like handling variadic ports or the undocumented node commands can either be quite complicated or outright impossible in the Python Nodes API).

But generally remains the fact that the Nodes API is the 'true' API which always will be more powerful (at least to the extent it has been wrapped for Python). My suggestion would be either to ask a concrete question what you want to do, or wait for the 2025.1 docs which are not far away. I will then have hopfeully found the time to document the new features and add some examples.

Cheers,
Ferdinand

Hey @T1001,

yes, you are on the right track there, to initialize an image as RGBA F32, you would do something like this:

static const Int32 size = 1024;
const ImageRef image = ImageClasses::IMAGE().Create() iferr_return;
const maxon::ColorProfile profile = ColorSpaces::RGBspace().GetDefaultNonlinearColorProfile();
const PixelFormat format = PixelFormats::RGBA::F32();
const Int32 channelCount = format.GetChannelCount();

// Init the bitmap with its size, storage convention, and pixel format. Whe choose here the
// "normal", i.e., consecutive layout. An alternative would be a planar layout.
image.Init(size, size, ImagePixelStorageClasses::Normal(), format) iferr_return;
image.Set(IMAGEPROPERTIES::IMAGE::COLORPROFILE, profile) iferr_return;

Regarding the rest, I roughly cover this in my example. A little GeUserArea which wraps around some render buffer data. I rather not yet share it here, as it "misbehaves" still in one aspect, and I am not sure if that is my or the API's fault (will have to catch one of the Image API devs for that).

You can also have a look at the Color Management and OCIO manual as I covered there quite a bit of pixel format and buffer handling subjects. Last but not least regarding hardware acceleration: The Image API does not have much drawing functions, that is primarily done in the semi-public Drawport API. It depends a bit on what you want to accelerate, filling a buffer cannot be accelerated, you either fill things row by row, or just wrap around some existing memory.

When you need hardware accelerated drawing functions like drawing a circle, etc., then you indeed must use the Drawport API. To get access to it as an external, you would have to apply for Maxon Registered Developer membership, as this would also grant access to the semi-public Drawport API. As its name implies, the Drawport API is the API with wich viewports are drawn in Cinema 4D. You might be familar with BaseDraw, the Cinema API type which is used to draw into view ports. Similar to how you can get an ImageRef from a BaseBitmap, you can get a DrawPortRef from a BaseDraw. Under the hood, draw ports are also used to draw into bitmaps, and there is also a mechanism with which one can attach a draw port to a dialog (a draw port user area).

But not all parts of the Drawport API are semi-public, some are fully private. I would first have to check, if the bitmap drawing part is semi-public and I know for a fact that the user area is not semi-public (but we wanted to expose it at some point but I think it never happend).

So, long story short, when you think you need all that, I would recommend reaching out via our contact form or directly apply for registered developer membership.

Cheers,
Ferdinand