> Documentation index: https://developer.android.com/reference/llms.txt

# SurfaceMaterial

Artifact: [androidx.compose.ui:ui](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/lighting/SurfaceMaterial.kt+class:androidx.compose.ui.lighting.SurfaceMaterial) Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01) Common/All
- Cmn

  ```
  class 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` | `None` 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` | `hashCode()` | 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` | `toString()` | Cmn |

## Public companion functions

### diffuse

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

```
val None: SurfaceMaterial
```

A `SurfaceMaterial` with all reflection components disabled.

## Public functions

### diffuse

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn

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

### fresnel

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn

```
open fun hashCode(): Int
```

### specular

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn

```
open fun toString(): String
```