MaterialAPI

Interface MaterialAPI

The MaterialAPI provides a set of methods for creating and managing materials in a webvis context. It allows you to:

  • Create materials and assign them to specific nodes in a scene.
  • Edit and update existing materials.
  • Retrieve all materials at once.
  • Request detailed material data for a specific material.
  • Remove materials when they are no longer needed.

The fastest way to get familiar with the MaterialAPI is by creating a material and assigning it to a node. The material can then be updated later and removed when it is no longer needed:

// Get the webvis context
const context = webvis.getContext();

// Create a node to assign the material to and enable the resource to make it visible
const nodeId = context.add({dataURI: "urn:x-i3d:shape:box", initialProperties: {enabled: true}});

// Create a material
const materialId = context.createMaterial({
     baseColor: [1, 0, 0],
     opacity: 1,
     roughness: 0.5,
     metallic: 0,
     name: "Red Material",
});

// Create an appearance URI which can be used to assign the material to a node
const appearanceURI = `urn:X-l3d:material:${materialId}`;

// Assign the material to the previously added node via the APPEARANCE_URI property
await context.setProperty(nodeId, webvis.Property.APPEARANCE_URI, appearanceURI);

 // Change the base color and the name of the material
context.changeMaterial(materialId, {
     baseColor: [0, 1, 0],
     name: "Green Material"
 });

// Unassign the material from the node
await context.setProperty(nodeId, webvis.Property.APPEARANCE_URI, null);

// Remove the material if no longer required
context.removeMaterial(materialId);

The following events are associated with the MaterialAPI:

interface MaterialAPI {
    changeMaterial(
        materialId: number,
        properties: MaterialProperties,
    ): MaterialProperties;
    createMaterial(properties?: MaterialProperties): number;
    getMaterialData(materialId: number): MaterialProperties;
    getMaterials(): number[];
    removeMaterial(materialId: number, safe?: boolean): RemoveState;
}

Hierarchy (View Summary)

Index

Methods

changeMaterial createMaterial getMaterialData getMaterials removeMaterial

Methods

  • Experimental

    Experimental. May be changed in the future without notice.

    Changes one or more properties of a material with the specified ID and triggers a MaterialChangedEvent.

    Parameters

    • materialId: number

      The ID of the material you want to change.

    • properties: MaterialProperties

      The properties of the material you want change.

    Returns MaterialProperties

    An object with the changed properties.

  • Experimental

    Experimental. May be changed in the future without notice.

    Creates a new material and triggers a MaterialCreatedEvent.

    Parameters

    Returns number

    The ID of the newly created material.

  • Experimental

    Experimental. May be changed in the future without notice.

    Returns the properties of the material entity with the specified ID.

    Parameters

    • materialId: number

      The ID of the material entity.

    Returns MaterialProperties

    The properties of the material entity.

  • Experimental

    Experimental. May be changed in the future without notice.

    Returns the IDs of all material entities in the webvis context.

    Returns number[]

    The IDs of all available materials

  • Experimental

    Experimental. May be changed in the future without notice.

    Removes the material from the scene and all related snapshots and triggers a MaterialRemovedEvent.

    Parameters

    • materialId: number

      The ID of the material.

    • Optionalsafe: boolean

      Performs a safe remove which interrupts the removal process if the material is part of one or more Snapshots. Default: false

    Returns RemoveState

    The resulting state of the removal process.