# Draw the Ambient Mesh

> Paint a title's Ambient Mesh in CSS from the colours in its detail response.

Show, Movie, Collection and Game details include an `ambientMesh`: a soft colour wash taken
from the title's Backdrop. It sits inside that image, at `metadataImages.backdrop.ambientMesh`
(`metadataImages.background.ambientMesh` for a Game), because it is derived from that image. The Mediux website paints it behind each
title page. You can paint the same wash in your app with plain CSS: no image request,
no canvas and no library.

`ambientMesh` is `null` when the Backdrop has no mesh yet, and `backdrop` itself is `null` when
the title has no hosted Backdrop, so use optional chaining and keep a plain background as the
fallback.

## What the response holds

```json
"backdrop": {
  "id": "…",
  "extension": "jpg",
  "ambientMesh": {
    "base": "#015f66",
    "grid": [
      ["#2f4832", "#334c32", "#345135", "#32553b", "#31593d", "#325b3e", "#375c3b", "#3c5b38"],
      ["#30472f", "#354b30", "#365033", "#355439", "#33593d", "#315c40", "#325d41", "#325e40"],
      ["#31452d", "#34482d", "#374d30", "#375335", "#35573a", "#315c40", "#2d5e44", "#295f48"],
      ["#2c412a", "#2f4329", "#32472d", "#334d32", "#31553a", "#2d5b42", "#275e49", "#1f604f"],
      ["#253e29", "#283e28", "#2a412a", "#2b4830", "#2a5039", "#265a45", "#205e4e", "#196054"]
    ]
  },
  "accent": { "color": "#68867b" }
}
```

- `base` is the dominant colour. Paint it underneath everything.
- `grid` is 5 rows of 8 colours, top row first and left to right in each row. Each colour
  is the wash at the centre of its cell, laid over the Backdrop's 16:9 frame.
- `accent` sits beside `ambientMesh` and is a single colour picked from the same Backdrop, for
  buttons, links or highlights.

## How it is drawn

Each grid row becomes one horizontal gradient with a colour stop at every column
centre. The five rows are stacked, and each row below the first fades in from the
previous row's centre to its own. That blends the colours smoothly in both directions,
which is how the website renders it.

| Column | 1     | 2      | 3      | 4      | 5      | 6      | 7      | 8      |
| ------ | ----- | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
| Stop   | 6.25% | 18.75% | 31.25% | 43.75% | 56.25% | 68.75% | 81.25% | 93.75% |

| Row    | 1   | 2   | 3   | 4   | 5   |
| ------ | --- | --- | --- | --- | --- |
| Centre | 10% | 30% | 50% | 70% | 90% |

## Draw it from a response

Give the element five empty children, one per row:

```html

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

```

```css
.mesh {
  position: relative;
  overflow: hidden;
  aspect-ratio: 16 / 9;
  background-color: #111; /* fallback when ambientMesh is null */
}

.mesh > * {
  position: absolute;
  inset: 0;
}
```

Then set the colours from the response:

```js
const centre = (index, count) => `${((index + 0.5) / count) * 100}%`;

function drawAmbientMesh(element, mesh) {
  if (!mesh) return;
  element.style.backgroundColor = mesh.base;
  mesh.grid.forEach((row, r) => {
    const layer = element.children[r];
    const stops = row.map((colour, c) => `${colour} ${centre(c, row.length)}`);
    layer.style.backgroundImage = `linear-gradient(90deg, ${stops.join(", ")})`;
    if (r > 0) {
      const from = centre(r - 1, mesh.grid.length);
      const to = centre(r, mesh.grid.length);
      layer.style.maskImage = `linear-gradient(transparent ${from}, #000 ${to})`;
    }
  });
}

const show = await fetch("https://api.mediux.io/shows/1396").then((r) =>
  r.json(),
);
drawAmbientMesh(
  document.querySelector(".mesh"),
  show.metadataImages.backdrop?.ambientMesh,
);
```

## The same mesh as static CSS

For a fixed page, or to check your output against a known result, here is the
response above (Breaking Bad) as plain CSS. It uses the HTML and the `.mesh` rules from the previous
section.

```css
.mesh {
  background-color: #015f66;
}

.mesh > :nth-child(1) {
  background-image: linear-gradient(
    90deg,
    #2f4832 6.25%,
    #334c32 18.75%,
    #345135 31.25%,
    #32553b 43.75%,
    #31593d 56.25%,
    #325b3e 68.75%,
    #375c3b 81.25%,
    #3c5b38 93.75%
  );
}
.mesh > :nth-child(2) {
  background-image: linear-gradient(
    90deg,
    #30472f 6.25%,
    #354b30 18.75%,
    #365033 31.25%,
    #355439 43.75%,
    #33593d 56.25%,
    #315c40 68.75%,
    #325d41 81.25%,
    #325e40 93.75%
  );
  mask-image: linear-gradient(transparent 10%, #000 30%);
}
.mesh > :nth-child(3) {
  background-image: linear-gradient(
    90deg,
    #31452d 6.25%,
    #34482d 18.75%,
    #374d30 31.25%,
    #375335 43.75%,
    #35573a 56.25%,
    #315c40 68.75%,
    #2d5e44 81.25%,
    #295f48 93.75%
  );
  mask-image: linear-gradient(transparent 30%, #000 50%);
}
.mesh > :nth-child(4) {
  background-image: linear-gradient(
    90deg,
    #2c412a 6.25%,
    #2f4329 18.75%,
    #32472d 31.25%,
    #334d32 43.75%,
    #31553a 56.25%,
    #2d5b42 68.75%,
    #275e49 81.25%,
    #1f604f 93.75%
  );
  mask-image: linear-gradient(transparent 50%, #000 70%);
}
.mesh > :nth-child(5) {
  background-image: linear-gradient(
    90deg,
    #253e29 6.25%,
    #283e28 18.75%,
    #2a412a 31.25%,
    #2b4830 43.75%,
    #2a5039 56.25%,
    #265a45 68.75%,
    #205e4e 81.25%,
    #196054 93.75%
  );
  mask-image: linear-gradient(transparent 70%, #000 90%);
}
```

## Fill a different shape

The grid maps onto a 16:9 frame. To fill a wider or taller area without stretching
the wash, size every row like `background-size: cover` and centre it. Set the same
size on the mask:

```css
.mesh {
  container-type: size;
}

.mesh > * {
  --frame-width: max(100cqw, calc(100cqh * 16 / 9));
  --frame: var(--frame-width) calc(var(--frame-width) * 9 / 16);
  background-size: var(--frame);
  background-position: center;
  background-repeat: no-repeat;
  mask-size: var(--frame);
  mask-position: center;
  mask-repeat: no-repeat;
}
```

Unprefixed `mask-image` works in current Chrome, Edge, Firefox and Safari. For Safari
before 15.4, also set `-webkit-mask-image` to the same value.

## Caching

The mesh and accent come with the title's detail response, so they follow that
response's [caching](https://docs-preview.mediux.io/api/caching.md). When Mediux improves how meshes are made, every
title's response is refreshed with the new colours, so read them from the API instead
of storing them for good.
