user: Describe Materials from the Blender manual or Python API, including usage steps and snippets.

assistant: The core material system in glTF supports a metal/rough PBR workflow
with the following channels of information:

- Base Color
- Metallic
- Roughness
- Baked Ambient Occlusion
- Normal Map (tangent space, +Y up)
- Emissive

Some additional material properties or types of materials can be expressed using glTF extensions.
The complete list can be found in [Extensions](#extensions) part of this documentation.

[image reference removed]

An example of the various image maps available in the glTF 2.0 core format. This is
the [water bottle sample model](https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0/WaterBottle)
shown alongside slices of its various image maps.

### Imported Materials

The glTF material system is different from Blender’s own materials. When a glTF file is imported,
the add-on will construct a set of Blender nodes to replicate each glTF material as closely as possible.

The importer supports Metal/Rough PBR (core glTF), Spec/Gloss PBR (`KHR_materials_pbrSpecularGlossiness`)
and some extension materials. The complete list can be found in [Extensions](#extensions) part of this documentation.

### Exported Materials

The exporter supports Metal/Rough PBR (core glTF) and Shadeless (`KHR_materials_unlit`) materials.
It will construct a glTF material based on the nodes it recognizes in the Blender material.
The material export process handles the settings described below.

#### Base Color

The glTF base color is determined by looking for a Base Color input on a Principled BSDF node.
If the input is unconnected, the input’s default color (the color field next to the unconnected socket)
is used as the Base Color for the glTF material.

[image reference removed]

A solid base color can be specified directly on the node.

If an Image Texture node is found to be connected to the Base Color input,
that image will be used as the glTF base color.

[image reference removed]

An image is used as the glTF base color.

If no texture is connected, the base color can be specified:

- From the Principled BSDF node’s *Base Color* input, which is the default.
- From a RGB node connected to the *Base Color* input.
- From an Ambiant Occlusion node connected to the *Base Color* input. (The AO socket
  is not used in glTF, but the color output can be used as a base color.)

[image reference removed]

#### Metallic and Roughness

These values are read from the Principled BSDF node. If both of these inputs are unconnected,
the node will display sliders to control their respective values between 0.0 and 1.0,
and these values will be copied into the glTF.

When using an image, glTF expects the metallic values to be encoded in the blue (`B`) channel,
and roughness to be encoded in the green (`G`) channel of the same image.
If images are connected to the Blender node in a manner that does not follow this convention,
the add-on may attempt to adapt the image to the correct form during exporting (with an increased export time).

In the Blender node tree, it is recommended to use a Separate RGB node
to separate the channels from an Image Texture node, and
connect the green (`G`) channel to Roughness, and blue (`B`) to Metallic.
The glTF exporter will recognize this arrangement as matching the glTF standard, and
that will allow it to simply copy the image texture into the glTF file during export.

The Image Texture node for this should have its *Color Space* set to Non-Color.

[image reference removed]

A metallic/roughness image connected in a manner consistent with the glTF standard,
allowing it to be used verbatim inside an exported glTF file.

#### Baked Ambient Occlusion

glTF is capable of storing a baked ambient occlusion map.
Currently there is no arrangement of nodes that causes Blender
to use such a map in exactly the same way as intended in glTF.
However, if the exporter finds a custom node group by the name of `glTF Material Output`, and
finds an input named `Occlusion` on that node group,
it will look for an Image Texture attached there to use as the occlusion map in glTF.
The effect need not be shown in Blender, as Blender has other ways of showing ambient occlusion,
but this method will allow the exporter to write an occlusion image to the glTF.
This can be useful to real-time glTF viewers, particularly on platforms where there
may not be spare power for computing such things at render time.

[image reference removed]

A pre-baked ambient occlusion map, connected to a node that doesn’t render but will export to glTF.

glTF stores occlusion in the red (`R`) channel, allowing it to optionally share
the same image with the roughness and metallic channels.

[image reference removed]

This combination of nodes mimics the way glTF packs occlusion, roughness, and
metallic values into a single image.

#### Normal Map

To use a normal map in glTF, connect an Image Texture node’s color output
to a Normal Map node’s color input, and then connect the Normal Map normal output to
the Principled BSDF node’s normal input. The Image Texture node
for this should have its *Color Space* property set to Non-Color.

The Normal Map node must remain on its default property of Tangent Space as
this is the only type of normal map currently supported by glTF.
The strength of the normal map can be adjusted on this node.
The exporter is not exporting these nodes directly, but will use them to locate
the correct image and will copy the strength setting into the glTF.

[image reference removed]

A normal map image connected such that the exporter will find it and copy it
to the glTF file.

#### Emissive

An Image Texture node can be connected to the Emission input on the Principled BSDF node
to include an emissive map with the glTF material. Alternatively, the Image Texture node
can be connected to an Emission shader node, and optionally combined with properties
from a Principled BSDF node by way of an Add Shader node.

If the emissive map is alone in the material, it is best to set the Base Color default
to black, and the Roughness default to 1.0. This minimizes the influence of the other
channels if they are not needed.

[image reference removed]

This arrangement is supported for backwards compatibility. It is simpler to use
the Principled BSDF node directly.

If any component of emissiveFactor is > 1.0, `KHR_materials_emissive_strength` extension will be used.

#### Clearcoat

When the *Clearcoat* input on the Principled BSDF node has a nonzero default value or
Image Texture node connected, the `KHR_materials_clearcoat` glTF extension will be
included in the export. This extension will also include a value or Image Texture
from the *Clearcoat Roughness* input if available.

If Image Textures are used, glTF requires that the clearcoat values be written to
the red (`R`) channel, and *Clearcoat Roughness* to the green (`G`) channel.
If monochrome images are connected, the exporter will remap them to these color channels.

The *Clearcoat Normal* input accepts the same kinds of inputs as the base Normal input,
specifically a tangent-space normal map with +Y up, and a user-defined strength.
This input can reuse the same normal map that the base material is using,
or can be assigned its own normal map, or can be left disconnected for a smooth coating.

All Image Texture nodes used for clearcoat shading should have their *Color Space* set to Non-Color.

[image reference removed]

An example of a complex clearcoat application that will export correctly to glTF.
A much simpler, smooth coating can be applied from just the Principled BSDF node alone.

#### Sheen

If a Sheen Roughness Texture is used, glTF requires the values be written to the alpha (`A`) channel.

[image reference removed]

#### Specular

When the *Specular IOR Level* or *Specular Tint* input of Principled BSDF node have a non default value or
Image Texture node connected, the `KHR_materials_specular` glTF extension will be
included in the export.

#### Anisotropy

Anisotropic textures and data need to be converted at export, and at import.

At import, some nodes are created to manage this conversion

[image reference removed]

At export, this exact same nodes are detected, and used to export data.

At export, you can also plug some grayscale textures for *Anisotropic* and *Anisotropic Rotation* sockets.
Then, exporter will convert these texture into a glTF compatible texture.

[image reference removed]

Note that the *tangent* socket must be linked to a *tangent* node, with UVMap.
The choosen UVMap must be the UVMap of the Normal Map.

#### Transmission

When the Transmission input on the Principled BSDF node has a nonzero default value or
Image Texture node connected, the `KHR_materials_transmission` glTF extension will be
included in the export. When a texture is used, glTF stores the values in the red (`R`) channel.
The *Color Space* should be set to Non-Color.

Transmission is different from alpha blending, because transmission allows full-strength specular reflections.
In glTF, alpha blending is intended to represent physical materials that are partially missing from
the specified geometry, such as medical gauze wrap. Transmission is intended to represent physical materials
that are solid but allow non-specularly-reflected light to transmit through the material, like glass.

#### IOR

At import, there are two different situation:

- if `KHR_materials_ior` is not set, IOR value of Principled BSDF node is set to 1.5,
  that is the glTF default value of IOR.
- If set, the `KHR_materials_ior` is used to set the IOR value of Principled BSDF.

At export, IOR is included in the export only if one of these extensions are also used:

- `KHR_materials_transmission`
- `KHR_materials_volume`
- `KHR_materials_specular`

IOR of 1.5 are not included in the export, because this is the default glTF IOR value.

#### Volume

Volume can be exported using a Volume Absorption node, linked to Volume socket of Output node.
Data will be exported using the `KHR_materials_volume` extension.

- For volume to be exported, some *transmission* must be set on Principled BSDF node.
- Color of Volume Absorption node is used as glTF attenuation color. No texture is allowed for this property.
- Density of Volume Absorption node is used as inverse of glTF attenuation distance.
- Thickness can be plugged into the Thickness socket of custom group node `glTF Material Output`.
- If a texture is used for thickness, it must be plugged on (`G`) Green channel of the image.

[image reference removed]

#### glTF Variants

There are two location to manage glTF Variants in Blender

- In 3D View, on `glTF Variants` tab
- For advanced settings, in Mesh Material Properties (see Advanced glTF Variant checks)

The main concept to understand for using Variants,
is that each material slot will be used as equivalent of a glTF primitive.

#### glTF Variants switching

After importing a glTF file including `KHR_materials_variants` extension, all variants can be displayed.

[image reference removed]

You can switch Variant, by *selecting* the variant you want to display, then clicking on *Display Variant*.

You can switch to default materials (when no Variant are used), by clicking on *Reset to default*.

#### glTF Variants creation

You can add a new Variant by clicking  at right of the Variant list.
Then you can change the name by double-clicking.

After changing Materials in Material Slots, you can assign current materials to the active Variant using
*Assign to Variant*.

You can also set default materials using *Assign as Original*.
These materials will be exported as default material in glTF.
This are materials that will be displayed by any viewer that don’t manage `KHR_materials_variants` extension.

#### Advanced glTF Variant checks

If you want to check primitive by primitive, what are Variants used, you can go to Mesh Material Properties.

[image reference removed]

The *glTF Material Variants* tab refers to the active material Slot and Material used by this slot.
You can see every Variants that are using this material for the given Slot/Primitive.

You can also assign material to Variants from this tab, but recommendation is to perform it from 3D View tab.

#### Double-Sided / Backface Culling

For materials where only the front faces will be visible, turn on *Backface Culling* in
the *Settings* panel of an EEVEE material. When using other engines (Cycles, Workbench)
you can temporarily switch to EEVEE to configure this setting, then switch back.

Leave this box unchecked for double-sided materials.

[image reference removed]

The inverse of this setting controls glTF’s `DoubleSided` flag.

#### Alpha Modes

glTF has three alpha modes, depending on whether the alpha value is always 1, always 0 or
1, or can be between 0 and 1. The exporter determines the alpha mode automatically from
the nodes connected to the Alpha socket.

Opaque
:   > In *opaque mode*, the material alpha is always 1.

    [image reference removed]

Mask
:   In *mask mode*, the material alpha is always 0 or 1. This creates “cutout”
    transparency, where there is a hard edge between opaque and transparent regions, and
    can be used for things like leaves or cloth with holes. To enable this mode, use a Math
    node to round the alpha value to either 0 or 1.

    [image reference removed]

    Rounding snaps alpha values that are 0.5 or greater up to 1, and ones below 0.5 down to
    1. It is also possible to use a cutoff value different than 0.5 by using Math nodes to
    do `1 - (alpha < cutoff)`.

    Mask mode is essentially the same as EEVEE’s “Alpha Clip” blend mode, but is done with
    shader nodes so it works in other render engines.

Blend
:   Materials that use neither of these will use *blend mode*. Blend mode allows partially
    transparent surfaces that tint the objects seen through them, like layers of colored
    film. However, partial transparency is complex to render, and glTF viewers may show
    visual artifacts in non-trivial scenes that use blend mode.

    To avoid artifacts, it may be a good idea to separate out parts of a model that can use
    opaque or mask mode, and use blend mode only on the parts where it is necessary, or to
    use only a *single* layer of transparent polygons in front of opaque objects.

#### UV Mapping

Control over UV map selection and transformations is available by connecting a UV Map node
and a Mapping node to any Image Texture node.

Settings from the Mapping node are exported using a glTF extension named `KHR_texture_transform`.
There is a mapping type selector across the top. *Point* is the recommended type for export.
*Texture* and *Vector* are also supported. The supported offsets are:

- *Location* - X and Y
- *Rotation* - Z only
- *Scale* - X and Y

For the *Texture* type, *Scale* X and Y must be equal (uniform scaling).

[image reference removed]

A deliberate choice of UV mapping.

#### Factors

Any Image Texture nodes may optionally be multiplied with a constant color or scalar.
These will be written as factors in the glTF file, which are numbers that are multiplied
with the specified image textures. These are not common.

- Use Math node (multiply) for scalar factors. Use second value as factor
- Use Mix node (color / multiply) for color factors. Set Factor to 1, and use Color2 (B) as factors

[image reference removed]

#### Example

A single material may use all of the above at the same time, if desired. This figure shows
a typical node structure when several of the above options are applied at once:

[image reference removed]

A Principled BSDF material with an emissive texture.

#### UDIM

UDIM is a way to store multiple textures in a single image file.
The UDIM system is supported by Blender, but is not supported by glTF.
When exporting a model that uses UDIM, the add-on will automatically split the
image into multiple images, one for each tile, and will update the material
nodes to use the new images.
All UDIM texture must use the same UV map to be exported.

### Exporting a Shadeless (Unlit) Material

To export an unlit material, mix in a camera ray, and avoid using the Principled BSDF node.

[image reference removed]

One of several similar node arrangements that will export
`KHR_materials_unlit` and render shadeless in Blender.