---
title: "blend"
description: "The blend namespace — the engine's Luau API reference for blend."
section: "API Reference"
slug: "api-blend"
canonical: "https://origozero.ai/docs/api-blend"
updated: "2026-09-05T23:13:46.236162109+00:00"
tags: ["api", "reference"]
---

# blend

The `blend` namespace — 13 functions.

## globals/blend/destroyLayout {#globals-blend-destroylayout}

```lua
blend.destroyLayout(handle: number) -> boolean
```

Drop the layout from the registry.

**Parameters**

- `handle` `number` — Layout handle.

**Returns** `boolean` — True if the layout existed and was removed.

## globals/blend/layout {#globals-blend-layout}

```lua
blend.layout(slots: { BlendSlot }, totalStride: number?) -> number?
```

Register a record-stride layout. Each slot is
`{ offset, stride, op }` where `op` is `"lerp"` / `"slerp"` /
`"sum"` / `"step"`. Slerp slots must have stride 4.
`totalStride` defaults to `max(offset + stride)` across slots;
pass an explicit value when records contain padding past the
last slot.

**Parameters**

- `slots` `{ BlendSlot }` — Array of slot tables.
- `totalStride` `number` _(optional)_ — Optional explicit record stride.

**Returns** `number?` — Layout handle, or nil.

```lua
local l = blend.layout({ { offset = 0, stride = 3, op = "lerp" } })
```

## globals/blend/lerpInto {#globals-blend-lerpinto}

```lua
blend.lerpInto(outBuffer: Substrate.TypedBuffer, layout: number, aBuffer: Substrate.TypedBuffer, bBuffer: Substrate.TypedBuffer, t: number) -> boolean
```

Two-input crossfade shortcut. Equivalent to
`blend.weightedInto(out, layout, { {a, 1-t}, {b, t} })`.
Faster for the common A/B fade case because it skips the
inputs-table walk.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `aBuffer` `Substrate.TypedBuffer` — The A side of the fade.
- `bBuffer` `Substrate.TypedBuffer` — The B side of the fade.
- `t` `number` — Crossfade weight on B (0..1).

**Returns** `boolean` — True on success.

## globals/blend/weightedInto {#globals-blend-weightedinto}

```lua
blend.weightedInto(outBuffer: Substrate.TypedBuffer, layout: number, inputs: { BlendInput }) -> boolean
```

Combine N weighted input buffers into the output buffer
using the layout's slot ops. The output buffer's length must
be a whole multiple of `layout.totalStride`; every input
buffer must be at least as long as the output. Returns false
on any handle / size mismatch.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `inputs` `{ BlendInput }` — Array of `{ buffer, weight }`.

**Returns** `boolean` — True on success.

## modules/blend/README {#modules-blend-readme}

```lua
require("@builtin/modules/api/engine/blend") -- blend (also available as global 'blend')
```

Record-stride blend primitives over Buffer slices — layout registry + weighted/lerp combiners. Public Luau surface over the `__blend` Internal FFI namespace.

Usage: local blend = require("@builtin/modules/api/engine/blend")
Also available as global: blend

## modules/blend/destroyLayout {#modules-blend-destroylayout}

```lua
destroyLayout(handle: number): boolean
```

Drop the layout from the registry.

**Parameters**

- `handle` `number` — Layout handle.

## modules/blend/layout {#modules-blend-layout}

```lua
layout(slots: { BlendSlot }, totalStride: number?): number?
```

Register a record-stride layout. Each slot is
`{ offset, stride, op }` where `op` is `"lerp"` / `"slerp"` /
`"sum"` / `"step"`. Slerp slots must have stride 4.
`totalStride` defaults to `max(offset + stride)` across slots;
pass an explicit value when records contain padding past the
last slot.

**Parameters**

- `slots` `{ BlendSlot }` — Array of slot tables.
- `totalStride` `number?` _(optional)_ — Optional explicit record stride.

```lua
local l = blend.layout({ { offset = 0, stride = 3, op = "lerp" } })
```

