Material

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

Static properties

AlphaMode: Record<string, GLTF.MaterialAlphaMode>

Constants.

Properties

propertyType: PropertyType.MATERIAL

Methods

  • getAlpha(): number
  • getAlphaCutoff(): number
  • setAlphaCutoff(alphaCutoff: number): Material
  • getAlphaMode(): GLTF.MaterialAlphaMode

  • 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:

  • setAlphaMode(alphaMode: GLTF.MaterialAlphaMode): Material
  • getBaseColorFactor(): vec4
  • setBaseColorFactor(baseColorFactor: vec4): Material

  • Base color / albedo. The visible color of a non-metallic surface under constant ambient light would be a linear combination (multiplication) of its vertex colors, base color factor, and base color texture. Lighting, and reflections in metallic or smooth surfaces, also effect the final color. The alpha (.a) channel of base color factors and textures will have varying effects, based on the setting of getAlphaMode.

    Reference:

  • dispatchEvent(event: BaseEvent): this

  • Dispatches an event on the GraphNode, and on the associated Graph. Event types on the graph are prefixed, "node:[type]".

  • 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.

  • getDoubleSided(): boolean
  • setDoubleSided(doubleSided: boolean): Material
  • getEmissiveFactor(): vec3
  • setEmissiveFactor(emissiveFactor: vec3): Material

  • Emissive texture. Emissive color is added to any base color of the material, after any lighting/shadowing are applied. An emissive color does not inherently "glow", or affect objects around it at all. To create that effect, most viewers must also enable a post-processing effect called "bloom".

    Reference:

  • equals(other: Property, skip?: Set<string>): boolean

  • Returns true if two properties are deeply equivalent, recursively comparing the attributes of the properties. Optionally, a 'skip' set may be included, specifying attributes whose values should not be considered in the comparison.

    Example: Two Primitives are equivalent if they have accessors and materials with equivalent content — but not necessarily the same specific accessors and materials.

  • addEventListener(type: string, listener: EventListener<T>): this
  • removeEventListener(type: string, listener: EventListener<T>): this
  • getExtension(name: string): Prop | null
  • listExtensions(): ExtensionProperty[]
  • getExtras(): Record<string, unknown>

  • Returns a reference to the Extras object, containing application-specific data for this Property. Extras should be an Object, not a primitive value, for best portability.

  • setExtras(extras: Record<string, unknown>): Property

  • Updates the Extras object, containing application-specific data for this Property. Extras should be an Object, not a primitive value, for best portability.

  • isDisposed(): boolean

  • Returns true if the node has been permanently removed from the graph.

  • getMetallicFactor(): number
  • setMetallicFactor(factor: number): Material
  • getMetallicRoughnessTexture(): Texture
  • getName(): string

  • Returns the name of this property. While names are not required to be unique, this is encouraged, and non-unique names will be overwritten in some tools. For custom data about a property, prefer to use Extras.

  • Sets the name of this property. While names are not required to be unique, this is encouraged, and non-unique names will be overwritten in some tools. For custom data about a property, prefer to use Extras.

  • 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
  • setOcclusionStrength(strength: number): Material

  • (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:

  • listParents(): Property[]

  • 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)
  • getRoughnessFactor(): number
  • setRoughnessFactor(factor: number): Material
Function symbol, where the argument and output are a box labeled 'glTF'.

Made by Don McCurdy. Documentation built with greendoc and published under Creative Commons Attribution 3.0.