Asset API Assets

Table of Contents

• Overview
  • Restrictions
• Technical Overview
  • Implementing Custom Preset Types
• Related Topics
• Common Tasks
  • Create Object Assets
  • Create Material Assets
  • Create Scenes Assets
  • Create File Assets
  • Create Node Setup Assets
  • Create Category Assets
  • Create Keyword Assets
  • Create Parameter Preset Assets
  • Create Scene Element Preset Assets

Create assets and presets for scene elements to be stored in an asset database.

Overview

Assets come as the asset types of scenes, objects, materials, media files, nodes and presets for the user in the Asset Browser. But there are also more assets types like categories, keywords, files, plugins and other types which are less obviously assets from the user view. An asset can conceptually be split into its primary data, for example the polygonal geometry for a polygon object asset, and its metadata which describe that asset. The primary data for classic API objects, tags and scenes is internally being wrapped as a document containing all asset dependencies when an asset is being stored and other asset types are being stored as resources.

Assets can also define presets of parameter values or sets of parameter values; e.g., the value of a gradient parameter or all the parameters that make up an instance of a Cube object. Such preset asset can then be loaded from the Asset Browser into any scene element that also contains that type of parameter or set of parameters. Assets can also be versioned, capturing multiple expressions of one piece of content, e.g., different development stages of a texture, mesh or material.

Restrictions

With the built-in asset types it is currently not possible to create an asset that wraps only a BaseTag or BaseShader. Because the former requires a BaseObject instance and the latter a BaseMaterial instance to be stored in a document. But due to the collection of asset dependencies, it is possible to store a BaseObject with its tags or a BaseMaterial with its shaders as a single asset. Assets for the maxon Nodes API are not limited by such restrictions.

Technical Overview

Assets are represented as asset descriptions by AssetDescriptionInterface references when interacting with asset databases in the Asset API. The interface can access the AssetInterface reference for an asset, holds the Url of an asset and can read and write descriptive metadata into for its asset. See Asset API Metadata for details on the asset model of the Asset API. The logical interface to an asset is represented by the interfaces AssetInterface and AssetTypeInterface. The former provides a view on a single asset in an asset database, primarily in form of its identifier, asset type and metadata. The latter generalizes a certain type of asset and provides among other functionalities the ability to load a reference to an AsstInterface and store assets with an AssetDescription reference.

The namespace AssetTypes contains the asset type declarations provided by Cinema 4D like for example the asset types AssetTypes::File or AssetTypes::Keyword. Object, Material, Scene assets are saved as a FileAsset and do not have their own assets type. The subtype of this FileAsset is specified by attributes in the ASSETMETADATA namespace. The metadata of such a FileAsset declare via its sub-type property if the asset is an image, movie, object, material or scene asset. In many use cases all this complexity can be hidden away by using the AssetCreationInterface which provides convenience methods for creating assets. Specific asset types also have their own AssetTypeInterface, providing asset type related functionalities as static functions. The SubTypeAssetInterface allows for example to set the subtype of a SubType asset and the CategoryAssetInterface to get and set the category of a CategoryAsset.

Fig I: A broad overview of the asset interfaces. The interfaces can be divided into four groups: The data interfaces which handle the data of an asset which are required when interacting with asset databases and repositories and when accessing asset metadata. The general logic interfaces which are the main interfaces to interact with and retrieve and write data for an asset. The specialized type interfaces which implement and provide functionalities for specific asset types. And the Preset Logic interfaces which are required to implement specialized preset assets. They also have their builtin specialized preset type logic interfaces, just as the the asset types, but these interfaces are hidden from the public view.

Implementing Custom Preset Types

Not yet documented

Related Topics

Articles	Asset API	Provide content as reusable assets served with the Cinema 4D Asset Browser.
	Interface Basics	The interface system of the MAXON API is a toolset to define public APIs and to hide implementation details. It is the base for most components of the MAXON API.
