# letterbox.h

Aspect-preserving resize with constant padding, on the SP500 DSP.

This is the "letterbox" step that prepares a camera frame as a fixed-size model input. The source is scaled by `r = min(dst_w/src_w, dst_h/src_h)` so it fits the destination without distortion, and the remaining border is filled with a constant value.

The applied scale and the top-left padding are returned so detections can be mapped back to source coordinates:

```cpp
src_x = (dst_x - result.pad_x) / result.scale;
src_y = (dst_y - result.pad_y) / result.scale;
```

Frames are 8-bit interleaved HWC with no row padding: a row is exactly `width * channels` bytes.

**Example**

```cpp
sp500_dsp_open(0);

sp500_letterbox_params p;
sp500_letterbox_params_init(&p);
p.src_w = 1920; p.src_h = 1080;
p.dst_w = 640;  p.dst_h = 640;

sp500_buffer src = sp500_buffer_wrap(frame, 1920 * 1080 * 3);
sp500_buffer dst = sp500_buffer_alloc(640 * 640 * 3, SP500_ALIGN_NPU);

sp500_letterbox_result r;
if(sp500_letterbox(&src, &p, &dst, &r) == SP500_OK)
{
    // dst.data holds the 640x640x3 model input; r.scale / r.pad_x / r.pad_y
    // map detections back to the 1920x1080 frame.
}
sp500_buffer_release(&dst);
```

## Data structures

| Name | Description |
| --- | --- |
| [`sp500_letterbox_params`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_letterbox_params/index.md>) | Letterbox geometry and options. |
| [`sp500_letterbox_result`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_letterbox_result/index.md>) | Values the DSP computed for a letterbox call. |

## Enumerations

### (anonymous enum)

```cpp
enum
```

Interpolation used by the resize, for [sp500\_letterbox\_params::interp](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_letterbox_params/#interp>).

| Value | Description |
| --- | --- |
| `SP500_RESIZE_NEAREST = 0` | nearest neighbour |
| `SP500_RESIZE_BILINEAR = 1` | bilinear (the default) |
| `SP500_RESIZE_BICUBIC = 2` | bicubic, a = -0.75 |
| `SP500_RESIZE_LANCZOS = 3` | Lanczos4, 8 tap |

## Functions

### sp500\_letterbox\_params\_init

```cpp
void sp500_letterbox_params_init(sp500_letterbox_params *params)
```

Fill `params` with the defaults documented above.

### sp500\_letterbox

```cpp
sp500_status sp500_letterbox(const sp500_buffer *src, const sp500_letterbox_params *params, sp500_buffer *dst, sp500_letterbox_result *result)
```

Letterbox an 8-bit HWC frame on the DSP.

**Parameters**

- `src` — Source frame; at least `src_w * src_h * channels` bytes.
- `params` — Geometry and options; see [sp500\_letterbox\_params](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_letterbox_params/index.md>).
- `dst` — Destination frame; at least `dst_w * dst_h * channels` bytes. Allocating it with [sp500\_buffer\_alloc()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-buffer-alloc>) lets the NPU consume the model input directly, with no copy.
- `result` — Receives the scale and padding. May be NULL if you do not need to map coordinates back.

**Returns**

[SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) on success. [SP500\_ERR\_INVALID\_ARG](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) for a bad parameter, [SP500\_ERR\_BUFFER\_TOO\_SMALL](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) for an undersized frame, [SP500\_ERR\_UNSUPPORTED](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) for an unknown interpolation, [SP500\_ERR\_NOT\_READY](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) if [sp500\_dsp\_open()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-dsp-open>) has not succeeded, [SP500\_ERR\_TIMEOUT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) or [SP500\_ERR\_DSP](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) if the DSP call failed. `result` is only meaningful when the call returned [SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>).
