Implementing Preset Assets

Table of Contents

• Overview
• Technical Overview
• Related Topics
  • Implement a Preset Asset Type
  • Implement a Data Type for a Preset Asset Type
  • Load Assets into a GUI
  • Save Assets from a GUI
  • Instantiate a Preset
  • Invoke Asset Implementation

Implement a custom preset asset type wrapping a custom data type to be exposed by the Asset Browser.

Overview

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.

Fig I: Preset assets can be saved and loaded with the buttons in the custom GUI that complements their data type and preset assets of matching type can be dragged into the GUI to load them into it. Preset assets can also generate preview thumbnails that reflect their stored data in the Asset Browser.

Technical Overview

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:

• An external layer which defines a custom data type and GUI, and
• an asset layer which implements a preset asset type for that data type and its GUI.

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.

Fig II: A simplified overview of implementing a preset asset type. Shown in green is the external layer and in blue the preset asset logic layer. It is the custom GUI implementation which actively sends data to the Asset API when the user wants to save or load a custom data type as an asset.

Related Topics

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.

Examples

Implement a Preset Asset Type

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.

dots_preset_asset.h dots_preset_asset.cpp

#ifndef SDK_PRESET_ASSET_TYPE_H__
#define SDK_PRESET_ASSET_TYPE_H__
 
#include "maxon/apibase.h"
#include "maxon/assets.h"
#include "maxon/base_preset_asset.h"
 
#include "dots_datatype.h"
 
// A published object is an object that is globally accessible within a Cinema 4D instance. Search 
// for "Published Objects" in the C++ SDK documentation for details on the subject of publishing 
// objects.
 
// The maxon API requires published objects to be declared for the implemented preset asset. They 
// primarily act as symbols for the preset asset type and class. A good pattern for the ids is: 
// 
//  "com.mycompany.assettype.myasset"
//  "com.mycompany.class.myasset"
 
// Declare the published object for dots asset type. It is mandatory to publish the objects in 
// these exact namespaces so that the Asset API can find them at runtime.
namespace maxon::AssetTypes
{
  MAXON_DECLARATION(BasePresetAssetType, DotsPresetAsset, "net.maxonexample.assettype.dotpreset");
};
 
// Declare a published object for dots asset type class.
namespace maxon::PresetAssetImplementations
{
  MAXON_DECLARATION(
    Class<BasePresetAsset>, DotsPresetAssetClass, "net.maxonexample.class.dotpreset");
};
 
// Declare a custom metadata attribute to describe the dot scale of dot asset thumbnails. Defining
// custom metadata attributes is optional. The source-processor will generate the files 
// dots_preset_asset1.hxx and dots_preset_asset2.hxx which must be included for this attribute to 
// be correctly exposed.
#include "dots_preset_asset1.hxx"
namespace maxon::ASSETMETADATA::DOTSPRESET
{
  MAXON_ATTRIBUTE(maxon::Float32, DOT_SCALE, "net.maxonexample.asset.dotpreset.dotscele");
};
#include "dots_preset_asset2.hxx"
 
// Renders a preview of the passed dots data.
// 
// @param[out] canvas     The canvas to draw into. 
// @param[in] data        The dots data to draw.
// @param[in] size        The size in pixels of the requested preview thumbnail.
// @param[in] dotScale    The size of a dot in relation to the preview size. E.g., 0.1 will mean
//                        that for a preview size of 100 each dot will be 10 pixels large.
maxon::Result<void> RenderPreview(
  GeClipMap* canvas, const DotsData* data, const maxon::Int32 size, const maxon::Float32 dotScale);
 
// Provides the dots preset asset implementation.
//
// The preset asset implementation handles a single asset. This implementation is only functional 
// in cooperation with the corresponding asset type implementation which is declared below as 
// DotsPresetAssetTypeImpl. Its key methods are the two Init() methods to instantiate an asset
// in memory from DotsData and from serialized data on disk, the Serialize() method to serialize 
// an asset in memory to an asset database, and the GeneratePreview() method to provide
// preview thumbnails for the Asset Browser.
// 
// @warning    It is important to implement all members for BasePresetAssetInterface, even the ones 
//             which seemingly serve no purpose as for example DotsPresetAssetImpl::Apply(). If 
//             these empty implementations are skipped, the solution will compile, but the 
//             construction of the BasePresetAssetInterface for a DotsPresetAsset will fail at 
//             runtime, as this component will then not adhere to the BasePresetAssetInterface 
//             interface signature.
class DotsPresetAssetImpl: 
  public maxon::Component<DotsPresetAssetImpl, maxon::BasePresetAssetInterface>
{
  // This is a BasePresetAssetInterface component which is final. It is always going to be the last 
  // component in the component list of a BasePresetAssetInterface instance, and therefore its 
  // methods cannot be overridden by other components.
  MAXON_COMPONENT(FINAL, maxon::BasePresetAssetClass);
 
public:
 
  // Called when the user invokes the asset in the Asset Browser.
  //
  // Usually not implemented for preset assets as applying them is handled with drag and drop
  // operations or the "Load Preset ..." button in the GUI of the data type.
  MAXON_METHOD maxon::Result<void> Apply() const;
 
  // Convert an asset from the old Content Browser format into an Asset Browser asset.
  //
  // Not implemented in this example.
  MAXON_METHOD maxon::Result<void> ConvertFromLegacyBrowser(
    Int32 pluginId, const maxon::Block<const Char>& memBlock, const BaseContainer& settings,
    const String& name, maxon::DataDictionary& metaProperties, maxon::AddAssetMetaData& addMetaData,
    maxon::AddAssetDepencendyStruct& addDependencyStruct,
    maxon::ResolveAssetDependenciesStruct& resolveAssets);
 
  // Initializes an asset instance from preset data.
  // 
  // This form of intilization is invoked when the user presses the "Save Preset ..." button in
  // the custom gui. It will invoke AssetCreationInterface::SaveBrowserPreset() which then will
  // invoke CreateInit() for the implemented asset interface, causing this method to be called.
  // 
  // @param[in] sourceData    The data to be wrapped, a pointer to an instance of DotsData.
  maxon::Result<void> Init(const maxon::PresetSaveArgs& sourceData);
 
  // Initializes an asset instance from serialized data.
  // 
  // This form of intilization is invoked when a repository must deserialize data that previously
  // has been serialized with DotsPresetAssetImpl::Serialize(). The structure of the data found
  // at #presetUrl depends on what is being carried out in Serialize().
  // 
  // @param[in] asset        The asset description of the asset to deserialize the data for.
  // @param[in] presetUrl    The location of the data to deserialize.
  maxon::Result<void> Init(const maxon::AssetDescription& asset, const maxon::Url& presetUrl);
 
  // Generates a preview image for the asset instance.
  // 
  // Called by the Asset Browser to populate its asset preview tiles.
  // 
  // @param[in] previewSize      The size of a tile in the Asset Browser to render for.
  // @param[in] progressRef      An interface to communicate progress.
  // @param[in] progressIndex    The progress index.
  // 
  // @return                     The url of the generated preview image.
  MAXON_METHOD maxon::Result<maxon::Url> GeneratePreview(maxon::Int previewSize,
    const maxon::ProgressRef& progressRef, maxon::Int progressIndex) const;
 
  // Returns the asset type for this asset instance.
  // 
  // Returns maxon::AssetTypes::DotsPresetAsset() as published at the top of this file.
  MAXON_METHOD const maxon::AssetType& GetType() const;
 
  // Called to serialize the asset instance to an output stream.
  // 
  // Called by an asset repository when an asset must be serialized to a database. Serialized must 
  // only be the custom data type data, not the asset metadata stored in the AssetDescription and 
  // AssetMetadata which are handled by the Asset API.
  // 
  // @param[out] outputStream    The stream to write the serialized data to.
  MAXON_METHOD maxon::Result<void> Serialize(const maxon::OutputStreamRef& outputStream) const;
 
  // Accesses the internal DotsData attached to the asset instance.
  //
  // This is a member of the specific pattern shown in this example and not a member of 
  // BasePresetAssetInterface.
  const DotsData* GetCustomData() const;
 
private:
  // The custom data attached to the preset asset instance, in this case an instance of DotsData.
  // Neither the naming of the field nor its existence is formally required, but the implementation 
  // pattern shown here does store the primary data attached to an asset instance in this way.
  AutoAlloc<DotsData> _customData;
};
 
 
// Provides the dots preset asset type implementation.
//
// The preset asset type implementation handles operations applicable to all assets of this type. 
// This implementation is only functional in cooperation with the corresponding singular asset 
// implementation which is declared above as DotsPresetAssetImpl.
// 
// Its most important methods are CreateNewPresetSettings() to create a new dots preset asset
// instance and the Load() method to handle incoming calls to the asset API to unpack preset asset
// data into an external entity; a DotsGui in this case.
// 
// @warning    Just as for DotsPresetAssetImpl it is important to implement all members for 
//             BasePresetAssetTypeInterface.
// 
// @warning    It is important to return the asset type id returned by GetId() in exactly the manner
//             which is shown here with a maxon::Id reference attched to the DotsPresetAssetTypeImpl
//             instance.
class DotsPresetAssetTypeImpl: 
  public maxon::Component<DotsPresetAssetTypeImpl, maxon::BasePresetAssetTypeInterface>
{
  // This is a component for a BasePresetAssetTypeInterface.
  MAXON_COMPONENT(NORMAL, maxon::AssetTypeBasePresetClass);
 
public:
  // The type identifier for the implemented asset type.
  const maxon::Id _typeId = maxon::AssetTypes::DotsPresetAsset.GetId();
 
  // Creates a new asset instance from the raw data which are wrapped by the asset.
  // 
  // The passed arguments contain an PresetSaveArgs instance and this implementation then calls
  // the DotsPresetAssetImpl::Init() overload which accepts PresetSaveArgs to create an asset
  // instance.
  // 
  // @param[in] args    The raw data to create a new asset instance for.
  MAXON_METHOD maxon::Result<void> CreateNewPresetSettings(
    maxon::CreatePresetAssetStruct& args) const;
 
  // Returns the the asset type this implementation is representing.
  MAXON_METHOD const maxon::DataType& GetAssetDataType() const;
 
  // Returns the identifier of the asset type.
  // 
  // As explained in the class description, it is important to follow the exact pattern shown here,
  // as otherwise the asset type will fail when assets must be saved and loaded.
  MAXON_METHOD const maxon::Id& GetId() const;
 
  // Returns the asset type alias as shown in the Asset Browser.
  MAXON_METHOD maxon::String GetName() const;
 
  // Used to deserialize an asset from an asset database.
  // 
  // This implementation ignores most of its input arguments and wraps around the 
  // DotsPresetAssetImpl::Init() method which accepts an asset description and url to instantiate
  // an asset.
  // 
  // @param[in] repo                The repository which is requesting the loading.
  // @param[in] assetDescription    The asset description for the to be loaded asset. 
  // @param[in] url                 The location of the primary data of the asset to deserialize.
  // @param[in] updateLinks         Private.
  MAXON_METHOD maxon::Result<maxon::Asset> Load(
    const maxon::AssetRepositoryRef& repo, const maxon::AssetDescription& assetDescription,
    const maxon::Url& url, maxon::Bool* updateLinks) const;
 
  // Handles incoming requests from the outside of the Asset API to load an preset asset into
  // a target passed with the PresetLoadArgs.
  // 
  // @param[in] preset         The data to load, a DotsPresetAsset in this case.
  // @param[in, out] target    The entity to load into, a DotsGui in this case.
  MAXON_METHOD maxon::Bool LoadPreset(
    const maxon::BasePresetAsset& preset, const maxon::PresetLoadArgs& target) const;
};
 
#endif // SDK_PRESET_ASSET_TYPE_H__

Example on GitHub

#include "c4d_basebitmap.h"
#include "c4d_resource.h"
#include "c4d_symbols.h"
#include "lib_clipmap.h"
 
#include "maxon/file_utilities.h"
#include "maxon/iomemory.h"
 
#include "dots_preset_asset.h"
 
// --- The thumbnail rendering for Dots assets -----------------------------------------------------
 
maxon::Result<void> RenderPreview(
  GeClipMap* canvas, const DotsData* data, const maxon::Int32 size, const maxon::Float32 dotScale)
{
  iferr_scope;
 
  if (!canvas)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION, "Null pointer canvas."_s);
  if (!data)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION, "Null pointer dots data."_s);
 
  // Attempt to initialize the canvas.
  const IMAGERESULT res = canvas->Init(size, size, 32);
  if (res != IMAGERESULT::OK)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION, "Could not init canvas."_s);
 
  // The scaling factor between the dots data and the requested preview size.
  maxon::Float32 sizef = static_cast<Float32>(size);
  const maxon::Float32 scalingFactor = sizef / static_cast<Float32>(data->canvasSize);
 
  // The size of one dot in relation to the preview size.
  maxon::Int32 dotSize = static_cast<maxon::Int32>(sizef * dotScale);
 
  // Start drawing and fill the background.
  canvas->BeginDraw();
  canvas->SetColor(175, 175, 175);
  canvas->FillRect(0, 0, size - 1, size - 1);
 
  // Draw the dots.
  canvas->SetColor(50, 50, 50);
  maxon::Vector p;
 
  for (maxon::Int32 i = 0; i < data->points.GetCount(); i++)
  {
    p = data->points[i] * scalingFactor;
    canvas->FillRect(static_cast<maxon::Int32>(p.x - dotSize),
                     static_cast<maxon::Int32>(p.y - dotSize),
                     static_cast<maxon::Int32>(p.x + dotSize),
                     static_cast<maxon::Int32>(p.y + dotSize));
  }
  canvas->EndDraw();
 
  return maxon::OK;
}
 
// --- SDKPresetAssetImpl implementations ----------------------------------------------------------
 
MAXON_METHOD maxon::Result<void> DotsPresetAssetImpl::Apply() const
{
  iferr_scope;
 
  // Not implemented. 
 
  return maxon::OK;
}
 