API Entities	AssetTypes	Contains the declarations of asset types.
	ASSETMETADATA	Contains the declarations of asset metadata attributes.
	AssetDependencyStruct	Not yet documented
	AssetDescriptionInterface	Represents an asset as its administrative metadata and provides access to its descriptive metadata.
	AssetInterface	Represents digital content which can be managed by an asset repository.
	AssetTypeInterface	Provides the methods needed by an asset repository to handle a specific type of assets.
	BasePresetAssetInterface	Allows to implement details for preset assets.
	BasePresetAssetTypeInterface	Defines a new preset type and is the connector to BasePresetAssetInterface.
	CategoryAssetInterface	Not yet documented
	ColorCategoryAssetInterface	Not yet documented
	DatabaseAssetInterface	Not yet documented
	DataDescriptionPresetStorageInterface	Not yet documented
	FileAssetInterface	Represents a file asset, so a plain file (or directory) stored in an asset repository.
	KeywordAssetInterface	Not yet documented
	NodeSpaceAssetInterface	Not yet documented
	PluginAssetInterface	Not yet documented
	SmartSearchAssetInterface	Not yet documented
	StoreAssetStruct	Not yet documented
	SubTypeAssetInterface	Not yet documented
	UpdatableAssetInterface	Represents an asset which supports the update of its updateable references to other assets to newer versions.
	UrlAssetRepositoryInterface	Not yet documented
SDK Plugins	Asset API Basics	Showcases basic interactions with the Asset API to modify asset databases and their content.
	Asset Type Implementation	Not yet documented
	Preset Asset Type Implementation	Not yet documented
Common Tasks	Create Object Assets	Create assets for classic API objects that can be stored in asset databases.
	Create Material Assets	Create assets for classic API materials that can be stored in asset databases.
	Create Scenes Assets	Create assets for classic API scenes that can be stored in asset databases.
	Create File Assets	Not yet documented
	Create Node Setup Assets	Not yet documented
	Create Category Assets	Not yet documented
	Create Keyword Assets	Not yet documented
	Create Parameter Preset Assets	Not yet documented
	Create Scene Element Preset Assets	Not yet documented

Common Tasks

Create Object Assets

Create assets for classic API objects that can be stored in asset databases.

This snippet can be found in a compileable context in the SDK plugin Asset API Basics.

