Individual Faces

In Babylon.js, the concept of individual faces refers to the ability to manipulate and customize the appearance and properties of each face of a mesh separately. This feature is particularly useful for enhancing visual detail and achieving complex effects without the need for additional geometry.

Boxes, cylinders, extruded polygons and polyhedrons have identifiable faces and have the faceUV and faceColors parameters in the options using the MeshBuilder method to create them. This means that each of their faces can have a different texture or color. For colors a particular color is mapped to a particular face. For textures part of the image file is mapped to a particular face. This can be done with any image and it is often useful to use a texture atlas containing a number of images combined into one image file.

Face Numbers

The face numbers refers to the index of a specific face on a mesh. Each face of a mesh is defined by a set of vertices, and Babylon.js allows developers to access and manipulate these faces individually. When working with individual faces, you can identify and apply different materials, textures, or effects based on their face index. This is particularly useful for complex models where different sides require distinct appearances.

function getFaceUVs() {
    return [
        new Vector4(0.75, 0.333, 1, 0.666), // back (+z)
        new Vector4(0.25, 0.333, 0.5, 0.666), // front (-z)
        new Vector4(0.5, 0.333, 0.75, 0.666), // right (+x)
        new Vector4(0, 0.333, 0.25, 0.666), // left (-x)
        new Vector4(0.25, 0.666, 0.5, 1), // top (+y)
        new Vector4(0.25, 0, 0.5, 0.333), // bottom (-y)
    ];
}
 
// ...
 
<box name='box' options={{ faceUV: getFaceUVsT(), wrap: true }}>
    <standardMaterial name='material' emissiveColor={Color3.White()}>
        <texture kind='diffuseTexture' url={uvT.src} />
    </standardMaterial>
</box>

Atlas

A texture atlas is a large image that contains multiple smaller textures. Instead of using separate texture files for each face or part of a model, a texture atlas combines them into a single image. This can significantly improve performance by reducing the number of texture bindings during rendering. When using a texture atlas, you can specify which part of the atlas to use for a particular face. This is done by adjusting UV coordinates for the mesh’s faces, allowing different parts of the model to reference different sections of the atlas. This technique is especially beneficial in environments with numerous objects sharing common textures.

function getFaceUVs(columns: number, rows: number, rowPosition: number = 0) {
    return new Array(6).fill(null).map((_, index) => new Vector4(index / columns, (0 + rowPosition) / rows, (index + 1) / columns, (1 + rowPosition) / rows));
}
 
// ...
 
<box name='box' options={{ faceUV: getFaceUVs(6, 4, 1), wrap: true }}>
    <standardMaterial name='material' emissiveColor={Color3.White()}>
        <texture kind='diffuseTexture' url={uv6x4.src} />
    </standardMaterial>
</box>
 

Face Colors

Face colors refer to the color assigned to specific faces of a mesh. This can be accomplished using vertex colors, which allow each vertex to have its own color that can be interpolated across the face, resulting in varying colors on different faces.

const colors = [Color3.Gray, Color3.Red, Color3.Green, Color3.Blue, Color3.Yellow, Color3.Purple].map(Color3 => Color4.FromColor3(Color3()));
 
// ...
 
<box name='box' options={{ faceColors: colors }}>
    <standardMaterial name='material' emissiveColor={Color3.White()} />
</box>

Cylinder

A cylinder has three surfaces, the top, the bottom and the tube joining them. For the face options face 0 is the bottom, face 1 is the tube and face 2 the top.

const cylinderUVs = [new Vector4(0, 0, 0, 0), new Vector4(1, 0, 0.33, 1), new Vector4(0, 0, 0.25, 1)]; // bottom, top, center 
 
// ...
 
<cylinder name='cylinder' options={{ faceUV: cylinderUVs, height: 1 }}>
    <standardMaterial name='material' emissiveColor={Color3.White()}>
        <texture kind='diffuseTexture' url={uvCylinder.src} />
    </standardMaterial>
</cylinder>

Learn More

For additional info and advanced use cases, please refer to Babylon.js documentation: https://doc.babylonjs.com/features/featuresDeepDive/materials/using/texturePerBoxFace.