Interface MaterialManagerInterface

The MaterialManagerInterface interface allows the coloring of the DMU.

This interface is used to create and set materials for geometric instances from their geometric instance ids. All materials are accessed by their material id, there is no specific "material objects" to handle.

WARNING : there is a fixed limit for the total number of different materials that may be in use.

Original materials refer to the materials loaded from the DMU and custom materials refer to the API created materials. Depending on the number of original materials of the DMU, there may be a different number of custom materials that may be created. The number of custom materials that may be created is given by getNbAvailableCustomMaterials. Only custom materials can be created, modified or removed; original materials of the DMU can only be queried but not modified.

A single geometric instance may have multiple original materials, in case of a multi material geometry. For these geometries, it is NOT possible to change the coloring of each individual sub-geometry. In case of a custom material application, the whole geometry color will be changed.

The MaterialManagerInterface is a member of the InfiniteEngineInterface, accessed through getMaterialManager.

/** 
 * Sample to illustrate the change of colors of `geometric instance` (MaterialManagerInterface).
 */
import { InfiniteEngineInterface, MaterialManagerInterface, Vector3 } from 'generated/documentation/appinfiniteapi';

// created previously
let lInfiniteEngine : InfiniteEngineInterface;
// the `geometric instance id` to check
let lGeometricInstanceId : number;
// get the material manager
const lMaterialManager : MaterialManagerInterface = lInfiniteEngine.getMaterialManager();

// warning, in case of multi materials, multiple materials may be retrieved
const lNbMaterials : number = lMaterialManager.getOriginalNbMaterialsOfInstance(lGeometricInstanceId);
const lOriginalMaterials : number[] = [];

if ((!lMaterialManager.getOriginalMaterialsOfInstance(lGeometricInstanceId, lOriginalMaterials)) || (lOriginalMaterials.length === 0))
{
    console.log('Error while fetching original materials');
}
console.assert(lNbMaterials === (lOriginalMaterials.length));

// get the diffuse color of the given `geometric instance`
const lOriginalColor : Vector3 = new Vector3();
if (!lMaterialManager.getMaterialDiffuse(lOriginalMaterials[0], lOriginalColor))
{
    console.log('Error while fetching original material color')
}

// colors are expressed as Vector3 red,green,blue (in this order), in the range [0:1]
// 
const lGreenColor : Vector3 = new Vector3(0, 1, 0);
const lRedColor : Vector3 = new Vector3(1, 0, 0);
const lBlueColor : Vector3 = new Vector3(0, 0, 1);
const lWhiteColor : Vector3 = new Vector3(1, 1, 1);

// create an array of colors to cycle through
const lColors : Vector3 [] = [lGreenColor, lRedColor, lBlueColor, lWhiteColor];
// where are we in the array ?
let lCurrentColorOffset : number = 0;

// create a custom material, but instead of creating multiple materials, use one and 
// modify it
const lCustomMaterialId : number = lMaterialManager.createNewMaterial(lRedColor);

// callback to be called on mouse down
const onChangeMaterial = () : void =>
{
    // should we set a color or restore it ?
    if (lCurrentColorOffset < lColors.length)
    {
        // modify the custom material
        lMaterialManager.modifyMaterial(lCustomMaterialId, lColors[lCurrentColorOffset]);
        if (lMaterialManager.getMaterialOfInstance(lGeometricInstanceId) !== lCustomMaterialId)
        {
            // and change the current material if relevant
            lMaterialManager.changeMaterialOfInstance(lGeometricInstanceId, lCustomMaterialId);
        }
        // next color for next time
        ++lCurrentColorOffset;
    }
    else
    {
        // we should restore the material for the element
        if (lMaterialManager.getMaterialOfInstance(lGeometricInstanceId) === lCustomMaterialId)
        {
            // but only if relevant
            lMaterialManager.restoreOriginalMaterialOfInstance(lGeometricInstanceId);
        }
        // go back to the start of tests
        lCurrentColorOffset = 0;
    }
}

// when should we change the colors of the given `geometric instance` ?
// => mouse down
document.addEventListener('mousedown', onChangeMaterial);

Please refer to the [InfiniteEngineInterface](InfiniteEngineInterface.html) for more information.
3D Rendering

See

InfiniteEngineInterface

Hierarchy

  • MaterialManagerInterface

Methods

changeMaterialOfAllInstances changeMaterialOfInstance changeMaterialOfInstances createNewMaterial getMaterialDiffuse getMaterialIds getMaterialOfInstance getNbAvailableCustomMaterials getNbCustomMaterials getOriginalMaterialsOfInstance getOriginalNbMaterialsOfInstance hasCustomMaterial isOriginalMaterial modifyMaterial removeMaterial restoreOriginalMaterialOfAllInstances restoreOriginalMaterialOfInstance restoreOriginalMaterialOfInstances

Methods

