Skip to content

3D engine that AI agents drive

8.6 KB
Raw Blame
// Extra PBR layers on top of the base metallic-roughness material, named as in the glTF KHR_materials_* extensions.
// This module holds plain data only, so the MCP server, recipes, the glTF code and the renderer share one set of ranges.

const UNIT = Object.freeze([0, 1]);
// KHR_materials_specular allows any non-negative colour factor, and Blender writes 10 for glossy Cycles materials. The
// reflectance is clamped to 1 after the IOR term (dielectricReflectance), so a value above 1 divided by that term is harmless.
const SPECULAR_COLOR_MAXIMUM = 1000;
// Bit 0 is the sun, then the point, spot and area lights in that order (light-link-bits.js). Every bit of the 32 bit integer is set.
export const ALL_LIGHTS_MASK = -1;

export const MATERIAL_LAYER_DEFAULTS = Object.freeze({
  clearcoat: 0,
  clearcoatRoughness: 0,
  transmission: 0,
  thickness: 0,
  ior: 1.5,
  dispersion: 0,
  attenuationColor: Object.freeze([1, 1, 1]),
  attenuationDistance: Infinity,
  sheenColor: Object.freeze([0, 0, 0]),
  sheenRoughness: 0,
  specular: 1,
  specularColor: Object.freeze([1, 1, 1]),
  anisotropy: 0,
  anisotropyRotation: 0,
  iridescence: 0,
  iridescenceIor: 1.3,
  iridescenceThickness: 400,
  toon: 0,
});

export const MATERIAL_LAYER_FIELDS = Object.freeze(Object.keys(MATERIAL_LAYER_DEFAULTS));

export const MATERIAL_LAYER_SCALAR_RANGES = Object.freeze({
  clearcoat: UNIT,
  clearcoatRoughness: UNIT,
  transmission: UNIT,
  thickness: Object.freeze([0, 1000]),
  ior: Object.freeze([1, 2.5]),
  dispersion: Object.freeze([0, 10]),
  sheenRoughness: UNIT,
  specular: Object.freeze([0, 4]),
  anisotropy: UNIT,
  anisotropyRotation: Object.freeze([-2 * Math.PI, 2 * Math.PI]),
  iridescence: UNIT,
  iridescenceIor: Object.freeze([1, 3]),
  iridescenceThickness: Object.freeze([0, 1200]),
  toon: Object.freeze([0, 8]),
});

export const MATERIAL_LAYER_COLOR_RANGES = Object.freeze({
  attenuationColor: UNIT,
  sheenColor: UNIT,
  specularColor: Object.freeze([0, SPECULAR_COLOR_MAXIMUM]),
});

function describeRange([minimum, maximum]) {
  return `between ${minimum} and ${maximum}`;
}

function checkScalar(field, value) {
  const [minimum, maximum] = MATERIAL_LAYER_SCALAR_RANGES[field];
  if (typeof value !== 'number' || !Number.isFinite(value) || value < minimum || value > maximum) {
    throw new RangeError(`${field} must be ${describeRange(MATERIAL_LAYER_SCALAR_RANGES[field])}, got ${value}. Use a number inside that range.`);
  }
}

function checkColor(field, value) {
  const [minimum, maximum] = MATERIAL_LAYER_COLOR_RANGES[field];
  const isLinearColor = Array.isArray(value) && value.length === 3 &&
    value.every(component => typeof component === 'number' && Number.isFinite(component) && component >= minimum && component <= maximum);
  if (!isLinearColor) {
    throw new RangeError(`${field} must be three linear RGB numbers ${describeRange(MATERIAL_LAYER_COLOR_RANGES[field])}. Pass [red, green, blue].`);
  }
}

/** Each toon step colour is a linear RGB weight on that step's light; above 1 brightens it. */
export const TOON_COLOR_MAXIMUM = 4;

function checkToonColors(material) {
  const colors = material.toonColors;
  if (colors === undefined) return;
  const steps = material.toon ?? 0;
  if (!(steps > 0)) {
    throw new RangeError(`toonColors needs toon above 0 (the step count), got toon ${steps}. Set toon to ${Array.isArray(colors) ? colors.length : 3} or remove toonColors.`);
  }
  if (!Array.isArray(colors) || colors.length !== steps) {
    throw new RangeError(`toonColors must be an array of ${steps} colours, one per toon step from darkest to lightest, got ${Array.isArray(colors) ? colors.length : colors}. Pass ${steps} [red, green, blue] triples, or change toon to ${Array.isArray(colors) ? colors.length : 3}.`);
  }
  colors.forEach((color, index) => {
    const isLinearColor = Array.isArray(color) && color.length === 3 &&
      color.every(component => typeof component === 'number' && Number.isFinite(component) && component >= 0 && component <= TOON_COLOR_MAXIMUM);
    if (!isLinearColor) {
      throw new RangeError(`toonColors[${index}] must be three linear RGB numbers between 0 and ${TOON_COLOR_MAXIMUM}. Pass [red, green, blue].`);
    }
  });
}

