SurfaceMaterial


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:

  • diffuse scatters light evenly in every direction and provides the overall shading.

  • specular adds the tight highlight of a glossy surface.

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

Summary

Public companion functions

SurfaceMaterial
diffuse(color: Color)

Creates a SurfaceMaterial with the diffuse reflection component set to color.

Cmn
SurfaceMaterial
fresnel(
    reflectivity: @FloatRange(from = 0.0, to = 1.0) Float,
    intensity: @FloatRange(from = 0.0, to = 1.0) Float
)

Creates a SurfaceMaterial with the Fresnel grazing-angle component set to reflectivity and intensity.

Cmn
SurfaceMaterial
specular(
    color: Color,
    shininess: @FloatRange(from = 0.0, fromInclusive = false) Float
)

Creates a SurfaceMaterial with the specular highlight component set to color and shininess.

Cmn

Public companion properties

SurfaceMaterial

A SurfaceMaterial with all reflection components disabled.

Cmn

Public functions

SurfaceMaterial
diffuse(color: Color)

Returns a copy of this SurfaceMaterial with the diffuse reflection component set to color, leaving the other reflection components unchanged.

Cmn
open operator Boolean
equals(other: Any?)
Cmn
SurfaceMaterial
fresnel(
    reflectivity: @FloatRange(from = 0.0, to = 1.0) Float,
    intensity: @FloatRange(from = 0.0, to = 1.0) Float
)

Returns a copy of this SurfaceMaterial with the Fresnel grazing-angle component set to reflectivity and intensity, leaving the other reflection components unchanged.

Cmn
open Int
Cmn
SurfaceMaterial
specular(
    color: Color,
    shininess: @FloatRange(from = 0.0, fromInclusive = false) Float
)

Returns a copy of this SurfaceMaterial with the specular highlight component set to color and shininess, leaving the other reflection components unchanged.

Cmn
open String
Cmn

Public companion functions

diffuse

fun diffuse(color: Color): SurfaceMaterial

Creates a SurfaceMaterial with the diffuse reflection component set to color.

Parameters
color: 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.

See also
diffuse

fresnel

fun fresnel(
    reflectivity: @FloatRange(from = 0.0, to = 1.0) Float,
    intensity: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): SurfaceMaterial

Creates a SurfaceMaterial with the Fresnel grazing-angle component set to reflectivity and intensity.

Parameters
reflectivity: @FloatRange(from = 0.0, to = 1.0) Float

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: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

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

See also
fresnel

specular

fun specular(
    color: Color,
    shininess: @FloatRange(from = 0.0, fromInclusive = false) Float
): SurfaceMaterial

Creates a SurfaceMaterial with the specular highlight component set to color and shininess.

Parameters
color: Color

the color of the highlight. It is multiplied by the color and intensity of each light.

shininess: @FloatRange(from = 0.0, fromInclusive = false) Float

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.

See also
specular

Public companion properties

None

val None: SurfaceMaterial

A SurfaceMaterial with all reflection components disabled.

Public functions

diffuse

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

equals

open operator fun equals(other: Any?): Boolean

fresnel

fun fresnel(
    reflectivity: @FloatRange(from = 0.0, to = 1.0) Float,
    intensity: @FloatRange(from = 0.0, to = 1.0) 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: @FloatRange(from = 0.0, to = 1.0) Float

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: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

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

hashCode

open fun hashCode(): Int

specular

fun specular(
    color: Color,
    shininess: @FloatRange(from = 0.0, fromInclusive = false) 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: 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: @FloatRange(from = 0.0, fromInclusive = false) Float

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.

toString

open fun toString(): String