Byte Engine Docs

MaterialX support

Look up the MaterialX version, shading models, and elements Byte Engine reads, and where a shaded surface differs from the document.

Byte Engine reads MaterialX version 1.39. A document arrives as a directed acyclic graph of nodes: every reference is resolved to an edge, every node is matched to its declaration, and connected ports are checked to agree on their type.

Each material converts into a Byte Engine Material Expression (BEMX) graph, the material description every renderer reads. To read a document from Rust, convert a material, or fix a document that fails to load, follow MaterialX documents.

Shading models

Four shading models convert directly onto the metallic-roughness surface a BEMX graph ends in: standard_surface, open_pbr_surface, UsdPreviewSurface and gltf_pbr. Two more are read as special cases: Disney's disney_principled, and surface_unlit, whose emission carries everything it shows. A model you define yourself works too, as long as its node graph produces one of those.

Behind the shading model, the network may use the standard library's value, channel, geometric, texture, math, adjustment and compositing nodes, and any node graph the document defines. Each of those converts to the BEMX node of the same meaning. Integer and boolean values become floats, because BEMX computes in floats alone.

Byte Engine reports anything else rather than approximating it. In particular, a surface built out of individual scattering closures, such as a <surface> node fed by dielectric_bsdf and oren_nayar_diffuse_bsdf, does not map onto a BEMX surface. Rebuild it on one of those models, or bake the network into textures with the MaterialX tools.

Differences from the document

Three things behave differently from the document:

  • Object-space and model-space geometric properties read their world-space value.
  • Images sample with the mesh's own texture coordinates. An <image> whose texcoord is driven by anything else, such as a place2d or a tiledimage, is reported instead of being sampled at the wrong place.
  • A texcoord node that reads a set other than zero converts, but a renderer that carries one texture coordinate set reports it when it builds the shader.

A shading model's normal input is a world-space normal, and it becomes the BEMX surface's normal unchanged when a shading network drives it. A constant or unconnected normal leaves the geometric normal in place.

Coat, sheen, transmission and subsurface inputs aren't converted, because a BEMX surface has no input for them.

Elements that are read

Everything that shapes the graph: nodes, nodegraphs both functional and compound, node declarations and their inheritance, implementations, custom types, geometric property declarations, units, and material variants.

Elements that assign materials to geometry, <look> and its companions, and elements that only describe how a graph is drawn in an editor are recognised and skipped, because neither changes the graph.

On this page