MAXON_METHOD maxon::Result<void> DotsPresetAssetImpl::ConvertFromLegacyBrowser(
  Int32 pluginId, const maxon::Block<const Char>& memBlock, const BaseContainer& settings,
  const String& name, maxon::DataDictionary& metaProperties, maxon::AddAssetMetaData& addMetaData,
  maxon::AddAssetDepencendyStruct& addDependencyStruct,
  maxon::ResolveAssetDependenciesStruct& resolveAssets)
{
  iferr_scope;
 
  // Not implemented. 
 
  return maxon::OK;
}
 
maxon::Result<void> DotsPresetAssetImpl::Init(const maxon::PresetSaveArgs& sourceData)
{
  iferr_scope;
 
  // Get the custom data passed by the PresetSaveArg.
  DotsData* dotsData = (DotsData*)sourceData.GetPointer();
  if (MAXON_UNLIKELY(dotsData == nullptr))
    return maxon::NullptrError(MAXON_SOURCE_LOCATION, "Could not access preset data."_s);
 
  // Assumed is here that there is no illegal preset state for this asset, e.g., an BaseArray 
  // inside the DotsData with no points/dots in it. When certain asset data should be rejected, 
  // an error must be returned at this point.
  //
  // if (receivedData->_points.GetCount() < 1)
  //    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Illegal empty preset state.")
 
  // Copy the received custom data over to the custom data attached to the asset.
  dotsData->CopyTo(_customData) iferr_return;
  return maxon::OK;
}
 