changeMaterialOfAllInstances

  • Changes the material of all geometric instances to a given custom material.

    Returns false if the material does not exist, is not a custom one. The custom material must have been created before being used (see createNewMaterial).

    Returns

    true if the material has been changed.

    Parameters

    • pMaterialId: number
      in
      The material to set (material id as returned by [createNewMaterial](MaterialManagerInterface.html#createNewMaterial)).

    Returns boolean

changeMaterialOfInstance

  • Changes the material of the given geometric instance to a given custom material.

    Returns false if the material does not exist , is not a custom one or if the geometric instance id is invalid. The custom material must have been created before being used (see createNewMaterial).

    Returns

    true if the material has been changed.

    Parameters

    • pGeometricInstanceId: number
      in
      The geometric instance id of the geometric instance to change.
    • pMaterialId: number
      in
      The material to set (material id as returned by [createNewMaterial](MaterialManagerInterface.html#createNewMaterial)).

    Returns boolean

changeMaterialOfInstances

  • Changes the material of the given geometric instances to a given custom material.

    Returns false if the material does not exist, is not a custom one or if any geometric instance id is invalid. The custom material must have been created before being used (see createNewMaterial).

    Returns

    true if the material has been changed.

    Parameters

    • pGeometricInstanceIds: number[] | Uint32Array
      in
      The geometric instance ids of the geometric instances to change.
    • pMaterialId: number
      in
      The material to set (material id as returned by [createNewMaterial](MaterialManagerInterface.html#createNewMaterial)).

    Returns boolean

createNewMaterial

  • Creates a new custom material of the given color.

    Returns

    The id of the new material, or -1 if the material could not be created (i.e. the limit of materials has been reached).

    See

    getNbAvailableCustomMaterials

    Parameters

    • pDiffuse: Vector3
      in
      The new diffuse color (3 floats in the range [0:1], x is red, y is green, b is black).

    Returns number

getMaterialDiffuse

  • Gets the diffuse color of the material.

    Returns

    true if pDiffuse was modified, and therefore the material exists.

    Parameters

    • pMaterialId: number
      in
      The material id to query.
    • pDiffuseOut: Vector3
      out
      The diffuse color of the given material.

    Returns boolean

getMaterialIds

  • Gets a copy of the array containing the list of the custom material ids currently in use.

    Returns

    The array of custom material ids.

    Returns number[]

getMaterialOfInstance

  • Gets the current material applied to the given instance, returns -1 if the geometric instance id is invalid.

    The returned value can refer either to a custom material id or an original material id. In case of an original material (see isOriginalMaterial), the id corresponds to the first id of getOriginalMaterialsOfInstance. Indeed, in case of a multi-material geometry, a single geometric instance may have multiple original materials.

    Returns

    The current material id of the instance, -1 if the geometric instance id is invalid.

    Parameters

    • pGeometricInstanceId: number
      in
      The instance id number to retrieve the current material id from.

    Returns number

getNbAvailableCustomMaterials

  • Gets the number of custom materials that may be created.

    This value does not depend on the custom materials already created. Once the DMU is loaded, you can expect this value to be constant.

    Returns

    The number of custom materials that may be created.

    Returns number

getNbCustomMaterials

  • Gets the number of custom materials currently in use.

    Returns

    The number of already created custom materials.

    Returns number

getOriginalMaterialsOfInstance

  • Retrieves all original material ids of the given geometric instance, even if a custom material has been applied to the geometric instance.

    This method is recommended when it is certain that the material of the given instance has not been overridden, else prefer getMaterialOfInstance.

    Returns

    true if the list of material ids has been retrieved (thus pGeometricInstanceId is valid).

    Parameters

    • pGeometricInstanceId: number
      in
      The geometric instance id to retrieve the original material ids from.
    • pMaterialIdsOut: number[]
      out
      The resulting original material ids of the given geometric instance id.

    Returns boolean

getOriginalNbMaterialsOfInstance

  • Gets the number of original materials of the given instance, even if a custom material has been applied to the geometric instance.

    Any geometric instance can have multiple original materials.

    Returns

    The current number of materials of the given geometric instance (at least 1), -1 if the given geometric instance id is invalid.

    Parameters

    • pGeometricInstanceId: number
      in
      The geometric instance id to retrieve the original material ids from.

    Returns number

hasCustomMaterial

  • Tells if the material corresponding to the given material id is an already created custom material.

    Returns

    true if the custom material exists.

    Parameters

    • pMaterialId: number
      in
      The material id to check.

    Returns boolean

isOriginalMaterial

  • Tells if the material corresponding to the given material id is included in the DMU s original materials (in opposition to custom materials).

    Returns

    true if the material id exists and is an original material.

    Parameters

    • pMaterialId: number
      in
      The material id to check.

    Returns boolean

modifyMaterial

  • Modifies the color of a custom material, changing its rendering parameters.

    It is NOT possible to edit original materials of the DMU.

    Returns

    true if the material was changed (i.e. the material id was correct and not an original material id).

    Parameters

    • pMaterialId: number
      in
      The custom material id of the material to edit.
    • pDiffuse: Vector3
      in
      The new diffuse color (3 floats in the range [0:1], red, green, blue).

    Returns boolean

removeMaterial

  • Removes the given material from the list of custom materials.

    Returns

    true if the material has been removed (exists and is a custom material).

    Parameters

    • pMaterialId: number
      in
      The id of the custom material to remove.

    Returns boolean

restoreOriginalMaterialOfAllInstances

  • Restores all the geometric instances to their original color.

    Returns void

restoreOriginalMaterialOfInstance

  • Restores the geometric instance to its original color.

    Restoring a material of a geometric instance that still has its original material is legal and therefore returns true.

    Returns

    true if the material has been restored (be it custom or not), false if the geometric instance id is invalid.

    Parameters

    • pGeometricInstanceId: number
      in
      The geometric instance id of the geometric instance to restore.

    Returns boolean

restoreOriginalMaterialOfInstances

  • Restores the geometric instances to their original colors.

    Restoring a material of a geometric instance that still has its original material is legal. All geometric instance ids must be valid in order to success.

    Returns

    true if the material has been restored, false if an invalid id is found in the geometric instance ids.

    Parameters

    • pGeometricInstanceIds: number[] | Uint32Array
      in
      The geometric instance ids of the geometric instances to restore.

    Returns boolean

Settings

Member Visibility

Theme