Unreal Material API

Unreal Material API#

instant3Dhub: Unreal Material API

instant3Dhub

Detailed Description

Unreal-side extension for rendering 3D data with Unreal Engine materials.

This group covers resolver bindings and runtime material selection for Custom Material URNs. In general, 3D data references MaterialAPI materials through AppearanceURI = urn:X-l3d:material:<ID>, where <ID> is the numeric MaterialAPI material id. Experimentally, Unreal also accepts AppearanceURI = urn:X-l3d:material:<suffix> where <suffix> may be a full Custom Material URN in the form urn:NID:NSS. Invalid suffixes fall back the same way as invalid material ids.

Use it to bind custom URN namespaces to resolver objects and map Unreal Custom Material URNs to Unreal Engine materials at runtime.

Custom resolver lifecycle:

Bind a resolver object to an NID on AI3DHConnector::CustomMaterialURNResolvers.
At runtime, UI3DHCustomMaterialURNResolver::ResolveURN resolves each Custom Material URN NSS to one FI3DHGeometryMaterials result using state stored on the resolver object itself.

Quick start:

Pick a custom namespace for your Custom Material URNs, such as urn:my-namespace:steel.
Bind the NID my-namespace to a resolver on AI3DHConnector::CustomMaterialURNResolvers.
Derive from UI3DHCustomMaterialURNResolver to implement your own custom resolver or use UI3DHMapCustomMaterialURNResolver together with UI3DHCustomMaterialResourceMap for the simplest NSS-to-material mapping.

Use UI3DHUtilities for URN parsing and validation helpers.

Experimental: The Unreal Material API is experimental and under active development. Please use at your own risk.

See also: AI3DHConnector; UI3DHCustomMaterialURNResolver; UI3DHMapCustomMaterialURNResolver; UI3DHCustomMaterialResourceMap

Classes
struct	FI3DHGeometryMaterials
class	UI3DHCustomMaterialURNResolver
class	UI3DHCustomMaterialResourceMap
class	UI3DHMapCustomMaterialURNResolver

Functions
const class UI3DHCustomMaterialURNResolver *	AI3DHConnector::FindCustomMaterialURNResolver (const FI3DHNamespaceIdentifier &NID) const

Variables
TMap< FI3DHNamespaceIdentifier, TObjectPtr< class UI3DHCustomMaterialURNResolver > >	AI3DHConnector::CustomMaterialURNResolvers

Function Documentation

◆ FindCustomMaterialURNResolver()

const class UI3DHCustomMaterialURNResolver * AI3DHConnector::FindCustomMaterialURNResolver ( const FI3DHNamespaceIdentifier & NID ) const

Returns the resolver object bound to a Custom Material URN namespace.

Returns: nullptr if not found.

Variable Documentation

◆ CustomMaterialURNResolvers

TMap<FI3DHNamespaceIdentifier, TObjectPtr<class UI3DHCustomMaterialURNResolver> > AI3DHConnector::CustomMaterialURNResolvers

protected

Binds Custom Material URN namespaces to resolver objects.

For a Custom Material URN of the form urn:NID:NSS, the connector uses the NID key from this map to choose a resolver, then passes the NSS to that resolver to select a material. This is used by Unreal's experimental urn:X-l3d:material:<full custom-material-urn> extension as well as other Unreal-side Custom Material URN entry points.

Keys must be valid Namespace Identifiers and must not use the reserved plugin prefixes:

must be longer than 2 characters.
may only contain letters, digits, and '-'.
must not start with l3d, X-l3d, i3d, or x-i3d.