maxon::Result<void> DotsPresetAssetImpl::Init(
  const maxon::AssetDescription& asset, const maxon::Url& presetUrl)
{
  iferr_scope;
 
  // This method is the counterpart to DotsPresetAssetImpl::Serialize() and would be named more
  // aptly as DotsPresetAssetImpl::Deserialize(). Its name as an overload of Init() is however
  // required by the ObjectInterface instation of the maxon API with ::CreateInit(). What has to
  // be done here depends on how the data has been serialized before in DotsPresetAssetImpl::
  // Serialize().
 
  // Create a HyperFile and read the data from the preset asset url into it.
  AutoAlloc<HyperFile> hyperFile;
  if (!hyperFile)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not allocate HyperFile."_s);
 
  if (!hyperFile->Open(0, MaxonConvert(presetUrl), FILEOPEN::READ, FILEDIALOG::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not read-open HyperFile."_s);
 
  // Attempt to read the first element of the HyperFile as a GeData instance.
  GeData geData;
  if (!hyperFile->ReadGeData(&geData))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Unexpected serialization format."_s);
  if (!hyperFile->Close())
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not close HyperFile."_s);
 
  // Extract the DotsData from the GeData container and copy them to the DotsData attached to the
  // preset asset instance.
  DotsData* data = (DotsData*)geData.GetCustomDataType(PID_CUSTOMDATATYPE_DOTS);
  data->CopyTo(_customData) iferr_return;
 
  return maxon::OK;
}
 
MAXON_METHOD maxon::Result<maxon::Url> DotsPresetAssetImpl::GeneratePreview(maxon::Int previewSize,
  const maxon::ProgressRef& progressRef, maxon::Int progressIndex) const
{
  iferr_scope;
 
  // This implementation does a little bit more than absolutely necessary, as it accesses the
  // metadata of the asset which is being rendered as a preview thumbnail to customize the output. 
  // Go to  the comment "// Core implementation" to skip this part.
 
  // Get the asset description and metadata.
  maxon::AssetDescription asset = super.GetDescription() iferr_return;
  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;
 
  // Core implementation
  // Initialize a drawing canvas and render the thumbnail in the requested size.
  AutoAlloc<GeClipMap> canvas;
  RenderPreview(canvas, _customData, static_cast<maxon::Int32>(previewSize), dotScale) iferr_return;
 
  const BaseBitmap* bmp = canvas->GetBitmap();
  if (!bmp)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Preview rendering failed."_s);
 
  // Write the bitmap into a in-memory png file.
  maxon::Url url = CreateMemoryFileWithSuffix("png"_s) iferr_return;
  if (IMAGERESULT::OK != bmp->Save(MaxonConvert(url), FILTER_PNG, nullptr, SAVEBIT::NONE))
    return maxon::IllegalStateError(MAXON_SOURCE_LOCATION);
 
  return url;
}
 
MAXON_METHOD const maxon::AssetType& DotsPresetAssetImpl::GetType() const
{
  // Return the preset asset type published in the header file.
  return maxon::AssetTypes::DotsPresetAsset();
}
 
MAXON_METHOD maxon::Result<void> DotsPresetAssetImpl::Serialize(
  const maxon::OutputStreamRef& outputStream) const
{
  iferr_scope;
 
  // Create a writable file in memory and a HyperFile to store the custom data.
  maxon::Url memFile = maxon::CreateMemoryFileWithSuffix() iferr_return;
  AutoAlloc<HyperFile> hyperFile;
  if (!hyperFile)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not allocate HyperFile."_s);
 
  // Open the HyperFile in memory which can be then be treated as a physical file with an url.
  if (!hyperFile->Open(0, MaxonConvert(memFile), FILEOPEN::WRITE, FILEDIALOG::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not write-open HyperFile."_s);
 
  // Pack the custom data attached to the asset into GeData and write them into the HyperFile.
  GeData geData;
  geData.SetCustomDataType(PID_CUSTOMDATATYPE_DOTS, *_customData);
  if (!hyperFile->WriteGeData(geData))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not write to HyperFile."_s);
  if (!hyperFile->Close())
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not close HyperFile."_s);
 
  // And finally write the in-memory file into the output stream.
  maxon::InputStreamRef inputStream = memFile.OpenInputStream() iferr_return;
  maxon::FileUtilities::CopyStream(inputStream, outputStream) iferr_return;
 
  return maxon::OK;
}
 
const DotsData* DotsPresetAssetImpl::GetCustomData() const
{
  // Return the raw DotsData attached to this asset instance.
  return _customData;
}
 
// Register the DotsPresetAsset component. This cannot be done in the header file.
MAXON_COMPONENT_CLASS_REGISTER(
  DotsPresetAssetImpl, maxon::PresetAssetImplementations::DotsPresetAssetClass);
 
// --- SDKPresetAssetTypeImpl implementation -------------------------------------------------------
 
MAXON_METHOD maxon::Result<void> DotsPresetAssetTypeImpl::CreateNewPresetSettings(
  maxon::CreatePresetAssetStruct& args) const
{
  iferr_scope;
 
  // Initialize a dots preset asset with the passed data.
  args._resAsset = DotsPresetAssetImpl::CreateInit(args._sourceData) iferr_return;
  return maxon::OK;
}
 
MAXON_METHOD const maxon::DataType& DotsPresetAssetTypeImpl::GetAssetDataType() const
{
  // Return the data type of the asset type as defined by the published objects.
  return DotsPresetAssetImpl::GetClass().GetDataType();
}
 
MAXON_METHOD const maxon::Id& DotsPresetAssetTypeImpl::GetId() const
{
  return _typeId;
}
 
MAXON_METHOD maxon::String DotsPresetAssetTypeImpl::GetName() const
{
  return maxon::String(GeLoadString(IDS_DOTS_ASSET));
}
 
MAXON_METHOD maxon::Result<maxon::Asset> DotsPresetAssetTypeImpl::Load(
  const maxon::AssetRepositoryRef& repo, const maxon::AssetDescription& assetDescription,
  const maxon::Url& url, maxon::Bool* updateLinks) const
{
  iferr_scope;
 
  // Making use of the Init() implementation provided above in DotsPresetAssetImpl to load an 
  // asset from its asset description and url.
  maxon::Asset asset = DotsPresetAssetImpl::CreateInit(assetDescription, url) iferr_return;
  return std::move(asset);
}
 
MAXON_METHOD maxon::Bool DotsPresetAssetTypeImpl::LoadPreset(
  const maxon::BasePresetAsset& preset, const maxon::PresetLoadArgs& target) const
{
  iferr_scope_handler
  {
    return false;
  };
 
  // Bail when the target data has not been set properly.
  if (!target.GetPointer())
    return true;
 
  // Attempt to instantiate the specific preset type and retrieve the custom data attached to it.
  const DotsPresetAssetImpl* impl = DotsPresetAssetImpl::GetOrNull(preset);
  if (!impl)
    return false;
 
  const DotsData* data = impl->GetCustomData();
  if (!data)
    return false;
 
  // Write the data into the custom GUI of the target passed by the PresetLoadArgs, which will
  // also be a DotsGui as established by convention in a dots preset asset.
  DotsGui* targetGui = (DotsGui*)target.GetPointer();
  if (MAXON_UNLIKELY(!targetGui))
    return false;
 
  TriState<GeData> packedData;
  packedData.Add(GeData(PID_CUSTOMDATATYPE_DOTS, *data));
 
  return targetGui->SetData(packedData);
}
 
// Register the DotsPresetAsset type component. This cannot be done in the header file.
MAXON_COMPONENT_OBJECT_REGISTER(DotsPresetAssetTypeImpl, maxon::AssetTypes::DotsPresetAsset);

Example on GitHub

Implement a Data Type for a Preset Asset Type

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.

1. A DotsUserArea instance, which renders a preview of the DotsData attached to the DotsGui.
2. A "Load Preset ..." button to load a preset asset of type DotsPresetAsset with the help of a popup dialog.
3. A "Save Preset ..." button to save the DotsData shown in the DotsGui as a DotsPresetAsset which is exposed by the Asset Browser.

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().

dots_datatype.h dots_datatype.cpp

#ifndef CUSTOMDATA_CUSTOMGUI_H__
#define CUSTOMDATA_CUSTOMGUI_H__
 
#include "c4d_baselist.h"
#include "c4d_customdatatype.h"
#include "c4d_gui.h"
#include "c4d_symbols.h"
 
#include "maxon/assets.h"
 
// The size of a DotsUserArea drawing canvas. 
const maxon::Int32 g_dots_canvas_size = 200;
// Forward declaration for the DotsData friend access modifier.
class DotsDataClass;
 
// Provides a data structure to store an array of points on a fixed size canvas.
class DotsData : public iCustomDataType<DotsData>
{
  friend class DotsDataClass;
 
public:
  DotsData() {}
  ~DotsData() {}
 
  maxon::BaseArray<maxon::Vector> points;
 
  maxon::Int32 canvasSize = g_dots_canvas_size;
 
  // Copies the data from this instance to #dest.
  // 
  // @param[in] dest    The target to copy to.
  // 
  // @return            The number of points copied.
  maxon::Result<maxon::Int32> CopyTo(DotsData& dest);
};
 
// Represents a gadget which can be added to dialogs that renders an instance of DotsData.
//
// Used by DotsGui and does not contain any Asset API relevant code.
class DotsUserArea : public GeUserArea
{
public:
  DotsUserArea();
  virtual ~DotsUserArea();
 
  virtual Bool Init();
  virtual Bool InitValues();
  virtual Bool GetMinSize(Int32& w, Int32& h);
 
  virtual void DrawMsg(Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer& msg);
  virtual Bool InputEvent(const BaseContainer& msg);
 
  DotsData* _data;
};
 
// Represents the custom GUI interface that handles a DotsData parameter in the Attribute Manager.
//
// This contains all the code handling the Asset API dots preset asset type implementation from the 
// classic API side, this custom GUI. The methods containing code relevant for the Asset API are 
// DotsGui::Command(), DotsGui::Message(), DotsGui::LoadAsset(), and DotsGui::SaveAsset().
class DotsGui : public iCustomGui
{
  INSTANCEOF(DotsGui, iCustomGui)
 
private:
  Bool _tristate;
  DotsData _data;
  DotsUserArea _dotsUserArea;
 
public:
  DotsGui(const BaseContainer &settings, CUSTOMGUIPLUGIN *plugin);
  virtual Bool CreateLayout();
  virtual Bool InitValues();
  virtual Bool SetData(const TriState<GeData>& tristate);
  virtual TriState<GeData> GetData();
 
  // Receives dialog gadget events for the custom GUI.
  // 
  // Used in this example to handle the "Load Asset ..." and "Save Asset ..." buttons. Sends and
  // receives data with the Asset API by sending itself as SavePresetArgs and LoadPresetArgs,
  // to the DotsPresetAsset type implementation to load or save DotsData into this DotsGui 
  // instance.
  // 
  // @param[in] id     The dialog gadget which received a user interaction.
  // @param[in] msg    The event data.
  // 
  // @return           If the event was consumed or not.
  virtual Bool Command(Int32 id, const BaseContainer &msg);
 
  // Receives messages sent to the iCustomGui dialog.
  // 
  // Used in this example to handle asset drag and drop events onto the custom GUI. Receives data 
  // from the Asset API in form of DndAsset tuples and then sends data to the Asset API to load
  // unpack the DotsData wrapped by the dragged asset into this DotsGui instance.
  // 
  // @param[in] msg            The message event and event data.
  // @param[in, out] result    The message data.
  // 
  // @return                   Depends on the type of message.
  virtual Int32 Message(const BaseContainer& msg, BaseContainer& result);
 
  // Handles loading assets into the GUI.
  // 
  // Both asset drag and drop events and "Load Asset..." button clicks will use this method. This
  // method is not an overload of iCustomGui and things must not be implemented in this way, but it
  // is the approach chosen here to abstract the process of asset loading.
  //
  // @param[in] assetDescription    The asset to load into the GUI.
  maxon::Result<void> LoadAsset(const maxon::AssetDescription& assetDescription);
 
  // Handles saving assets from the current state of the GUI. This method is not an overload of
  // 
  // Saved will be _data of the GUI instance. This method is not an overload of iCustomGui and 
  // things must not be implemented in this way, but it is the approach chosen here to abstract 
  // the process of asset saving.
  maxon::Result<void> SaveAsset();
};
 
 
static Int32 g_stringtable[] = { PID_CUSTOMDATATYPE_DOTS };
 
 
// Provides the plugin interface for the custom GUI.
//
// This does not contain any code relevant for the Asset API.
class DotsGuiData : public CustomGuiData
{
public:
  virtual Int32 GetId();
  virtual CDialog* Alloc(const BaseContainer& settings);
  virtual void Free(CDialog* dlg, void* userdata);
  virtual const Char* GetResourceSym();
  virtual CustomProperty* GetProperties();
  virtual Int32 GetResourceDataType(Int32*& table);
 
};
 
 
// Provides the plugin interface for the custom datatype.
//
// This does not contain any code relevant for the Asset API.
class DotsDataClass : public CustomDataTypeClass
{
  INSTANCEOF(DotsDataClass, CustomDataTypeClass)
 
public:
  virtual Int32 GetId();
  virtual CustomDataType* AllocData();
  virtual void FreeData(CustomDataType* data);
  virtual Bool CopyData(const CustomDataType* src, CustomDataType* dst, AliasTrans* aliastrans);
  virtual Int32 Compare(const CustomDataType* d1, const CustomDataType* d2);
  virtual Bool WriteData(const CustomDataType* t_d, HyperFile* hf);
  virtual Bool ReadData(CustomDataType* t_d, HyperFile* hf, Int32 level);
  virtual const Char* GetResourceSym();
  virtual void GetDefaultProperties(BaseContainer& data);
};
 
 
// Registers the dots datatype and GUI
Bool RegisterDotsDataAndGui();
 
#endif // CUSTOMDATA_CUSTOMGUI_H__

Example on GitHub

#include "c4d.h"
 
#include "maxon/asset_creation.h"
#include "maxon/asset_draganddrop.h"
#include "maxon/assetmanagerinterface.h"
#include "maxon/base_preset_asset.h"
#include "maxon/datadescription_string.h"
#include "maxon/sortedarray.h"
#include "maxon/stringresource.h"
 
#include "dots_preset_asset.h"
#include "dots_datatype.h"
 
// --- The dots data type implementation -----------------------------------------------------------
 
maxon::Result<maxon::Int32> DotsData::CopyTo(DotsData& dest)
{
  iferr_scope;
 
  dest.points.Flush();
  dest.points.CopyFrom(points) iferr_return;
  dest.canvasSize = canvasSize;
 
  return (maxon::Int32)dest.points.GetCount();
}
 
// --- The implementation of the user area used to render DotsData ---------------------------------
 
DotsUserArea::DotsUserArea()
{
  _data = nullptr;
}
 
DotsUserArea::~DotsUserArea()
{
  
}
 
Bool DotsUserArea::Init()
{
  return true;
}
 
Bool DotsUserArea::InitValues()
{
  return true;
}
 
Bool DotsUserArea::GetMinSize(Int32& w, Int32& h)
{
  w = g_dots_canvas_size;
  h = g_dots_canvas_size;
  return true;
}
 
void DotsUserArea::DrawMsg(Int32 x1, Int32 y1, Int32 x2, Int32 y2, const BaseContainer& msg)
{
  this->OffScreenOn();
 
  // drawing the white background
  this->DrawSetPen(Vector(1.0));
  this->DrawRectangle(0, 0, g_dots_canvas_size, g_dots_canvas_size);
 
  // if the data is defined for each dot a rectangle is drawn
  if (_data)
  {
    this->DrawSetPen(Vector(0.0));
 
    for (Int32 i = 0; i < _data->points.GetCount(); ++i)
    {
      const Vector vec = _data->points[i];
      this->DrawRectangle(SAFEINT32(vec.x)-5, SAFEINT32(vec.y)-5, 
                          SAFEINT32(vec.x) + 5, SAFEINT32(vec.y) + 5);
    }
  }
}
 
Bool DotsUserArea::InputEvent(const BaseContainer& msg)
{
  // check the input device
  switch (msg.GetInt32(BFM_INPUT_DEVICE))
  {
    // some mouse interaction
    case  BFM_INPUT_MOUSE:                                  
    {
      // get the cursor position
      Int32 mx = msg.GetInt32(BFM_INPUT_X);
      Int32 my = msg.GetInt32(BFM_INPUT_Y);
      Global2Local(&mx, &my);
 
      // add the new position to the data
      iferr (_data->points.Append(Vector(mx, my, 0)))
        return false;
 
      // inform the parent that the data has changed
      BaseContainer m(BFM_ACTION);
      m.SetInt32(BFM_ACTION_ID, GetId());
      SendParentMessage(m);
 
      return true;
    }
  }
  return false;
}
 
// --- The implementation of the iCustomGui that handles the data type to Asset API interactions ---
 
DotsGui::DotsGui(
  const BaseContainer &settings, CUSTOMGUIPLUGIN *plugin) : iCustomGui(settings, plugin)
{
  _tristate = false;
};
 
Bool DotsGui::CreateLayout()
{
  BaseContainer bc;
 
  GroupBegin(1000, BFH_SCALEFIT|BFV_FIT, 1, 1, String(), 0);
  {
    GroupSpace(5, 5);
 
    // creating the GeUserArea
    C4DGadget* userarea = this->AddUserArea(ID_USERAREA, BFH_LEFT, 400, 300);
    this->AttachUserArea(_dotsUserArea, userarea);  
 
    // assigning the data
    _dotsUserArea._data = &_data;
 
    // The buttons for loading and saving asset presets.
    GroupBegin(1001, BFH_SCALEFIT | BFV_FIT, 2, 1, String(), 0);
    {
      GroupSpace(5, 5);
 
      AddButton(ID_BTN_LOAD_PRESET, BFH_FIT | BFV_FIT, 0, 0, maxon::String("Load Preset..."));
      AddButton(ID_BTN_SAVE_PRESET, BFH_FIT | BFV_FIT, 0, 0, maxon::String("Save Preset..."));
    }
  }
  GroupEnd();
 
  return SUPER::CreateLayout();
};
 
Bool DotsGui::InitValues()
{
  return SUPER::InitValues();
};
 
maxon::Result<void> DotsGui::LoadAsset(const maxon::AssetDescription& assetDescription)
{
  iferr_scope;
 
  // Sort out any asset descriptions that are not of type DotsPresetAsset.
  if (!assetDescription)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Invalid asset description."_s);
 
  if (assetDescription.GetTypeId() != maxon::AssetTypes::DotsPresetAsset().GetId())
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Received unexpected asset type."_s);
 
  // Load the asset and attempt to cast it to a BasePresetAsset.
  maxon::Asset asset = assetDescription.Load() iferr_return;
  maxon::BasePresetAsset preset = maxon::Cast<maxon::BasePresetAsset>(asset);
  if (!preset)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Failed to cast asset to preset asset."_s);
 
  // Prepare the PresetLoadArgs to send to the DotsPresetAssetImpl to load the data. The arguments 
  // will point to #this GUI, so that the DotsPresetAssetImpl can load the asset into it.
  maxon::PresetLoadArgs dataContainer;
  dataContainer.SetPointer(this) iferr_return;
 
  // Call the dots asset type implementation to load #preset into #this GUI.
  if (!maxon::AssetTypes::DotsPresetAsset().LoadPreset(preset, dataContainer))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not load asset."_s);
 
  return maxon::OK;
}
 
maxon::Result<void> DotsGui::SaveAsset()
{
  iferr_scope;
 
  // Create an instance PresetSaveArgs and point to _data, the instance of DotsData attached to this
  // GUI, in it.
  maxon::PresetSaveArgs data(&_data, 0);
 
  // The strings for the asset type name and asset name. #SaveBrowserPreset will allow the user to
  // modify the asset name.
  const maxon::String typeName = maxon::AssetTypes::DotsPresetAsset().GetName();
  const maxon::String assetName("Dots Preset");
 
  // Call #AssetCreationInterface::SaveBrowserPreset for the type #DotsPresetAsset and the prepared
  // PresetSaveArgs. It will cause the DotsPresetAssetTypeImpl to be called to save the asset with
  // the given PresetSaveArgs #data wrapping the instance of DotsData of this GUI.
  maxon::AssetCreationInterface::SaveBrowserPreset(maxon::AssetTypes::DotsPresetAsset(), 
    data, typeName, assetName, false, false, false) iferr_return;
 
  return maxon::OK;
}
 
Bool DotsGui::Command(Int32 id, const BaseContainer &msg)
{
  iferr_scope_handler
  {
    ApplicationOutput("Error: @", err);
    return false;
  };
 
  switch (id)
  {
    // A message from the user area was received, inform the parent dialog that the data has changed.
    case ID_USERAREA:
    {
      BaseContainer m(msg);
      m.SetInt32(BFM_ACTION_ID, GetId());
      m.SetData(BFM_ACTION_VALUE, this->GetData().GetValue());
      SendParentMessage(m);
 
      // Redraw the user area
      _dotsUserArea.Redraw();
      return true;
    }
    // The "Load Preset ..." button has been pressed.
    case ID_BTN_LOAD_PRESET:
    {
      // The selection filter over the name of an asset type. This will cause the #OpenPopup
      // call below to only show Dots assets.
      maxon::String filterString ("type:dot");
 
      // Open a selection menu for the user to select a preset. The last argument is a delegate
      // which handles the selected content once the user finalizes the selection. #OpenPopup is
      // not blocking which means the selected asset cannot be passed to the outer scope from the
      // lambda, as the outer scope, everything after the call to #OpenPopup, will be reached before
      // the lambda has been executed. Instead of a lambda also a delegate function could be used, 
      // which then would have to handle a maxon::DragAndDropDataAssetArray. In this case this 
      // approach with a lambda was chosen, so that an abstracted DotsGui::LoadAsset could be used. 
      // It handles both "Load Asset ..." button and drag-and-drop asset loading events with an
      // asset description as an input.
      maxon::AssetManagerInterface::OpenPopup(maxon::ASSETPOPUPOPTIONS::POPUPMODE,
        maxon::MASTERFILTER::ALL, filterString, {},
        maxon::GetZeroRef<maxon::GraphModelPresenterRef>(),
        maxon::GetZeroRef<maxon::nodes::NodesGraphModelRef>(), "Select Dots Preset"_s, {},
        [this](const maxon::DragAndDropDataAssetArray& selected) -> void
        {
          iferr_scope_handler
          {
            return;
          };
 
          // Bail when there is no selection.
          if (!selected.GetAssetDescriptions().IsPopulated())
            return;
 
          // Get first selected asset description.
          const maxon::AssetDescription selectedAsset = (
            selected.GetAssetDescriptions()[0].Get<maxon::AssetDescription>());
 
          // Call the asset loading method for this instance.
          this->LoadAsset(selectedAsset) iferr_return;
 
          return;
        }) iferr_return;
 
      return true;
    }
    // The "Save Preset ..." button has been pressed.
    case ID_BTN_SAVE_PRESET:
    {
      // Call the asset saving method for this instance.
      SaveAsset() iferr_return;
      return true;
    }
    default:
      break;
  }
  return SUPER::Command(id, msg);
}
 
maxon::Int32 DotsGui::Message(const BaseContainer& msg, BaseContainer& result)
{
  iferr_scope_handler
  {
    return false;
  };
 
  switch (msg.GetId())
  {
    // A drag and drop event occurred on the custom GUI.
    case BFM_DRAGRECEIVE:
    {
      // Will point to the dragged data.
      void* dragObject = nullptr;
 
      // Bail on incomplete or invalid drag operations.
      MAXON_SCOPE
      {
        // Bail on incomplete drag operations.
        if (msg.GetInt32(BFM_DRAG_ESC) || msg.GetInt32(BFM_DRAG_LOST))
          return true;
 
        // The drag occurred not on the drag and drop area or the drag data is inaccessible.
        if (!CheckDropArea(ID_USERAREA, msg, true, true) || !GetDragObject(msg, 0, &dragObject))
          return true;
 
        // The drag data is invalid.
        if (!dragObject)
          return false;
      }
 
      // Variable for the asset which might be contained in the drag and drop data.
      maxon::AssetDescription asset; 
 
      // Extract the asset from the dragged data
      MAXON_SCOPE
      {
        // Unpack the drag and drop data.
        const maxon::DragAndDropDataAssetArray* dragArray = (
          static_cast<const maxon::DragAndDropDataAssetArray*>(dragObject));
 
        // Attempt to get the first dots asset description in the dragged data.
        for (maxon::DndAsset dragTuple : dragArray->GetAssetDescriptions())
        {
          // A DndAsset is a tuple of an AssetDescription, Url, and String: Test if the
          // AssetDescription of this drag and drop tuple is of type DotsPresetAsset.
          if (dragTuple.first.GetTypeId() == maxon::AssetTypes::DotsPresetAsset().GetId())
          {
            asset = dragTuple.first;
            break;
          }
        }
 
        // The dragged data did not contain any dots preset assets.
        if (!asset)
          return true;
 
        // Set a cursor indicating an unfinished drag operation on a dragable area.
        if (!msg.GetInt32(BFM_DRAG_FINISHED))
        {
          SetDragDestination(MOUSE_COPY);
          return true;
        }
      }
 
      // The drag operation has finished, the asset should be loaded.
      LoadAsset(asset) iferr_return;
      return true;
    }
    default:
      break;
  }
  return iCustomGui::Message(msg, result);
}
 
Bool DotsGui::SetData(const TriState<GeData> &tristate)
{
  // data is set from the outside
  const DotsData* const data = static_cast<const DotsData*>(
    tristate.GetValue().GetCustomDataType(PID_CUSTOMDATATYPE_DOTS));
 
  if (data)
  {
    _data.points.Flush();
    iferr (_data.points.CopyFrom(data->points))
      return false;
 
    _dotsUserArea.Redraw(); 
  }
 
  return true;
};
 
TriState<GeData> DotsGui::GetData()
{
  TriState<GeData> tri;
  tri.Add(GeData(PID_CUSTOMDATATYPE_DOTS, _data));
 
  return tri;
};
 
// --- The implementation of the plugin interface for the DotsGui ----------------------------------
 
Int32 DotsGuiData::GetId()
{
  return PID_CUSTOMGUI_DOTS;
};
 
CDialog* DotsGuiData::Alloc(const BaseContainer& settings)
{
  // creating the dialog that "is" the actual GUI
 
  iferr (DotsGui* const dlg = NewObj(DotsGui, settings, GetPlugin()))
    return nullptr;
  
  CDialog *cdlg = dlg->Get();
 
  if (!cdlg) 
    return nullptr;
    
  return cdlg;
};
 
void DotsGuiData::Free(CDialog* dlg, void* userdata)
{
  if (!dlg || !userdata) 
    return;
 
  DotsGui* sub = static_cast<DotsGui*>(userdata);
  DeleteObj(sub);
};
 
const Char* DotsGuiData::GetResourceSym()
{
  // the symbol used in resource files
  return "CUSTOMGUIDOTS";
};
 
CustomProperty* DotsGuiData::GetProperties()
{
  return nullptr;
};
 
Int32 DotsGuiData::GetResourceDataType(Int32*& table)
{
  // returns the list of data types this GUI can work with
  table = g_stringtable; 
  return sizeof(g_stringtable)/sizeof(Int32);
};
 
// --- The implementation of the plugin interface for the DotsData ---------------------------------
 
Int32 DotsDataClass::GetId()
{
  return PID_CUSTOMDATATYPE_DOTS;
}
 
CustomDataType* DotsDataClass::AllocData()
{
  DotsData* data = NewObjClear(DotsData);
  return data;
};
 
void DotsDataClass::FreeData(CustomDataType* data)
{
  DotsData* d =  static_cast<DotsData*>(data);
  DeleteObj(d);
}
 
Bool DotsDataClass::CopyData(
  const CustomDataType* src, CustomDataType* dst, AliasTrans* aliastrans)
{
  // copy the data to the given target data
 
  const DotsData* s =  static_cast<const DotsData*>(src);
  DotsData* d =  static_cast<DotsData*>(dst);
 
  if (!s || !d)
    return false;
 
  d->points.Flush();
  iferr (d->points.CopyFrom(s->points))
    return false;
 
  return true;
}
 
Int32 DotsDataClass::Compare(const CustomDataType* d1, const CustomDataType* d2)
{
  // compare the values of the given elements
  // this is also used to determine if a parameter has changed
 
  const DotsData* const s = static_cast<const DotsData*>(d1);
  const DotsData* const d = static_cast<const DotsData*>(d2);
 
  if (!s || !d)
    return 0;
 
  // This just compares the number of points. A better implementation would be to also compare 
  // the values of the points
 
  const maxon::Int countd1 = s->points.GetCount();
  const maxon::Int countd2 = d->points.GetCount();
 
  if (countd1 == countd2) 
    return 0;
  if (countd1 < countd2) 
    return -1;
  if (countd1 > countd2) 
    return 1;
 
  return 0;
}
 
Bool DotsDataClass::WriteData(const CustomDataType* t_d, HyperFile* hf)
{
  // write the data of this datatype to the given hyper file
 
  const DotsData* const d = static_cast<const DotsData*>(t_d);
 
  // save number of points
  const maxon::Int length = d->points.GetCount();
  hf->WriteInt64((Int64)length);
 
  // save points
  for (Int64 i = 0; i < length; ++i)
  {
    hf->WriteVector(d->points[i]);
  }
 
  return true;
}
 
Bool DotsDataClass::ReadData(CustomDataType* t_d, HyperFile* hf, Int32 level)
{
  // reads the data of this datatype from the given HyperFile
  DotsData* const d = static_cast<DotsData*>(t_d);
 
  if (level > 0)
  {
    // get number of points
    Int64 length = 0;
    if (hf->ReadInt64(&length))
    {
      // read points
      for (Int64 i = 0; i < length; ++i)
      {
        Vector vec;
        if (hf->ReadVector(&vec))
        {
          iferr (d->points.Append(vec))
            return false;
        }
      }
    }   
  }
  return true;
}
 
const Char* DotsDataClass::GetResourceSym()
{
  // this symbol can be used in resource files
  return "ASSETDOTS";
}
 
void DotsDataClass::GetDefaultProperties(BaseContainer &data)
{
  // the default values of this datatype
 
  // use the custom GUI as default
  data.SetInt32(DESC_CUSTOMGUI, PID_CUSTOMGUI_DOTS);
  data.SetInt32(DESC_ANIMATE, DESC_ANIMATE_ON);
}
 
// --- Registration of the plugin interfaces -------------------------------------------------------
 
Bool RegisterDotsDataAndGui()
{
  // register custom datatype
  if (!RegisterCustomDataTypePlugin(
    GeLoadString(IDS_DOTS_DATATYPE),
    CUSTOMDATATYPE_INFO_LOADSAVE |
    CUSTOMDATATYPE_INFO_TOGGLEDISPLAY |
    CUSTOMDATATYPE_INFO_HASSUBDESCRIPTION,
    NewObjClear(DotsDataClass),
    1))
    return false;
  
  // dummy library for custom GUI
  static BaseCustomGuiLib myDotCustomGUI;
 
  ClearMem(&myDotCustomGUI, sizeof(myDotCustomGUI));
  FillBaseCustomGui(myDotCustomGUI);
 
  if (!InstallLibrary(PID_CUSTOMGUI_DOTS, &myDotCustomGUI, 1000, sizeof(myDotCustomGUI))) 
    return false;
 
  // register custom GUI
  if (!RegisterCustomGuiPlugin(GeLoadString(IDS_DOTS_GUI), 0, NewObjClear(DotsGuiData)))
    return false;
 
  return true;
}

Example on GitHub

Load Assets into a GUI

Provides an example pattern for loading preset assets into a iCustomGui.

maxon::Result<void> DotsGui::LoadAsset(const maxon::AssetDescription& assetDescription)
{
  iferr_scope;
 
  // Sort out any asset descriptions that are not of type DotsPresetAsset.
  if (!assetDescription)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Invalid asset description."_s);
 
  if (assetDescription.GetTypeId() != maxon::AssetTypes::DotsPresetAsset().GetId())
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Received unexpected asset type."_s);
 
  // Load the asset and attempt to cast it to a BasePresetAsset.
  maxon::Asset asset = assetDescription.Load() iferr_return;
  maxon::BasePresetAsset preset = maxon::Cast<maxon::BasePresetAsset>(asset);
  if (!preset)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Failed to cast asset to preset asset."_s);
 
  // Prepare the PresetLoadArgs to send to the DotsPresetAssetImpl to load the data. The arguments 
  // will point to #this GUI, so that the DotsPresetAssetImpl can load the asset into it.
  maxon::PresetLoadArgs dataContainer;
  dataContainer.SetPointer(this) iferr_return;
 
  // Call the dots asset type implementation to load #preset into #this GUI.
  if (!maxon::AssetTypes::DotsPresetAsset().LoadPreset(preset, dataContainer))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Could not load asset."_s);
 
  return maxon::OK;
}

Example on GitHub

Save Assets from a GUI

Provides an example pattern for creating preset assets from the data attached to a iCustomGui.

maxon::Result<void> DotsGui::SaveAsset()
{
  iferr_scope;
 
  // Create an instance PresetSaveArgs and point to _data, the instance of DotsData attached to this
  // GUI, in it.
  maxon::PresetSaveArgs data(&_data, 0);
 
  // The strings for the asset type name and asset name. #SaveBrowserPreset will allow the user to
  // modify the asset name.
  const maxon::String typeName = maxon::AssetTypes::DotsPresetAsset().GetName();
  const maxon::String assetName("Dots Preset");
 
  // Call #AssetCreationInterface::SaveBrowserPreset for the type #DotsPresetAsset and the prepared
  // PresetSaveArgs. It will cause the DotsPresetAssetTypeImpl to be called to save the asset with
  // the given PresetSaveArgs #data wrapping the instance of DotsData of this GUI.
  maxon::AssetCreationInterface::SaveBrowserPreset(maxon::AssetTypes::DotsPresetAsset(), 
    data, typeName, assetName, false, false, false) iferr_return;
 
  return maxon::OK;
}

Example on GitHub

Instantiate a Preset

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.

maxon::Result<maxon::AssetDescription> InstantiateDotsPresetAsset()
{
  iferr_scope;
 
  // Allocate the data.
  DotsData dotsData = DotsData();
 
  // Init a pseudo random generator and add ten random points to the DotsData.
  maxon::LinearCongruentialRandom<maxon::Float32> random;
  random.Init(static_cast<maxon::Int32>(maxon::UniversalDateTime::GetNow().GetUnixTimestamp()));
 
  for (maxon::Int32 i = 0; i < 10; i++)
  {
    const maxon::Float32 x = random.Get01() * maxon::Float32(dotsData.canvasSize);
    const maxon::Float32 y = random.Get01() * maxon::Float32(dotsData.canvasSize);
    dotsData.points.Append(maxon::Vector(x, y, 0)) iferr_return;
  }
 
  // Pack the DotsData into a PresetSaveArgs. The type of data that must be packed depends on the
  // Preset Asset type implementation.
  maxon::PresetSaveArgs data(&dotsData, 0);
  const maxon::String typeName = maxon::AssetTypes::DotsPresetAsset().GetName();
  const maxon::String name ("Manually Instantiated Dots Preset");
 
  // Save the data as a preset asset.
  maxon::AssetDescription asset = maxon::AssetCreationInterface::SaveBrowserPreset(
    maxon::AssetTypes::DotsPresetAsset(), data, typeName, name, false, false, false) iferr_return;
 
  return std::move(asset);
}

Example on GitHub

Invoke Asset Implementation

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.

maxon::Result<void> UpdatePreviewThumbnail(
  maxon::AssetDescription& assetDescription, maxon::Float32 difference)
{
  iferr_scope;
 
  // Bail when an asset description has been passed that is not for a dots preset asset.
  if (assetDescription.GetTypeId() != maxon::AssetTypes::DotsPresetAsset().GetId())
    return maxon::IllegalArgumentError(
      MAXON_SOURCE_LOCATION, "Passed asset is not of type 'DotsPresetAsset'"_s);
 
  // 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;
 
  // The new value clamped to the interval [0.025, 0.1].
  maxon::Float32 newValue = maxon::ClampValue(oldValue + difference, 0.025F, 0.1F);
 
  // Write the new value as a persistent value, i.e., a value that will be serialized.
  assetDescription.StoreMetaData(maxon::ASSETMETADATA::DOTSPRESET::DOT_SCALE, newValue,
    maxon::AssetMetaDataInterface::KIND::PERSISTENT) iferr_return;
 
  // Get the asset interface for the asset description and cast it to a BasePresetAsset.
  maxon::Asset asset = assetDescription.Load() iferr_return;
  maxon::BasePresetAsset presetAsset = maxon::Cast<maxon::BasePresetAsset>(asset);
  if (!presetAsset)
    return maxon::UnexpectedError(
      MAXON_SOURCE_LOCATION, "Could not access asset implementation."_s);
 
  // Get Asset Browser preferences and the thumbnail width within them.
  BaseContainer* bc = GetWorldContainerInstance()->GetContainerInstance(
    CID_ASSET_BROWSER_PREFERENCES);
  const maxon::Int32 BROWSER_PREVIEW_WIDTH = 6;
  maxon::Int32 previewWidth = maxon::ClampValue(
    bc->GetInt32(BROWSER_PREVIEW_WIDTH, 512), 128, 1024);
 
  // The DotsPresetAssetImpl does not make use of the passed ProgressInterface as most preset 
  // assets do, due to to the negligible rendering times. If it would, a fully initialized 
  // ProgressInterface reference must be defined here instead of a dummy reference.
  maxon::ProgressRef dummy;
 
  // Call the DotsPresetAssetImpl to generate the preview and store new preview url. The fact
  // that we can do this with the BasePresetAssetInterface reference #presetAsset is due to the 
  // component system of the maxon API. The BasePresetAssetInterface referenced by #presetAsset 
  // will carry the DotsPresetAssetImpl component which has been defined in the dots preset asset
  // implementation. It will take over with its method of the same name when GeneratePreview() is 
  // being called. So, we are in fact calling here DotsPresetAssetImpl::GeneratePreview().
  maxon::Url newPreviewUrl = presetAsset.GeneratePreview(previewWidth, dummy, 0) iferr_return;
  if (newPreviewUrl.IsEmpty())
    return maxon::UnexpectedError(
      MAXON_SOURCE_LOCATION, "Dots preset asset thumbnail rendering failed."_s);
 
  // Clear out the old preview cache for static previews, as the dots preset type only does
  // provide such preview thumbnails.
  maxon::Url oldPreviewUrl = metadata.Get(
    maxon::ASSETMETADATA::ASSET_PREVIEWIMAGEURL, maxon::Url()) iferr_return;
 
  if (oldPreviewUrl.IsPopulated())
  {
    assetDescription.StoreUrlMetaData(maxon::ASSETMETADATA::ASSET_PREVIEWIMAGEURL,
      maxon::Url(), maxon::AssetMetaData::KIND::PERSISTENT) iferr_return;
    maxon::ImageUrlCacheInterface::InvalidateCache(oldPreviewUrl) iferr_return;
  }
 
  // Update the asset metadata for the new preview url.
  assetDescription.StoreUrlMetaData(
    maxon::ASSETMETADATA::ASSET_PREVIEWIMAGEURL, newPreviewUrl,
    maxon::AssetMetaData::KIND::PERSISTENT) iferr_return;
 
  maxon::DataDictionary metaProperties = metadata.Get(
    maxon::ASSETMETADATA::MetaProperties, maxon::DataDictionary()) iferr_return;
  metaProperties.Set(maxon::ASSET::METAPROPERTIES::BASE::AUTOMATICPREVIEW, true) iferr_return;
  assetDescription.StoreMetaData(maxon::ASSETMETADATA::MetaProperties,
    std::move(metaProperties), maxon::AssetMetaData::KIND::PERSISTENT) iferr_return;
 
  return maxon::OK;
}

Example on GitHub