Class

SurfaceMaterial

Describes how a surface reflects the light that reaches it.

Source set: Common
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:

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

Functions

diffuse

Source set: Common
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

Source set: Common
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

Source set: Common
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

Source set: Common
override fun equals(other: Any?): Boolean

hashCode

Source set: Common
override fun hashCode(): Int

toString

Source set: Common
override fun toString(): String

Members

Companion

Source set: Common
public companion object

Properties

None

Source set: Common
public val None: SurfaceMaterial = SurfaceMaterial()

A SurfaceMaterial with all reflection components disabled.

Functions

diffuse

Source set: Common
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

Source set: Common
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

Source set: Common
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].

Jetpack Compose beyond MaterialFree components, screens and templates for apps that don’t look like Google’s. Copy them into your app, or let your coding agent add them.Browse for free

Content updated: