ParameterStorageInterface Class Reference

#include <materialparameter.h>

Static Public Member Functions

template<typename TYPE , typename KEY >
static Result< TypedConstantParameter< TYPE > > Extract (const DataDictionaryInterface &parameters, KEY &&id)
 
template<typename TYPE , typename KEY >
static Result< TypedConstantParameter< TYPE > > Extract (const DataDictionary &parameters, KEY &&id)
 
template<typename T , typename KEY >
static Result< void > Insert (DataDictionary &parameters, KEY &&id, T &&value, Bool isConstant, UInt dynamicTimestamp)
 
template<typename KEY >
static Result< void > InsertData (DataDictionary &parameters, KEY &&id, Data &&dataValue, Bool isConstant, UInt dynamicTimestamp)
 
static MAXON_METHOD Result< DataDictionary > LoadDefaults (const Id &materialType)
 
static MAXON_METHOD Result< ImageTextureRef > CreateImageTexture (const TextureBuffer &textureBuffer, const PixelFormat &pixelFormat)
 
static MAXON_METHOD Result< void > SaveMaterialExchangeData (const MaterialExchangeData &data, const Url &outputDirectory)
 
template<typename TYPE , typename KEY >
static Result< TypedConstantParameter< TYPE > > GetOrDefault (const DataDictionary &parameters, const DataDictionary &defaultParameters, KEY &&id)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (ParameterStorageInterface, MAXON_REFERENCE_NORMAL, "net.maxon.material.interface.parameterstorage")
 

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( ParameterStorageInterface  ,
MAXON_REFERENCE_NORMAL  ,
"net.maxon.material.interface.parameterstorage"   
)
private

◆ Extract() [1/2]

static Result<TypedConstantParameter<TYPE> > Extract ( const DataDictionaryInterface parameters,
KEY &&  id 
)
static

Extracts / gets an typed parameter from a DataDictionaryInterface object with type check between the requested value type and the attribute's type.

Template Parameters
TYPEThe value type of the parameter.
KEYThe type of the key attribute.
Parameters
[in]parametersThe DataDictionary holding the parameter.
[in]idThe parameter's attribute id.
Returns
The typed parameter on success.

◆ Extract() [2/2]

static Result<TypedConstantParameter<TYPE> > Extract ( const DataDictionary &  parameters,
KEY &&  id 
)
static

Extracts / gets an typed parameter from a DataDictionary with type check between the requested value type and the attribute's type.

Template Parameters
TYPEThe value type of the parameter.
KEYThe type of the key attribute.
Parameters
[in]parametersThe DataDictionary holding the parameter.
[in]idThe parameter's attribute id.
Returns
The typed parameter on success. For example, a base color can be extracted the following:
maxon::nodes::TypedConstantParameter<Color> baseColor = maxon::nodes::ParameterStorageInterface::Extract<Color>(parameters, maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::BASE_COLOR) iferr_return;
#define parameters
Definition: graminit.h:11
#define iferr_return
Definition: resultbase.h:1519

◆ Insert()

static Result<void> Insert ( DataDictionary &  parameters,
KEY &&  id,
T &&  value,
Bool  isConstant,
UInt  dynamicTimestamp 
)
static

Inserts a typed parameter into the provided DataDictionary with type check between the provided value and the attribute's type.

Template Parameters
KEYThe type of the key attribute.
Parameters
[out]parametersThe DataDictionary to hold on the parameter.
[in]idThe parameter's attribute id.
[in]valueThe typed constant / default value of the parameter.
[in]isConstantTrue if the parameter is constant (and requires no texture-driven representation).
[in]dynamicTimestampThe timestamp of the texture-driven representation.
Returns
OK on success. For example, a red base color can be inserted the following:
maxon::nodes::ParameterStorageInterface::Insert(parameters, maxon::NODESPACE::EXCHANGE::BUNDLE::VIEWPORTMATERIAL::BASE_COLOR, Color(1, 0, 0), true, 0) iferr_return;
Col3< Float, 1 > Color
Definition: vector.h:84

◆ InsertData()

static Result<void> InsertData ( DataDictionary &  parameters,
KEY &&  id,
Data &&  dataValue,
Bool  isConstant,
UInt  dynamicTimestamp 
)
static

Inserts an opaque parameter into the provided DataDictionary.