function checkAttenuationDistance(value) {
  const isPositive = typeof value === 'number' && value > 0 && Number.isFinite(value);
  if (!isPositive) {
    throw new RangeError(`attenuationDistance must be a finite number above 0 (metres), got ${value}. Leave it out for no absorption.`);
  }
}

/** Throws a RangeError that names the field and the fix for the first layer value that is out of range. */
export function validateMaterialLayers(material) {
  for (const field of Object.keys(MATERIAL_LAYER_SCALAR_RANGES)) {
    if (material[field] !== undefined) checkScalar(field, material[field]);
  }
  for (const field of Object.keys(MATERIAL_LAYER_COLOR_RANGES)) {
    if (material[field] !== undefined) checkColor(field, material[field]);
  }
  checkToonColors(material);
  if (material.attenuationDistance !== undefined && material.attenuationDistance !== Infinity) {
    checkAttenuationDistance(material.attenuationDistance);
  }
  if (material.transmission > 0 && material.tag !== undefined && material.tag !== 'surface' && material.tag !== 'gltf' && material.tag !== 'liquid') {
    throw new RangeError(`transmission needs a standard PBR material tag, got ${material.tag}. Use the surface tag.`);
  }
}

// A material graph's {"fresnel":{"ior":n}} factor of emission (material-graph.js) reaches the renderers as `emissionFresnel`:
// the IOR, or 0 for none. The raster shader and the CPU path tracer both evaluate this same curve per pixel.
export const EMISSION_FRESNEL_IOR_RANGE = Object.freeze([1.01, 3]);

/** Schlick's Fresnel reflectance of a dielectric at the cosine between the view and the normal: 1 at grazing angles. */
export function fresnelSchlick(cosine, ior) {
  const normalIncidence = ((ior - 1) / (ior + 1)) ** 2;
  const clamped = Math.min(Math.max(cosine, 0), 1);
  return normalIncidence + (1 - normalIncidence) * (1 - clamped) ** 5;
}

export function materialLayerValue(material, field) {
  return material[field] ?? MATERIAL_LAYER_DEFAULTS[field];
}

/** True when the material asks for any layer beyond the base material. */
export function hasMaterialLayers(material) {
  return MATERIAL_LAYER_FIELDS.some(field => material[field] !== undefined && material[field] !== MATERIAL_LAYER_DEFAULTS[field]
    && JSON.stringify(material[field]) !== JSON.stringify(MATERIAL_LAYER_DEFAULTS[field]));
}

/** Reflectance of a dielectric at normal incidence, as the glTF specular and IOR extensions combine it. */
export function dielectricReflectance(material) {
  const ior = materialLayerValue(material, 'ior');
  const fromIor = ((ior - 1) / (ior + 1)) ** 2;
  const weight = materialLayerValue(material, 'specular');
  return materialLayerValue(material, 'specularColor').map(component => Math.min(fromIor * component, 1) * weight);
}

/**
 * Plain values the renderer batches by: dielectric F0 (3), coat (2), sheen (4), transmission (4), attenuation colour (3),
 * anisotropy strength and rotation (2), iridescence factor, film IOR and film thickness in nanometres (3), light mask (1), toon bands (1), and the subsurface block as JSON, or '' (1; subsurface-limits.js and the addon read it), emission fresnel (1), the emission mask: axis index or -1, from, to (3) and the toon step colours as JSON, or '' (1; toon-shader.js reads it).
 */
export function materialLayerState(material) {
  validateMaterialLayers(material);
  return [
    ...dielectricReflectance(material),
    materialLayerValue(material, 'clearcoat'),
    materialLayerValue(material, 'clearcoatRoughness'),
    ...materialLayerValue(material, 'sheenColor'),
    materialLayerValue(material, 'sheenRoughness'),
    materialLayerValue(material, 'transmission'),
    materialLayerValue(material, 'ior'),
    materialLayerValue(material, 'thickness'),
    materialLayerValue(material, 'attenuationDistance'),
    ...materialLayerValue(material, 'attenuationColor'),
    materialLayerValue(material, 'anisotropy'),
    materialLayerValue(material, 'anisotropyRotation'),
    materialLayerValue(material, 'iridescence'),
    materialLayerValue(material, 'iridescenceIor'),
    materialLayerValue(material, 'iridescenceThickness'),
    material.lightMask ?? ALL_LIGHTS_MASK,
    materialLayerValue(material, 'toon'),
    material.subsurface ? JSON.stringify(material.subsurface) : '',
    material.emissionFresnel ?? 0,
    'xyz'.indexOf(material.emissionMask?.axis),
    material.emissionMask?.from ?? 0,
    material.emissionMask?.to ?? 1,
    material.toonColors ? JSON.stringify(material.toonColors) : '',
  ];
}

export const MATERIAL_LAYER_STATE_LENGTH = 29;