## modules/blend/lerpInto {#modules-blend-lerpinto}

```lua
lerpInto(outBuffer: Substrate.TypedBuffer, layout: number, aBuffer: Substrate.TypedBuffer, bBuffer: Substrate.TypedBuffer, t: number): boolean
```

Two-input crossfade shortcut. Equivalent to
`blend.weightedInto(out, layout, { {a, 1-t}, {b, t} })`.
Faster for the common A/B fade case because it skips the
inputs-table walk.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `aBuffer` `Substrate.TypedBuffer` — The A side of the fade.
- `bBuffer` `Substrate.TypedBuffer` — The B side of the fade.
- `t` `number` — Crossfade weight on B (0..1).

## modules/blend/weightedInto {#modules-blend-weightedinto}

```lua
weightedInto(outBuffer: Substrate.TypedBuffer, layout: number, inputs: { BlendInput }): boolean
```

Combine N weighted input buffers into the output buffer
using the layout's slot ops. The output buffer's length must
be a whole multiple of `layout.totalStride`; every input
buffer must be at least as long as the output. Returns false
on any handle / size mismatch.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `inputs` `{ BlendInput }` — Array of `{ buffer, weight }`.

## typed/builtin//modules/api/engine/blend/blend/destroyLayout {#typed-builtin-modules-api-engine-blend-blend-destroylayout}

```lua
blend.destroyLayout(handle: number) -> boolean
```

Drop the layout from the registry.

**Parameters**

- `handle` `number` — Layout handle.

**Returns** `boolean` — True if the layout existed and was removed.

## typed/builtin//modules/api/engine/blend/blend/layout {#typed-builtin-modules-api-engine-blend-blend-layout}

```lua
blend.layout(slots: { BlendSlot }, totalStride: number?) -> number?
```

Register a record-stride layout. Each slot is
`{ offset, stride, op }` where `op` is `"lerp"` / `"slerp"` /
`"sum"` / `"step"`. Slerp slots must have stride 4.
`totalStride` defaults to `max(offset + stride)` across slots;
pass an explicit value when records contain padding past the
last slot.

**Parameters**

- `slots` `{ BlendSlot }` — Array of slot tables.
- `totalStride` `number` _(optional)_ — Optional explicit record stride.

**Returns** `number?` — Layout handle, or nil.

```lua
local l = blend.layout({ { offset = 0, stride = 3, op = "lerp" } })
```

## typed/builtin//modules/api/engine/blend/blend/lerpInto {#typed-builtin-modules-api-engine-blend-blend-lerpinto}

```lua
blend.lerpInto(outBuffer: Substrate.TypedBuffer, layout: number, aBuffer: Substrate.TypedBuffer, bBuffer: Substrate.TypedBuffer, t: number) -> boolean
```

Two-input crossfade shortcut. Equivalent to
`blend.weightedInto(out, layout, { {a, 1-t}, {b, t} })`.
Faster for the common A/B fade case because it skips the
inputs-table walk.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `aBuffer` `Substrate.TypedBuffer` — The A side of the fade.
- `bBuffer` `Substrate.TypedBuffer` — The B side of the fade.
- `t` `number` — Crossfade weight on B (0..1).

**Returns** `boolean` — True on success.

## typed/builtin//modules/api/engine/blend/blend/weightedInto {#typed-builtin-modules-api-engine-blend-blend-weightedinto}

```lua
blend.weightedInto(outBuffer: Substrate.TypedBuffer, layout: number, inputs: { BlendInput }) -> boolean
```

Combine N weighted input buffers into the output buffer
using the layout's slot ops. The output buffer's length must
be a whole multiple of `layout.totalStride`; every input
buffer must be at least as long as the output. Returns false
on any handle / size mismatch.

**Parameters**

- `outBuffer` `Substrate.TypedBuffer` — The buffer written into.
- `layout` `number` — Layout handle.
- `inputs` `{ BlendInput }` — Array of `{ buffer, weight }`.

**Returns** `boolean` — True on success.