public class SurfaceMaterial internal constructor(
internal val diffuseColor: Color = Color.Unspecified,
internal val specularColor: Color = Color.Unspecified,
internal val specularShininess: Float = 1f,
internal val fresnelReflectivity: Float = 0f,
internal val fresnelIntensity: Float = 0f,
)
Describes how a surface reflects the light that reaches it.
A material has three independent reflection components that are evaluated for every light illuminating the surface and summed:
diffusescatters light evenly in every direction and provides the overall shading.specularadds the tight highlight of a glossy surface.fresnelbrightens the surface where it is viewed at a grazing angle.
The diffuse and specular components are calculated as per the Blinn-Phong reflection model. The fresnel component is calculated using Schlick's approximation.
Any component that is not set is disabled and contributes nothing to the lighting, so SurfaceMaterial.None has all reflection components disabled and renders no lighting at all. Set at least diffuse to see a result.
Functions
diffuse
public fun diffuse(color: Color): SurfaceMaterial
Returns a copy of this SurfaceMaterial with the diffuse reflection component set to color, leaving the other reflection components unchanged.
Diffuse reflection scatters light equally in every direction, so its contribution depends only on the angle between the surface normal and the light and is independent of the angle it is viewed from. This is what gives a lit surface its overall sense of shape.
Parameters
| color | the color the surface reflects. It is multiplied by the color and intensity of each light, so a white surface takes on the color of the light while a red surface only reflects the red it receives. Pass Color.Unspecified to disable diffuse reflection. |
specular
public fun specular(
color: Color,
@FloatRange(from = 0.0, fromInclusive = false) shininess: Float,
): SurfaceMaterial
Returns a copy of this SurfaceMaterial with the specular highlight component set to color and shininess, leaving the other reflection components unchanged.
Specular reflection is the bright highlight that appears where a glossy surface reflects a light back towards the viewer. Unlike diffuse, it moves as the surface tilts and can be used to give the surface a polished or glossy look.
Parameters
| color | the color of the highlight. It is multiplied by the color and intensity of each light. Pass Color.Unspecified to disable specular reflection. |
| shininess | the specular exponent. Larger values concentrate the highlight into a smaller, sharper spot; smaller values spread it into a broad highlight. Must be positive. |
Throws: IllegalArgumentException
if shininess is not positive.
fresnel
public fun fresnel(
@FloatRange(from = 0.0, to = 1.0) reflectivity: Float,
@FloatRange(from = 0.0, to = 1.0) intensity: Float = 1.0f,
): SurfaceMaterial
Returns a copy of this SurfaceMaterial with the Fresnel grazing-angle component set to reflectivity and intensity, leaving the other reflection components unchanged.
Real surfaces become more reflective the closer to edge-on they are viewed, which looks like a rim of light around the curved parts of a surface. The term is estimated with Schlick's approximation and added on top of diffuse and specular.
The rim needs geometry that curves away from the viewer, such as SurfaceGeometrySpec.convex. On a surface built with SurfaceGeometrySpec.flat the interior normals all face the viewer directly, so the grazing angle term vanishes and only the head-on reflectivity is left, which only brightens the surface with no rim.
Parameters
| reflectivity | reflectance when the surface is viewed head-on. 0.04 is representative of common non-metals such as plastic or glass; polished metals are closer to 1. A value of 0 disables the Fresnel contribution. Expected to be in the range 0..1. |
| intensity | multiplier applied to the Fresnel contribution. Use it to strengthen or soften the rim without changing the physical reflectance. A value of 0 disables the Fresnel contribution. Expected to be in the range 0..1. |
Throws: IllegalArgumentException
if reflectivity or intensity is not in [0, 1].
equals
override fun equals(other: Any?): Boolean
hashCode
override fun hashCode(): Int
toString
override fun toString(): String
Members
Companion
public companion object
Properties
None
public val None: SurfaceMaterial = SurfaceMaterial()
A SurfaceMaterial with all reflection components disabled.
Functions
diffuse
public fun diffuse(color: Color): SurfaceMaterial
Creates a SurfaceMaterial with the diffuse reflection component set to color.
Parameters
| color | the color the surface reflects. It is multiplied by the color and intensity of each light, so a white surface takes on the color of the light while a red surface only reflects the red it receives. |
specular
public fun specular(
color: Color,
@FloatRange(from = 0.0, fromInclusive = false) shininess: Float,
): SurfaceMaterial
Creates a SurfaceMaterial with the specular highlight component set to color and shininess.
Parameters
| color | the color of the highlight. It is multiplied by the color and intensity of each light. |
| shininess | the specular exponent. Larger values concentrate the highlight into a smaller, sharper spot; smaller values spread it into a broad highlight. Must be positive. |
Throws: IllegalArgumentException
if shininess is not positive.
fresnel
public fun fresnel(
@FloatRange(from = 0.0, to = 1.0) reflectivity: Float,
@FloatRange(from = 0.0, to = 1.0) intensity: Float = 1.0f,
): SurfaceMaterial
Creates a SurfaceMaterial with the Fresnel grazing-angle component set to reflectivity and intensity.
Parameters
| reflectivity | reflectance when the surface is viewed head-on. 0.04 is representative of common non-metals such as plastic or glass; polished metals are closer to 1. A value of 0 disables the Fresnel contribution. Expected to be in the range 0..1. |
| intensity | multiplier applied to the Fresnel contribution. Use it to strengthen or soften the rim without changing the physical reflectance. A value of 0 disables the Fresnel contribution. Expected to be in the range 0..1. |
Throws: IllegalArgumentException
if reflectivity or intensity is not in [0, 1].