Template Parameters
KEYThe type of the key attribute.
Parameters
[out]parametersThe DataDictionary to hold on the parameter.
[in]idThe parameter's attribute id.
[in]dataValueThe opaque constant / default value of the parameter.
[in]isConstantTrue if the parameter is constant (and requires no texture-driven representation).
[in]dynamicTimestampThe timestamp of the texture-driven representation.
Returns
OK on success.

◆ LoadDefaults()

static MAXON_METHOD Result<DataDictionary> LoadDefaults ( const Id materialType)
static

Loads and parses the data description of material and inserts the defined default values into a DataDictionary. This method caches once-loaded description for performance.

Parameters
[in]materialTypeThe (bundle) type of the material representation.
Returns
The parameter set on success.

◆ CreateImageTexture()

static MAXON_METHOD Result<ImageTextureRef> CreateImageTexture ( const TextureBuffer textureBuffer,
const PixelFormat &  pixelFormat 
)
static

Creates an image for a F32 RGBA texture buffer with matching dimensions. The pixel format can be chosen freely, allowing a lossy reduction of the bit depth.

Parameters
[in]textureBufferThe parameter's attribute id.
[in]pixelFormatThe opaque constant / default value of the parameter.
Returns
The image on success.

For example, a texture buffer can be saved to disk the following:

maxon::ImageTextureRef bakedImage = maxon::material::ParameterStorageInterface::CreateImageTexture(textureBuffer, maxon::PixelFormats::RGBA::F32()) iferr_return;
maxon::Url imageOutputPath = maxon::Url("C:/Temp/bakedImage"_s);
imageOutputPath.SetSuffix("tif"_s) iferr_return;
const maxon::MediaOutputUrlRef destination = maxon::ImageSaverClasses::Tif().Create() iferr_return;
maxon::MediaSessionRef imageExportSession = maxon::MediaSessionObject().Create() iferr_return;
bakedImage.Save(imageOutputPath, destination, maxon::MEDIASESSIONFLAGS::RUNONLYANALYZE, &imageExportSession) iferr_return;
imageExportSession.Convert(TimeValue(), maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
imageExportSession.Close() iferr_return;
static MAXON_METHOD Result< ImageTextureRef > CreateImageTexture(const TextureBuffer &textureBuffer, const PixelFormat &pixelFormat)
static auto Create(ARGS &&... args)
Definition: apibase.h:2773
The maxon namespace contains all declarations of the MAXON API.
Definition: autoweight.h:14
MEDIASESSIONFLAGS
Definition: mediasession_session.h:15

◆ SaveMaterialExchangeData()

static MAXON_METHOD Result<void> SaveMaterialExchangeData ( const MaterialExchangeData data,
const Url outputDirectory 
)
static

Saves a collection of material constants and texture buffers to a file directory. The constants are converted to strings and saved into a "constants.json" file. Texture buffers are saved to F32 RGBA Tif files named according to the Ids. This function is particularly helpful for debugging purposes.

Parameters
[in]dataThe material data containing constant values and texture buffers.
[in]outputDirectoryThe output directory to populate with JSON and Tif files.
Returns
OK on success.

◆ GetOrDefault()

static Result<TypedConstantParameter<TYPE> > GetOrDefault ( const DataDictionary &  parameters,
const DataDictionary &  defaultParameters,
KEY &&  id 
)
static

Convenience function to extract a typed parameter under #id from the provided parameters container if contained. Otherwise, #defaultParameters will be queried.

Template Parameters
KEYThe type of the key attribute.
Parameters
[in]parametersThe DataDictionary that is expected to hold the parameter.
[in]defaultParametersThe DataDictionary that is expected to hold the default parameter as a fallback.
Returns
The parameter on success.

This helper function makes it easier to write code that is robust against producers that only populate some parameters of the material. If a parameter is missing, it is reasonable to fall back to a default. The usage is the following:

const maxon::DataDictionary defaultParameters = maxon::material::ParameterStorageInterface::LoadDefaults(maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::GetId()) iferr_return;
const maxon::material::TypedConstantParameter<Color> baseColor = maxon::material::ParameterStorageInterface::GetOrDefault(parameters, defaultParameters, maxon::MATERIAL::PORTBUNDLE::STANDARDSURFACE::BASE_COLOR) iferr_return;
const maxon::Color baseColorValue = baseColor._value;
static Result< TypedConstantParameter< TYPE > > GetOrDefault(const DataDictionary &parameters, const DataDictionary &defaultParameters, KEY &&id)
Definition: materialparameter.h:371
static MAXON_METHOD Result< DataDictionary > LoadDefaults(const Id &materialType)