# SurfaceMaterial

> Describes how a surface reflects the light that reaches it.

## API Reference

> Source set: Common

```kotlin
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

```kotlin
public fun diffuse(color: Color): SurfaceMaterial
```

Returns a copy of this [SurfaceMaterial](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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

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

Returns a copy of this [SurfaceMaterial](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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

```kotlin
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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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

```kotlin
override fun equals(other: Any?): Boolean
```

### hashCode

> Source set: Common

```kotlin
override fun hashCode(): Int
```

### toString

> Source set: Common

```kotlin
override fun toString(): String
```

## Members

### Companion

> Source set: Common

```kotlin
public companion object
```

## Properties

### None

> Source set: Common

```kotlin
public val None: SurfaceMaterial = SurfaceMaterial()
```

A [SurfaceMaterial](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) with all reflection components disabled.

## Functions

### diffuse

> Source set: Common

```kotlin
public fun diffuse(color: Color): SurfaceMaterial
```

Creates a [SurfaceMaterial](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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

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

Creates a [SurfaceMaterial](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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

```kotlin
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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceMaterial/api.md) 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]`.
