Implement a custom preset asset type wrapping a custom data type to be exposed by the Asset Browser.
A preset asset type allows users to read and write a custom data type exposed by a plugin into an asset database. Usually such preset asset type implementation is not just bound to a custom data type, but also to a custom GUI which is used to display the custom data in the Attribute Manger of Cinema 4D. Unlike a normal asset type, a preset asset type usually does not implement the method which is invoked when a user double clicks an asset in the Asset Browser. Instead, preset assets rely on drag and drop operations and dedicated GUIs elements being added to their data type GUI for loading and saving a preset asset.
The general logic to implement a preset asset type, is to provide a two layer implementation where the layers communicate with a dedicated data exchange type, the preset arguments PresetLoadArgs and PresetSaveArgs:
The common pattern to implement the external layer, is to implement a iCustomDataType to store the custom data and an iCustomGui to display this data as a parameter in the Attribute Manger. The iCustomGui sends and receives data from the Asset API with the preset arguments PresetLoadArgs and PresetSaveArgs, usually attaching itself or the wrapped data to these arguments, so that the asset type layer can load and store data. The pattern to implement the GUI is to add two buttons for the preset handling: One for loading a preset into the GUI and one for saving a preset. Via iCustomGui::Command these buttons then invoke the Asset API to load or store an asset. Asset drag and drop operations are handled with the DndAsset alias, a tuple containing among other data the dragged AssetDescriptionInterface reference. The drag and drop is handled as any other classic API drag and drop operation in iCustomGui::Message, where an array of DndAsset, the dragged asset(s), is then part of the message data.
The preset asset type implementation must implement a component for the BasePresetAssetInterface interface and one for the BasePresetAssetTypeInterface interface. The first component implements the functionalities that are applicable to singular asset: Creating a new instance with PresetSaveArgs, generating preview images and serializing the asset data into an asset database. The component for the BasePresetAssetTypeInterface interface implements the functionalities that are applicable to all instances of this asset type. Most importantly creating a new preset asset instance, loading, i.e., deserializing, a previously serialized asset from an asset database and handling incoming PresetLoadArgs requests from the Asset API to load an preset into passed the PresetLoadArgs.
Articles | Asset API | Provide content as reusable assets served with the Cinema 4D Asset Browser. |
Entity Creation | Explains the managed memory environment of the maxon API with interfaces and references. | |
Published Objects | Explains the concept of published objects. | |
Component Bases | Explains the component system of maxon API classes. | |
Important API Entities | iCustomDataType | Provides the base class for a custom data type implementation. |
iCustomGui | Provides the base class a custom GUI implementation which can be used to display a custom datatype. | |
CustomDataTypeClass | Provides the plugin class for custom data type implementations. | |
CustomGuiData | Provides the plugin class for custom GUI implementations. | |
AssetTypes | Contains the declarations of asset types. | |
AssetDescriptionInterface | Represents an asset over its metadata in an asset repository. | |
BasePresetAssetInterface | Provides the base implementation for the functionalities of a singular preset asset. | |
BasePresetAssetTypeInterface | Provides the base implementation for the functionalities applicable to all preset assets of a specific type. | |
PresetLoadArgs | Provides a helper data structure that is used to exchange incoming preset asset data with the Asset API for preset asset implementations. | |
PresetSaveArgs | Provides a helper data structure that is used to exchange outgoing preset asset data with the Asset API for preset asset implementations. | |
DndAsset | Provides a helper data structure that is used in asset drag and drop operations. | |
SDK Plugins | Dots Preset Asset Implementation | Showcases the implementation of a custom preset asset type in conjunction with a custom datatype and GUI. |
Examples | Implement a Preset Asset Type | Implement a preset asset and asset type. |
Implement a Data Type for a Preset Asset Type | Implement a data type wrapped by a preset asset. | |
Load Assets into a GUI | Provides an example pattern for loading preset assets into a iCustomGui. | |
Save Assets from a GUI | Provides an example pattern for creating preset assets from the data attached to a iCustomGui. | |
Instantiate a Preset | Instantiate an implemented preset asset type from its custom data type. | |
Invoke Asset Implementation | Showcases how to access the implementation of an asset type from an asset description. |
Implements the Dots preset asset type that is targeted by the dots data type and GUI.
The preset asset type implementation must implement a component for the BasePresetAssetInterface interface and one for the BasePresetAssetTypeInterface interface. The first component implements the functionalities that are applicable to singular asset: Creating a new instance with PresetSaveArgs, generating preview images and serializing the asset data into an asset database. The component for the BasePresetAssetTypeInterface interface implements the functionalities that are applicable to all instances of this asset type. Most importantly creating a new preset asset instance, loading, i.e., deserializing a previously serialized asset from an asset database and handling incoming PresetLoadArgs requests from the Asset API to load a preset into the passed PresetLoadArgs.
Implements a custom datatype with a custom GUI that accommodates a matching preset asset type.
The core elements of this implementation are DotsData
and DotsGui
. DotsData implements the custom data type and DotsGui a dialog that is used to render that data type as a parameter in the Attribute Manger.
DotsGui is a iCustomGui which inherits from GeDialog and attaches three gadgets to itself.
DotsUserArea
instance, which renders a preview of the DotsData attached to the DotsGui.DotsPresetAsset
with the help of a popup dialog.Both the DotsData and DotsGui implementation are exposed as plugin interfaces to the classic API, handling the data type and its GUI. For DotsData it is DotsDataClass
and for DotsGui it is DotsGuiData
. These types are then used to register the data type and its GUI as plugins with Cinema 4D.
The example also showcases the bindings of a custom GUI and datatype to the Asset API, so that users can save and load preset assets from within the GUI of the data type. This is primarily realized with the two buttons in the custom GUI, the "Load Preset..." and "Save Preset..." buttons. In DotsGui::Command()
the click messages for these buttons are then handled and DotsData is being sent to or retrieved from the Asset API DotsPresetAsset type implementation. Asset drag and drop events are being handled in a similar fashion in DotsGui::Message()
.
Provides an example pattern for loading preset assets into a iCustomGui.
Provides an example pattern for creating preset assets from the data attached to a iCustomGui.
Demonstrates how to instantiate a preset asset with its data type.
How a preset asset can be instantiated from their targeted data type depends on the implementation of the preset asset. The pattern shown here applies to the dots preset asset example and some native preset asset types of Cinema 4D, but there is no guarantee that all preset asset types directly wrap their data type in the PresetSaveArgs.
Showcases how to access the implementation of an asset type from an asset description.
An asset thumbnail can be updated with AddPreviewRenderAsset in a more convenient fashion. This example demonstrates how to load the asset interface from an asset description and then invoke one of the implementations of its components. It is an example case for what has been lined out in Asset Types as the rare case of having to invoke methods of an maxon::AssetInterface instance for an asset directly.
The The Dots Preset Asset Type makes its preview thumbnails dependent on a custom meta data attribute called DOTS_SCALE. The example showcases how to write that attribute and how to manually update the preview image by calling the dots preset asset implementation.