C++ SDK: Release 2025.2.0

Author: mxn-ferdinand

plugins/example.assets/source/asset_api_examples/examples_assets.cpp

@@ -316,7 +316,7 @@ maxon::Result<void> LinkMediaAssets(
 			return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION, "Could not allocate shader."_s);
 
 		material->InsertShader(shader);
-		if (!material->SetParameter(ConstDescID(DescLevel(MATERIAL_COLOR_SHADER)), shader, DESCFLAGS_SET::NONE))
+		if (!material->SetParameter(ConstDescIDLevel(MATERIAL_COLOR_SHADER), shader, DESCFLAGS_SET::NONE))
 			return maxon::IllegalStateError(MAXON_SOURCE_LOCATION, "Could not link shader."_s);
 
 		// Get the asset url and check if it is empty.
@@ -326,7 +326,7 @@ maxon::Result<void> LinkMediaAssets(
 		const Filename file = MaxonConvert(url);
 
 		// Set the asset url as the filename parameter of the bitmap shader.
-		if (!shader->SetParameter(ConstDescID(DescLevel(BITMAPSHADER_FILENAME)), file, DESCFLAGS_SET::NONE))
+		if (!shader->SetParameter(ConstDescIDLevel(BITMAPSHADER_FILENAME), file, DESCFLAGS_SET::NONE))
 			return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Could not set texture file."_s);
 
 		// Name the material after the asset and insert it into the document.

plugins/example.assets/source/asset_api_examples/examples_contexts.cpp

@@ -891,7 +891,7 @@ maxon::Result<void> RunLoadMaterialAssets()
 			iferr_scope;
 
 			// Skip over asset that is not matching the search criteria.
-			maxon::AssetMetaData assetMetadata = assetDescription.GetMetaData();
+			const maxon::AssetMetaData& assetMetadata = assetDescription.GetMetaData();
 			maxon::Id assetSubtype = assetMetadata.Get(
 				maxon::ASSETMETADATA::SubType, maxon::Id()) iferr_return;
 

plugins/example.assets/source/asset_api_examples/examples_databases.cpp

@@ -563,7 +563,7 @@ maxon::Result<void> FilteredAssetSerach(const maxon::AssetRepositoryRef& reposit
 
 			// Retrieve the asset subtype of the currently yielded asset. See the metadata examples for
 			// details on the asset metadata model.
-			maxon::AssetMetaData assetMetadata = asset.GetMetaData();
+			const maxon::AssetMetaData& assetMetadata = asset.GetMetaData();
 			maxon::Id assetSubtype = assetMetadata.Get(
 				maxon::ASSETMETADATA::SubType, maxon::Id()) iferr_return;
 

plugins/example.assets/source/asset_api_examples/examples_metadata.cpp

@@ -80,7 +80,7 @@ maxon::Result<void> AccessAssetDescriptionData(const maxon::AssetDescription& as
 	// contains most of the descriptive and administrative metadata associated with an asset.
 	const maxon::AssetRepositoryRef assetRepository = assetDescription.GetRepository();
 	const maxon::Id assetRepositoryId = assetDescription.GetRepositoryId();
-	const maxon::AssetMetaData assetMetadata = assetDescription.GetMetaData();
+	const maxon::AssetMetaData& assetMetadata = assetDescription.GetMetaData();
 	ApplicationOutput("\tAsset Repository Id: @", assetRepositoryId);
 	ApplicationOutput("\tAsset Metadata: @", assetMetadata);
 
@@ -133,7 +133,7 @@ maxon::Result<maxon::AssetDescription> AddAssetVersion(
 		return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, 
 			"The repository the asset is attached to is read-only."_s);
 
-	const maxon::AssetMetaData metadata = asset.GetMetaData();
+	const maxon::AssetMetaData& metadata = asset.GetMetaData();
 	const maxon::Id subtype = metadata.Get<
 		decltype(maxon::ASSETMETADATA::SubType)>().GetOrDefault() iferr_return;
 
@@ -416,7 +416,7 @@ maxon::Result<void> IterateAssetMetadata(const maxon::AssetDescription& assetDes
 	iferr_scope;
 
 	// Get the metadata.
-	const maxon::AssetMetaData metadata = assetDescription.GetMetaData();
+	const maxon::AssetMetaData& metadata = assetDescription.GetMetaData();
 
 	// Access all existing entries and iterate over them.
 	using MetaDataTuple = maxon::Tuple<maxon::InternedId, maxon::AssetMetaData::KIND>;
@@ -444,7 +444,7 @@ maxon::Result<void> ReadAssetMetadata(const maxon::AssetDescription& assetDescri
 	ApplicationOutput("Reading Asset Metadata for: @\n", assetDescription);
 
 	// Get the metadata from the asset description.
-	const maxon::AssetMetaData metadata = assetDescription.GetMetaData();
+	const maxon::AssetMetaData& metadata = assetDescription.GetMetaData();
 	// Get the language Cinema 4D is currently running in.
 	const maxon::LanguageRef currentLanguage = maxon::Resource::GetCurrentLanguage();
 

plugins/example.assets/source/dots_preset_asset_impl/dots_preset_asset.cpp

@@ -174,12 +174,11 @@ MAXON_METHOD maxon::Result<maxon::Url> DotsPresetAssetImpl::GeneratePreview(maxo
 
 	// Get the asset description and metadata.
 	maxon::AssetDescription asset = super.GetDescription() iferr_return;
-	maxon::AssetMetaData metadata = asset.GetMetaData();
+	const maxon::AssetMetaData& metadata = asset.GetMetaData();
 
 	// Access the custom metadata attribute for the the dot scale or return a default value of 0.025
 	// when that entry has not been populated.
-	maxon::Float32 dotScale = metadata.Get(
-		maxon::ASSETMETADATA::DOTSPRESET::DOT_SCALE, 0.025F) iferr_return;
+	maxon::Float32 dotScale = metadata.Get(maxon::ASSETMETADATA::DOTSPRESET::DOT_SCALE, 0.025F) iferr_return;
 
 	// Core implementation
 	// Initialize a drawing canvas and render the thumbnail in the requested size.

plugins/example.assets/source/dots_preset_asset_impl/examples_dots.cpp

@@ -124,9 +124,8 @@ maxon::Result<void> UpdatePreviewThumbnail(
 	// Get the asset metadata and the existing or default entry of 0.025F for the dot scale. This
 	// custom metadata attribute has been defined in the dots preset asset implementation and will
 	// only be carried by that asset type.
-	maxon::AssetMetaData metadata = assetDescription.GetMetaData();
-	maxon::Float32 oldValue = metadata.Get(
-		maxon::ASSETMETADATA::DOTSPRESET::DOT_SCALE, 0.025F) iferr_return;
+	const maxon::AssetMetaData& metadata = assetDescription.GetMetaData();
+	maxon::Float32 oldValue = metadata.Get(maxon::ASSETMETADATA::DOTSPRESET::DOT_SCALE, 0.025F) iferr_return;
 
 	// The new value clamped to the interval [0.025, 0.1].
 	maxon::Float32 newValue = maxon::ClampValue(oldValue + difference, 0.025F, 0.1F);

plugins/example.hello_world/README.md

@@ -0,0 +1,10 @@
+# example.hello_world
+
+Contains a bare-bones example of a Cinema 4D module with a singular command plugin that opens a "Hello World" dialog when invoked.
+
+| Filename | Description |
+|---|---|
+| `project\projectdefinition.txt` | Contains the build configuration of the module. |
+| `source\main.cpp` | Contains all the source code of the module. |
+
+

plugins/example.hello_world/project/projectdefinition.txt

@@ -0,0 +1,26 @@
+// The platforms this project is targeting - can be [Win64;OSX;Linux].
+Platform=Win64;OSX;Linux
+
+// Type of project - can be [Lib;DLL;App], DLL is for (plugin) modules, lib for static libraries,
+// effectively frameworks, and App for standalone applications (not possible for plugins).
+Type=DLL
+
+// The frameworks dependencies of this module. One can only include header files from frameworks
+// which are listed here. The selection here is a good starting point for most projects.
+APIS=\
+asset.framework;\
+cinema.framework;\
+cinema_hybrid.framework;\
+core.framework
+
+// Enable Cinema API features for this module, and then reenable style checks again (because 
+// C4D=true disables them).
+C4D=true
+stylecheck.level=3 
+
+// The ID of the module which is being compiled. One should use the reversed domain notation, derived
+// from a domain name you own, followed by plugin qualifiers, e.g, "net.mycompany.mymodule" or
+// "net.mycompany.mysuite.mymodule". It is important that this ID is unique, as Cinema 4D will
+// not load two modules with the same ID. Please note that Cinema 4D will also not load modules
+// with a "net.maxon" domain, as this domain is reserved for Maxon modules.
+ModuleId=net.maxonexample.hello_world

plugins/example.hello_world/source/main.cpp

@@ -0,0 +1,97 @@
+/* Hello World Command Plugin
+(C) MAXON Computer GmbH, 2025
+
+Author: Ferdinand Hoppe
+Date: 27/03/2025
+
+Realizes a simple command plugin that opens a message dialog with the text "Hello World!" once it 
+has been invoked.
+
+The main focus of this example is to get the plugin message infrastructure up and running that is 
+required to register all Cinema API plugins.
+*/
+
+// -------------------------------------------------------------------------------------------------
+// This section contains the code that is usually placed in the main.cpp file of a project. It is
+// custom to separate a project into a main.cpp file - which handles all the module messages
+// for its plugins - and one or multiple files which realize the actual plugins.
+// -------------------------------------------------------------------------------------------------
+#include "c4d_plugin.h"
+#include "c4d_resource.h"
+
+// Forward declaration of the the #RegisterMyPlugin() function we implement below, so we can use
+// the function in #PluginStart below.
+bool RegisterMyPlugin();
+
+// Called by Cinema 4D in its boot sequence when this module is being loaded. This is the entry
+// point to register Cinema API plugins. A plugin which does not register itself or whose 
+// registration fails will not be accessible to users.
+cinema::Bool cinema::PluginStart()
+{
+	// Attempt to register our plugin.
+	if (!RegisterMyPlugin())
+		return false;
+	return true;
+}
+
+// Called by Cinema 4D in its shutdown sequence when this module is about to be unloaded. Most 
+// plugins use the empty implementation shown here as they do not have to free resources.
+void cinema::PluginEnd()
+{
+}
+
+// Called by Cinema 4D when a plugin message is sent to this module. There are several messages but
+// all modules must implement at least C4DPL_INIT_SYS as shown below. Otherwise the module and its 
+// plugins will not work.
+cinema::Bool cinema::PluginMessage(cinema::Int32 id, void* data)
+{
+	switch (id)
+	{
+		// g_resource is a global variable that is used to manage resources in Cinema 4D. It is 
+		// defined in the c4d_resource.h file which we include above. We cannot start our module
+		// if the resource management has not been initialized.
+		case C4DPL_INIT_SYS:
+		{
+			if (!cinema::g_resource.Init())
+				return false;
+			return true;
+		}
+	}
+	return false;
+}
+
+// -------------------------------------------------------------------------------------------------
+// This section contains the code that is usually placed in a myplugin.cpp and/or myplugin.h file.
+// It contains the actual plugin implementation and usually also the registration function for the
+// plugin as these functions must have access to the plugin class.
+// -------------------------------------------------------------------------------------------------
+
+#include "c4d.h"
+#include "c4d_gui.h"
+
+// Realizes the most basic plugin possible, a command that opens a message dialog with the text
+// "Hello World!" once it has been invoked.
+class MyPluginCommand : public cinema::CommandData
+{
+public:
+
+	// Called by Cinema 4D when this command is being invoked, either by a user pressing a menu item, 
+	// a button, or by a CallCommand() call made from C++ or Python code.
+	virtual cinema::Bool Execute(cinema::BaseDocument* doc, cinema::GeDialog* parentManager)
+	{
+		cinema::MessageDialog("Hello World!"_s);
+		return true;
+	}
+};
+
+// The ID to register the plugin with. This ID must be unique to this registration call and new IDs 
+// must be obtained from https://developers.maxon.net/forum/pid .
+const cinema::Int32 g_plugin_id = 1063013;
+
+// Calls the registration function for a CommandData plugin with an instance of our command class.
+cinema::Bool RegisterMyPlugin()
+{
+	return cinema::RegisterCommandPlugin(
+		g_plugin_id, "Hello World Command"_s, 0, nullptr, "Hello World Tooltip"_s, 
+		NewObjClear(MyPluginCommand));
+}