Table of Contents
Create and load assets for a wide range of content types exposed by the Asset Browser.
Overview
The Asset API can handle assets wrapping multiple types of content. Assets for known content types have specialized handling behaviours for their asset content, as for example generating preview images and loading the asset content into Cinema 4D when the asset is dragged or double-clicked. The data stored with an asset consists of two parts: The primary data, the actual content as for example an image file, and the secondary data, the metadata which describe that content. An asset description is the container which holds the metadata describing an asset, while the various forms of asset type implementations provide an interface for the primary data of the asset.
The most tangible forms of assets wrap fundamental content as scenes, objects, materials, files, node templates, and presets. But also other forms of data are represented by assets as for example categories, keywords. From an Asset API perspective there are three asset types which cover the vast majority of asset content: File, node template, and preset assets. File assets wrap most of the content delivered with the Asset Browser, ranging from scenes over objects, materials, and textures to arbitrary files. Node templates are a part of the Nodes API and represent nodes or node groups that can be part of a node graph, as for example Scene and Material Nodes. Preset assets are a specialized form of asset type that wrap a specific data type and are often also associated with a special GUI which handles loading and saving assets. Examples for such preset assets are spline and gradient presets, which both wrap the corresponding spline and gradient data types and GUIs.
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.
Technical Overview
The implementation of all asset types is split into two parts: The implementation of an asset interface which inherits from AssetInterface and implements the functionalities that apply to singular asset of that type, as for example accessing the metadata of the specific asset. And the implementation of an asset type interface which inherits from AssetTypeInterface and implements the functionalities that apply to all assets of that type. All asset type implementations are exposed by the namespace AssetTypes which is often used to specify an asset type in operations which require an asset type to be passed.
From an asset description the corresponding asset interface can be accessed with AssetDescriptionInterface::Load, returning a reference to the base AssetInterface for that asset description and the asset description of an asset interface can be accessed with the method AssetInterface::GetDescription. On the rare occasions where a type specific asset interface for an asset description is required, the base interface must be cast with maxon::Cast into the type specific asset interface.
AssetInterface is derived from the base interface ObjectInterface, allowing assets to be instantiated as any maxon API object with its Create method, returning a reference to a newly created asset interface. But this from of asset instantiation is usually only applied to the less complex asset types, as for example keyword and category assets, where manually setting up the data and metadata of that asset is trivial. More complex asset types are instantiated with convenience functions which hide the asset interfaces away and expose directly the asset descriptions for the newly created assets. These convenience functions are primarily being provided by the interface AssetCreationInterface; offering static functions to create assets for objects, materials, scenes, textures, videos, files, and presets, as well as for loading them back. Node template assets, i.e., assets that wrap a graph node, do not have their own asset interface in the Asset API and are instead represented by NodeTemplateInterface, a member of the Nodes API, and their node template identifier is also used as their asset identifier. Node template assets must be created with NodesGraphModelInterface::MoveToAsset and loaded back by inserting the template with NodesGraphModelInterface::AddChild into a graph.
Assets of type AssetTypes::File are special in that they can have a subtype. The subtype is expressed in the metadata of the asset and can also be set with the function SubTypeAssetInterface::SetSubType. A file asset which wraps a subset of an object-hierarchy of a scene is for example of subtype maxon::ASSETMETADATA::SubType_ENUM_Object and an image file asset of subtype maxon::ASSETMETADATA::SubType_ENUM_MediaImage.
Related Topics
| Articles | Asset API | Provide content as reusable assets served with the Cinema 4D Asset Browser. |
| Implementing Preset Assets | Implement a custom preset asset type wrapping a custom data type to be exposed by the Asset Browser. | |
| Entity Creation | Explains the managed memory environment of the maxon API with interfaces and references. | |
| Important API Entities | AssetTypes | Contains the declarations of asset types. |
| AssetCreationInterface | Provides static convenience functions to create and load assets for materials, objects, scenes, files, and presets. | |
| AssetDescriptionInterface | Represents an asset over its metadata in an asset repository. | |
| AssetInterface | Provides the base implementation for the functionalities of a singular asset. | |
| AssetTypeInterface | Provides the base implementation for the functionalities applicable to all assets of a specific type. | |
| 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. | |
| FileAssetInterface | Represents a file asset, the most common from of asset type, wrapping a wide range of content. | |
| NodeTemplateInterface | Represents both a node and asset type which can be loaded into a nodes graph and inserted into an asset database. | |
| CategoryAssetInterface | Represents an Asset Browser category as an asset. | |
| KeywordAssetInterface | Represents an Asset Browser keyword as an asset. | |
| SmartSearchAssetInterface | Represents an Asset Browser smart search preset as an asset. | |
| StoreAssetStruct | Provides a helper structure that is used to store assets in asset repositories. | |
| DndAsset | Provides a helper structure that is used in asset drag and drop operations. | |
| SDK Plugins | Asset API Examples | Showcases basic interactions with the Asset API to modify asset databases and their content. |
| Examples | Create Object Assets | Store a BaseObject as an asset. |
| Create Material Assets | Store a BaseMaterial as an asset. | |
| Create Scene Assets | Store a BaseDocument as an asset. | |
| Create Media Assets | Store an image or movie as a media asset. | |
| Create File Assets | Store an arbitrary file as an asset. | |
| Create Node Template Assets | Store scene or material nodes of a node graph as assets. | |
| Create Category Assets | Create a category in which other assets can be placed. | |
| Create Keyword Assets | Create a keyword with which other assets can be described. | |
| Link Media Assets | Reference a media asset in a material. | |
| Load Assets | Load assets of any type back into the active document. | |
| Load File Assets Manually | Load file assets wrapping objects, materials, scenes or other file types manually back into Cinema 4D. | |
| Load Node Template Assets Manually | Load a node template manually back into a node graph. |
Examples
The examples shown here are all related to the "Asset Types" category in the Asset API Examples plugin. With the plugin you can run these examples to see their output. Each example shown here has a link bar at its bottom, linking to the code on GitHub, as well as to a calling context on GitHub. A calling context is a function which showcases how to gather the required inputs for that specific example and is targeted at users who want to know how to carry out a specific task in more detail. The context link is named "How to call this example ...".
Create Object Assets
Stores a BaseObject as an asset.
The object is being stored with all 'connected' elements like child objects, tags, materials and shaders. Uses the convenience function AssetCreationInterface::CreateObjectAsset to simplify the process.
Create Material Assets
Stores a BaseMaterial as an asset.
The material is being stored with all 'connected' shaders. Uses the convenience function AssetCreationInterface::CreateMaterialAsset to simplify the process.
Create Scene Assets
Stores a BaseDocument as an asset.
The scene is being stored with all its dependencies as objects, materials, shaders, or textures. Uses the convenience function AssetCreationInterface::CreateSceneAsset to simplify the process.
Create Media Assets
Stores an image or video file as a media asset.
Other than arbitrary file assets, media assets will have a preview thumbnail reflecting the specific content of the asset and open in the picture viewer when invoked in the Asset Browser. Uses the convenience function AssetCreationInterface::SaveTextureAsset to simplify the process.
Create File Assets
Stores an arbitrary file as an asset.
Many forms of assets as scenes, objects, materials and textures are file type assets which are distinguished only by their asset subtype. File type assets can also have the empty id as their subtype, allowing them to wrap around arbitrary file types as for example a PDF or Word file. File assets of unsupported subtype lack the special handling of a supported subtype asset as for example preview images or loading them when double clicked. File assets should always be stored under the correct subtype, and only assets for unsupported file types should be stored as plain file assets. Uses the convenience function SaveMemFileAsAssetWithCopyAsset which will make a copy of the file to be stored as an asset in the asset database.
Create Node Template Assets
Transforms the active selection of nodes in a node graph into an asset.
The selected nodes will be moved into a group node, then an asset for that group node will be created, and finally that group node in the graph will be replaced with the asset node. The operation will maintain wires established to nodes outside of the selection.
Create Category Assets
Creates a category asset.
Asset categories are the folder structure visible in the Asset Browser that group other assets. Each of these categories is an asset itself and each asset, including category assets themselves, can reference exactly one category asset as its parent category.
Create Keyword Assets
Creates a keyword asset.
Asset keywords are used by the Asset Browser to group assets in addition to categories. Each keyword is an asset itself which can be referenced with its asset id by other assets as one of their multiple keywords.
Link Media Assets
Loads the passed media assets as materials into the passed document.
Loads image and movie assets into a document as textures in the color channel of a material and ensures that the passed assets are indeed of asset type File and matching subtype. The major insight of this example is that the Url of a media asset can be used directly to access its content.
Load Assets
Loads any asset type back into the active document.
Uses the convenience function LoadAssets() which can load all asset types but is bound to the active document. The approach shown here will open progress popup dialogs when an asset must be downloaded.
Load File Assets Manually
Loads a file asset wrapping objects, materials, scenes or other file types manually back into Cinema 4D.
Other than with the convenience function LoadAssets() this approach can also load into a document which is not the active document.
Load Node Template Assets Manually
Loads the passed node template identifiers manually as nodes into the passed graph.
Node template assets are special because they do not have an interface in the Asset API wrapping them. Instead, a NodeTemplate can be treated directly as asset, where the identifier of the the node template is identical to the identifier which identifies the node template within the Asset API.