maxon::Result<void> CreateObjectAsset()
{
  // An error scope handling which is more verbose than a simple "iferr_scope;". If one of the
  // calls below returns an error, the function will be exited through this block.
  iferr_scope_handler
  {
    ApplicationOutput("Stopped CreateObjectAsset() execution with the error: @", err);
    return err;
  };
 
  // Get the active document and the active object in it.
  BaseDocument* doc = GetActiveDocument();
  if (doc == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  BaseObject* op = doc->GetActiveObject();
  if (op == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  // Get the user preferences repository to store our asset in, we could also use our own database
  // and repository here. For details see Asset API - Databases.
  const maxon::AssetRepositoryRef& repository = maxon::AssetInterface::GetUserPrefsRepository();
 
  // Create an id for the new asset.
  maxon::Id assetId = maxon::AssetInterface::MakeUuid("object", false) iferr_return;
  // The name of the asset, we can pick here anything we would like, the name does not have to be
  // unique.
  maxon::String assetName = FormatString("C++ SDK - Object Asset (@)", op->GetName());
  // Create the metadata for the asset, we will leave it empty here. See Asset API - Metadata for
  // details on handling asset metadata.
  maxon::AssetMetaData metadata;
  // The version of the asset.
  maxon::String assetVersion = "1.0"_s;
  // And finally the StoreAssetStruct which bundles up a category id, the lookup and the storage
  // repository.
  maxon::StoreAssetStruct storeAsset{ maxon::Id(), repository, repository };
 
  // There are more atomic methods attached to AssetRepositoryInterface we could use to store 
  // assets, but here we are going to use one of the convenience functions attached to 
  // AssetCreationInterface to store the material as an asset.
  maxon::AssetDescription description = maxon::AssetCreationInterface::CreateObjectAsset(
    op, doc, storeAsset, assetId, assetName, assetVersion, metadata, true) iferr_return;
 
  // Push an update event to Cinema 4D, so that the Asset Browser can catch up.
  EventAdd();
  ApplicationOutput("Created object asset with the id '@'.", description);
 
  return maxon::OK;
}

Example Output

Create Material Assets

Create assets for classic API materials that can be stored in asset databases.

This snippet can be found in a compileable context in the SDK plugin Asset API Basics.

maxon::Result<void> CreateMaterialAsset()
{
  // An error scope handling which is more verbose than a simple "iferr_scope;". If one of the
  // calls below returns an error, the function will be exited through this block.
  iferr_scope_handler
  {
    ApplicationOutput("Stopped CreateMaterialAsset() execution with the error: @", err);
    return err;
  };
 
  // Get the active document and the active material in it.
  BaseDocument* doc = GetActiveDocument();
  if (doc == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  BaseMaterial* material = doc->GetActiveMaterial();
  if (material == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  // Get the user preferences repository to store our asset in, we could also use our own database
  // and repository here. For details see Asset API - Databases.
  const maxon::AssetRepositoryRef& repository = maxon::AssetInterface::GetUserPrefsRepository();
 
  // Create an id for the new asset.
  maxon::Id assetId = maxon::AssetInterface::MakeUuid("material", false) iferr_return;
  // The name of the asset, we can pick here anything we would like, the name does not have to be
  // unique.
  maxon::String assetName = FormatString("C++ SDK - Material Asset (@)", material->GetName());
  // Create the metadata for the asset, we will leave it empty here. See Asset API - Metadata for
  // details on handling asset metadata.
  maxon::AssetMetaData metadata;
  // The version of the asset.
  maxon::String assetVersion = "1.0"_s;
  // And finally the StoreAssetStruct which bundles up a category id, the lookup and the storage
  // repository.
  maxon::StoreAssetStruct storeAsset{ maxon::Id(), repository, repository };
 
  // There are more atomic methods attached to AssetRepositoryInterface we could use to store 
  // assets, but here we are going to use one of the convenience functions attached to 
  // AssetCreationInterface to store the material as an asset.
  maxon::AssetDescription description = maxon::AssetCreationInterface::CreateMaterialAsset(
    doc, material, storeAsset, assetId, assetName, assetVersion, metadata, true) iferr_return;
 
  // Push an update event to Cinema 4D, so that the Asset Browser can catch up.
  EventAdd();
  ApplicationOutput("Created material asset with the id '@'.", description);
 
  return maxon::OK;
}

Example Output

Create Scenes Assets

Create assets for classic API scenes that can be stored in asset databases.

This snippet can be found in a compileable context in the SDK plugin Asset API Basics.

maxon::Result<void> CreateSceneAsset()
{
  // An error scope handling which is more verbose than a simple "iferr_scope;". If one of the
  // calls below returns an error, the function will be exited through this block.
  iferr_scope_handler
  {
    ApplicationOutput("Stopped CreateSceneAsset() execution with the error: @", err);
    return err;
  };
 
  // Get the active document.
  BaseDocument* doc = GetActiveDocument();
  if (doc == nullptr)
    return maxon::NullptrError(MAXON_SOURCE_LOCATION);
 
  // Get the user preferences repository to store our asset in, we could also use our own database
  // and repository here. For details see Asset API - Databases.
  const maxon::AssetRepositoryRef& repository = maxon::AssetInterface::GetUserPrefsRepository();
 
  // Create an id for the new asset.
  maxon::Id assetId = maxon::AssetInterface::MakeUuid("scene", false) iferr_return;
  // The name of the asset, we can pick here anything we would like, the name does not have to be
  // unique.
  maxon::String assetName = FormatString("C++ SDK - Scene Asset (@)", doc->GetDocumentName());
  // Create the metadata for the asset, we will leave it empty here. See Asset API - Metadata for
  // details on handling asset metadata.
  maxon::AssetMetaData metadata;
  // The version of the asset.
  maxon::String assetVersion = "1.0"_s;
  // And finally the StoreAssetStruct which bundles up a category id, the lookup and the storage
  // repository.
  maxon::StoreAssetStruct storeAsset{ maxon::Id(), repository, repository };
 
  // There are more atomic methods attached to AssetRepositoryInterface we could use to store 
  // assets, but here we are going to use one of the convenience functions attached to 
  // AssetCreationInterface to store the material as an asset.
  maxon::AssetDescription description = maxon::AssetCreationInterface::CreateSceneAsset(
    doc, storeAsset, assetId, assetName, assetVersion, metadata, true) iferr_return;
 
  // Push an update event to Cinema 4D, so that the Asset Browser can catch up.
  EventAdd();
  ApplicationOutput("Created scene asset with the id '@'.", description);
 
  return maxon::OK;
}

Example Output

Create File Assets

Not yet documented

Create Node Setup Assets

Not yet documented

Create Category Assets

Not yet documented

Create Keyword Assets

Not yet documented

Create Parameter Preset Assets

Not yet documented

Create Scene Element Preset Assets

Not yet documented