Materials describe a surface's appearance and response to light.

Each Primitive within a Mesh may be assigned a single Material. The number of GPU draw calls typically increases with both the numbers of Primitives and of Materials in an asset; Materials should be reused wherever possible. Techniques like texture atlasing and vertex colors allow objects to have varied appearances while technically sharing a single Material.

Material properties are modified by both scalars (like baseColorFactor) and textures (like baseColorTexture). When both are available, factors are considered linear multipliers against textures of the same name. In the case of base color, vertex colors (COLOR_0 attributes) are also multiplied.

Textures containing color data (baseColorTexture, emissiveTexture) are sRGB. All other textures are linear. Like other resources, textures should be reused when possible.

Usage:

const material = doc.createMaterial('myMaterial')
    .setBaseColorFactor([1, 0.5, 0.5, 1]) // RGBA
    .setOcclusionTexture(aoTexture)
    .setOcclusionStrength(0.5);

mesh.listPrimitives()
    .forEach((prim) => prim.setMaterial(material));

Hierarchy

Properties

propertyType: MATERIAL

Property type.

AlphaMode: Record<string, MaterialAlphaMode> = ...

Constants.

Methods

  • dispatchEvent(event: BaseEvent): Material
  • Events.

  • dispose(): void
  • Removes both inbound references to and outbound references from this object. At the end of the process the object holds no references, and nothing holds references to it. A disposed object is not reusable.

  • Returns true if two properties are deeply equivalent, recursively comparing the attributes of the properties. For example, two Primitives are equivalent if they have accessors and materials with equivalent content — but not necessarily the same specific accessors and materials.

  • getAlpha(): number
  • getAlphaCutoff(): number
  • Returns the mode of the material's alpha channels, which are provided by baseColorFactor and baseColorTexture.

    • OPAQUE: Alpha value is ignored and the rendered output is fully opaque.
    • BLEND: Alpha value is used to determine the transparency each pixel on a surface, and the fraction of surface vs. background color in the final result. Alpha blending creates significant edge cases in realtime renderers, and some care when structuring the model is necessary for good results. In particular, transparent geometry should be kept in separate meshes or primitives from opaque geometry. The depthWrite or zWrite settings in engines should usually be disabled on transparent materials.
    • MASK: Alpha value is compared against alphaCutoff threshold for each pixel on a surface, and the pixel is either fully visible or fully discarded based on that cutoff. This technique is useful for things like leafs/foliage, grass, fabric meshes, and other surfaces where no semitransparency is needed. With a good choice of alphaCutoff, surfaces that don't require semitransparency can avoid the performance penalties and visual issues involved with BLEND transparency.

    Reference:

  • getBaseColorFactor(): vec4
  • getBaseColorHex(): number
  • getDefaults(): Nullable<IMaterial>
  • getDoubleSided(): boolean
  • getEmissiveFactor(): vec3
  • getEmissiveHex(): number
  • getExtension<Prop>(name: string): Prop
  • getExtras(): Record<string, unknown>
  • getMetallicFactor(): number
  • getMetallicRoughnessTexture(): Texture
  • getName(): string
  • getNormalScale(): number
  • Normal (surface detail) texture.

    A tangent space normal map. The texture contains RGB components. Each texel represents the XYZ components of a normal vector in tangent space. Red [0 to 255] maps to X [-1 to 1]. Green [0 to 255] maps to Y [-1 to 1]. Blue [128 to 255] maps to Z [1/255 to 1]. The normal vectors use OpenGL conventions where +X is right and +Y is up. +Z points toward the viewer.

    Reference:

  • getOcclusionStrength(): number
  • (Ambient) Occlusion texture, generally used for subtle 'baked' shadowing effects that are independent of an object's position, such as shading in inset areas and corners. Direct lighting is not affected by occlusion, so at least one indirect light source must be present in the scene for occlusion effects to be visible.

    The occlusion values are sampled from the R channel. Higher values indicate areas that should receive full indirect lighting and lower values indicate no indirect lighting.

    Reference:

  • getRoughnessFactor(): number
  • init(): void
  • isDisposed(): boolean
  • Returns true if the node has been permanently removed from the graph.

  • listExtensions(): ExtensionProperty<IProperty>[]
  • listParents(): Property<IProperty>[]
  • Returns a list of all properties that hold a reference to this property. For example, a material may hold references to various textures, but a texture does not hold references to the materials that use it.

    It is often necessary to filter the results for a particular type: some resources, like Accessors, may be referenced by different types of properties. Most properties include the Root as a parent, which is usually not of interest.

    Usage:

    const materials = texture
        .listParents()
        .filter((p) => p instanceof Material)
    
  • setAlphaCutoff(alphaCutoff: number): Material
  • setBaseColorFactor(baseColorFactor: vec4): Material
  • setBaseColorHex(hex: number): Material
  • setDoubleSided(doubleSided: boolean): Material
  • setEmissiveFactor(emissiveFactor: vec3): Material
  • setExtension<Prop>(name: string, extensionProperty: Prop): Material
  • setExtras(extras: Record<string, unknown>): Material
  • setMetallicFactor(factor: number): Material
  • setNormalScale(scale: number): Material
  • setOcclusionStrength(strength: number): Material
  • setRoughnessFactor(factor: number): Material
Function symbol, f(📦) → 📦, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy TypeDoc documentation Copyright 2021 under MIT license