diff --git a/docs/Materials.md.html b/docs/Materials.md.html
index fcae1296e2..e5c5cf78d2 100644
--- a/docs/Materials.md.html
+++ b/docs/Materials.md.html
@@ -89,10 +89,11 @@ in table [standardProperties].
**clearCoatNormal** | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
**emissive** | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
**postLightingColor** | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
+**ior** | Index of refraction for refractive objects
**transmission** | Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is
**absorption** | Absorption factor for refractive objects
-**ior** | Index of refraction for refractive objects
**microThickness** | Thickness of the thin layer of refractive objects
+**thickness** | Thickness of the solid volume of refractive objects
[Table [standardProperties]: Properties of the standard model]
The type and range of each property is described in table [standardPropertiesTypes].
@@ -112,10 +113,11 @@ The type and range of each property is described in table [standardPropertiesTyp
**clearCoatNormal** | float3 | [0..1] | Linear RGB, encodes a direction vector in tangent space
**emissive** | float4 | rgb=[0..1], a=[-n..n] | Alpha is the exposure compensation
**postLightingColor** | float4 | [0..1] | Pre-multiplied linear RGB
+**ior** | float | [1..n] | Optional, usually deduced from the reflectance
**transmission** | float | [0..1] |
**absorption** | float3 | [0..n] |
-**ior** | float | [1..n] | Optional, usually deduced from the reflectance
**microThickness** | float | [0..n] |
+**thickness** | float | [0..n] |
[Table [standardPropertiesTypes]: Range and type of the standard model's properties]
@@ -146,10 +148,10 @@ The type and range of each property is described in table [standardPropertiesTyp
!!! Note: About thickness and microThickness for refraction
`thickness` represents the thickness of solid objects in the direction of the normal, for
satisfactory results, this should be provided per fragment (e.g.: as a texture) or at least per
- vertex. `microThickness` represent the thickness of the thin layer of an object, and can
+ vertex. `microThickness` represent the thickness of the thin layer of an object, and can
generally be provided as a constant value. For example, a 1mm thin hollow sphere of radius 1m,
would have a `thickness` of 1 and a `microThickness` of 0.001. Currently `thickness` is not
- used when `refractionType` is set to "thin".
+ used when `refractionType` is set to `thin`.
### Base color
@@ -236,10 +238,10 @@ The effect of `roughness` on metallic surfaces is shown in figure [roughnessCond
### Reflectance
The `reflectance` property only affects non-metallic surfaces. This property can be used to control
-the specular intensity. This value is defined between 0 and 1 and represents a remapping of a
-percentage of reflectance. For instance, the default value of 0.5 corresponds to a reflectance of
-4%. Values below 0.35 (2% reflectance) should be avoided as no real-world materials have such
-low reflectance.
+the specular intensity and index of refraction of materials. This value is defined
+between 0 and 1 and represents a remapping of a percentage of reflectance. For instance, the
+default value of 0.5 corresponds to a reflectance of 4%. Values below 0.35 (2% reflectance) should
+be avoided as no real-world materials have such low reflectance.
The effect of `reflectance` on non-metallic surfaces is shown in figure [reflectanceProperty]
(click on the image to see a larger version).
@@ -270,6 +272,18 @@ Teeth | 5.8% | 1.63 | 0.6
Default value | 4% | 1.5 | 0.5
[Table [commonMatReflectance]: Reflectance of common materials]
+Note that the `reflectance` property also defines the index of refraction of the surface.
+When this property is defined it is not necessary to define the `ior` property. Setting
+either of these properties will automatically compute the other property. It is possible
+to specify both, in which case their values are kept as-is, which can lead to physically
+impossible materials, however, this might be desirable for artistic reasons.
+
+The `reflectance` property is designed as a normalized property in the range 0..1 which makes
+it easy to define from a texture.
+
+See the Index of refraction section for more information about the `ior` property and refractive
+indices.
+
### Clear coat
Multi-layer materials are fairly common, particularly materials with a thin translucent
@@ -421,6 +435,85 @@ this option for more information.
`postLightingColor` can be used as a simpler `emissive` property by setting
`postLightingBlending` to `add` and by providing an RGB color with alpha set to `0.0`.
+### Index of refraction
+
+The `ior` property only affects non-metallic surfaces. This property can be used to control the
+index of refraction and the specular intensity of materials. The `ior` property is intended to
+be used with refractive (transmissive) materials, which are enabled when the `refractionMode` is
+set to `cubemap` or `screenspace`.
+
+The index of refraction (or refractive index) of a material is a dimensionless number that describes
+how fast light travels through that material. The higher the number, the slower light travels
+through the medium. More importantly for rendering materials, the refractive index determines how
+the path light travels is bent when entering the material. Higher indices of refraction will cause
+light to bend further away from the initial path.
+
+Table [commonMatIOR] describes acceptable refractive indices for various types of materials.
+
+Material | IOR
+--------------------------:|:-----------------
+Air | 1.0
+Water | 1.33
+Common liquids | 1.33 to 1.5
+Common gemstones | 1.58 to 2.33
+Plastics, glass | 1.5 to 1.58
+Other dielectric materials | 1.33 to 1.58
+[Table [commonMatIOR]: Index of refraction of common materials]
+
+The appearance of a refractive material will greatly depend on the `refractionType` and
+`refractionMode` settings of the material. Refer to the Blending and transparency: refractionType
+section and the Blending and transparency: refractionMode section for more information.
+
+The effect of `ior` when `refractionMode` is set to `cubemap` and `refractionType` is set to `solid`
+can be seen in figure [iorProperty2] (click on the image to see a larger version).
+
+![Figure [iorProperty2]: `transmission` varying from 1.0
+(left) to 1.5 (right)](images/materials/ior.png)
+
+Figure [iorProperty] shows the comparison of a sphere of `ior` 1.0 with a sphere of `ior` 1.33, with
+the `refractionMode` set to `screenspace` and the `refractionType` set to `solid`
+(click on the image to see a larger version).
+
+![Figure [iorProperty]: `ior` of 1.0 (left) and 1.33 (right)](images/material_ior.png)
+
+Note that the `ior` property also defines the reflectance (or specular intensity) of the surface.
+When this property is defined it is not necessary to define the `reflectance` property. Setting
+either of these properties will automatically compute the other property. It is possible to specify
+both, in which case their values are kept as-is, which can lead to physically impossible materials,
+however, this might be desirable for artistic reasons.
+
+See the Reflectance section for more information on the `reflectance` property.
+
+!!! Tip
+ Refractive materials are affected by the `roughness` property. Rough materials will scatter
+ light, creating a diffusion effect useful to recreate "blurry" appearances such as frosted
+ glass, certain plastics, etc.
+
+### Transmission
+
+The `transmission` property defines what ratio of diffuse light is transmitted through a refractive
+material. This property only affects materials with a `refractionMode` set to `cubemap` or
+`screenspace`.
+
+When `transmission` is set to 0, no amount of light is transmitted and the diffuse component of
+the surface is 100% visible. When `transmission` is set to 1, all the light is transmitted and the
+diffuse component is not visible anymore, only the specular component is.
+
+The effect of `transmission` on a glossy dielectric (`ior` of 1.5, `refractionMode` set to
+`cubemap`, `refractionType` set to `solid`) is shown in figure [transmissionProperty]
+(click on the image to see a larger version).
+
+![Figure [transmissionProperty]: `transmission` varying from 0.0
+(left) to 1.0 (right)](images/materials/transmission.png)
+
+!!! Tip
+ The `transmission` property is useful to create decals, paint, etc. at the surface of refractive
+ materials.
+
+### Absorption
+
+### Micro-thickness and thickness
+
## Subsurface model
### Thickness
diff --git a/docs/images/material_ior.png b/docs/images/material_ior.png
new file mode 100644
index 0000000000..9975273821
Binary files /dev/null and b/docs/images/material_ior.png differ
diff --git a/docs/images/materials/ior.png b/docs/images/materials/ior.png
new file mode 100644
index 0000000000..e1b8ced8d9
Binary files /dev/null and b/docs/images/materials/ior.png differ
diff --git a/docs/images/materials/transmission.png b/docs/images/materials/transmission.png
new file mode 100644
index 0000000000..88d9a036f7
Binary files /dev/null and b/docs/images/materials/transmission.png differ
diff --git a/samples/frame_generator.cpp b/samples/frame_generator.cpp
index d454b41755..664c0f6807 100644
--- a/samples/frame_generator.cpp
+++ b/samples/frame_generator.cpp
@@ -348,7 +348,7 @@ static LinearImage toLinear(size_t w, size_t h, size_t bpr, const uint8_t* src)
for (size_t x = 0; x < w; ++x, p += 3) {
filament::math::float3 sRGB(p[0], p[1], p[2]);
sRGB /= std::numeric_limits::max();
- *d++ = sRGB;
+ *d++ = sRGBToLinear(sRGB);
}
}
return result;