# SurfaceGeometrySpec

> Describes the virtual three-dimensional shape that a lit surface is treated as having.

## API Reference

> Source set: Common

```kotlin
public sealed class SurfaceGeometrySpec
```

Describes the virtual three-dimensional shape that a lit surface is treated as having.

A spec is resolution independent. It is resolved into concrete geometry once the surface's size,
layout direction and density are known, so a single spec can be shared between surfaces of
different sizes.

Lighting is currently implemented only for rectangles, and for rounded rectangles whose corners
each have a circular radius (`x == y`). Any other shape, including `CutCornerShape`,
`GenericShape`, and rounded rectangles with elliptical corner radii, throws an
`IllegalArgumentException` when the spec is resolved.

## Members

### Companion

> Source set: Common

```kotlin
public companion object
```

## Functions

### flat

> Source set: Common

```kotlin
public fun flat(shape: Shape, thickness: Dp): SurfaceGeometrySpec
```

A surface whose interior is flat and faces the viewer directly.

Every interior pixel shares the same normal, so the interior takes a single even shade
This reads as a sheet of material rather than as a solid object, and
`SurfaceMaterial.fresnel` adds an even brightening instead of a rim.

#### Parameters

| | |
| --- | --- |
| shape | outline of the lit surface. See the class documentation for the shapes that are supported. |
| thickness | height of the surface towards the viewer. The attenuation of the light is calculated based on the resultant distance `lightElevation - surfaceThickness`. |

#### Throws: IllegalArgumentException

if [thickness](https://composables.com/jetpack-compose/androidx.glance/glance-wear-tiles/functions/thickness/api.md) is `Dp.Unspecified`.

### convex

> Source set: Common

```kotlin
public fun convex(shape: Shape, thickness: Dp, bevelWidth: Dp): SurfaceGeometrySpec
```

A surface that bulges towards the viewer, like a dome.

The interior is flat and the outline is wrapped in a curved band whose width is
determined by `bevelWidth`. The normals tilt outwards, away from the center of the
surface. The curved surface catches a highlight on the side facing a light and falls into
shadow on the opposite side, giving the surface a rounded, physical edge.

#### Parameters

| | |
| --- | --- |
| shape | outline of the lit surface. See the class documentation for the shapes that are supported. |
| thickness | height of the surface towards the viewer. The attenuation of the light is calculated based on the resultant distance `lightElevation - surfaceThickness`. The thickness is considered uniform over the surface. |
| bevelWidth | width of the curved band along the outline. Clamped to half of the surface's smaller dimension when resolved. |

#### Throws: IllegalArgumentException

if [thickness](https://composables.com/jetpack-compose/androidx.glance/glance-wear-tiles/functions/thickness/api.md) or `bevelWidth` is `Dp.Unspecified` or `bevelWidth` is negative.

### concave

> Source set: Common

```kotlin
public fun concave(shape: Shape, thickness: Dp, bevelWidth: Dp): SurfaceGeometrySpec
```

A surface that dishes away from the viewer, like a bowl.

The interior is flat and the outline is wrapped in a curved band whose width is
determined by `bevelWidth`. The normals tilt inwards, towards the center of the surface.
The curved surface falls into shadow on the side facing a light and illuminates on the
opposite side, giving the surface a depressed shade.

#### Parameters

| | |
| --- | --- |
| shape | outline of the lit surface. See the class documentation for the shapes that are supported. |
| thickness | height of the surface towards the viewer. The attenuation of the light is calculated based on the resultant distance `lightElevation - surfaceThickness`. The thickness is considered uniform over the surface. |
| bevelWidth | width of the curved band along the outline. Clamped to half of the surface's smaller dimension when resolved. |

#### Throws: IllegalArgumentException

if [thickness](https://composables.com/jetpack-compose/androidx.glance/glance-wear-tiles/functions/thickness/api.md) or `bevelWidth` is `Dp.Unspecified` or `bevelWidth` is negative.
