garb

Dress your pixels for the occasion.

You can't show up to a function in the wrong style. Swap your BGR for your RGB, your ARGB for your RGBA, and tie up loose ends like that unreliable alpha BGRX.

SIMD-accelerated pixel format conversions: x86-64 AVX2, ARM NEON, WASM SIMD128, with automatic scalar fallback. no_std compatible, #![forbid(unsafe_code)].

What it does

Converts between pixel layouts at the byte-slice level. Every image decoder and renderer has an opinion about channel order and pixel width, and none of them agree. garb handles the mechanical part — swapping, expanding, and stripping channels — so you can get back to the interesting work.

SIMD-optimized (contiguous and strided)

• RGBA ↔ BGRA (in-place and copy)
• RGB ↔ BGR (in-place and copy)
• RGB → RGBA / BGRA
• BGR → BGRA / RGBA
• RGBA / BGRA → RGB / BGR (drop alpha)
• Gray → RGBA / BGRA
• GrayAlpha → RGBA / BGRA
• Fill alpha (set byte 3 = 255 in each 4-byte pixel, for RGBA/BGRA layouts)

Experimental (feature experimental — API may change)

• Gray → RGB, GrayAlpha → RGB, Gray ↔ GrayAlpha
• RGB / RGBA / BGR / BGRA → Gray (weighted luma: BT.709, BT.601, BT.2020; or identity)
• Depth conversion: u8 ↔ u16, u8 ↔ f32, u16 ↔ f32
• F32 alpha premultiply / unpremultiply (in-place and copy, AVX2 SIMD)

All operations have _strided variants for images with padding between rows (common in video frames and GPU textures).

Performance

All benchmarks on 1920×1080 buffers. "Naive" is the obvious chunks_exact loop — what the compiler autovectorizes on its own. Numbers from GitHub Actions CI; run cargo bench locally for hardware-specific results.

x86-64 (AVX2) — Linux, Zen 4

aarch64 (NEON) — Linux, Ampere Altra

In-place swaps and fill use hand-written NEON and are 2–3.6x faster on all ARM hardware tested (Ampere Altra, Apple Silicon, Snapdragon X). Cross-bpp operations (3↔4 channel, 3bpp copy) use LLVM's autovectorizer, which generates optimal code for these patterns on AArch64.

WASM (SIMD128) — wasmtime

Full benchmark results for all six native platforms plus WASM are available in the CI artifacts. Run cargo bench to reproduce locally.

Usage

The core &[u8] / &mut [u8] API lives in garb::bytes. Every function returns Result<(), SizeError> — no panics, no silent truncation.

use garb::bytes::{rgba_to_bgra_inplace, rgb_to_bgra};
use garb::SizeError;

// In-place: swap R↔B in a 4bpp buffer
let mut pixels = vec![255u8, 0, 128, 255,  0, 200, 100, 255];
rgba_to_bgra_inplace(&mut pixels)?;
assert_eq!(pixels, [128, 0, 255, 255,  100, 200, 0, 255]);

// Copy: RGB (3 bpp) → BGRA (4 bpp), alpha filled to 255
let rgb = vec![255u8, 0, 128];
let mut bgra = vec![0u8; 4];
rgb_to_bgra(&rgb, &mut bgra)?;
assert_eq!(bgra, [128, 0, 255, 255]);
# Ok::<(), SizeError>(())

Strided images

A stride is the distance between the start of one row and the start of the next, measured in units of the slice's element type. For the core &[u8] API that means bytes; for the typed imgref API it means elements of the slice's item type (e.g. pixel count for ImgRef<Rgba<u8>>). When stride > width the gap is padding — garb never reads or writes it.

All _strided functions take dimensions before strides:

• In-place: (buf, width, height, stride)
• Copy: (src, dst, width, height, src_stride, dst_stride)

use garb::bytes::{rgba_to_bgra_inplace_strided, rgb_to_bgra_strided};

// In-place: 60 pixels wide, stride=256 bytes, 100 rows
let mut buf = vec![0u8; 256 * 100];
rgba_to_bgra_inplace_strided(&mut buf, 60, 100, 256)?;

// Copy with different strides: RGB (stride=192) → BGRA (stride=256)
let rgb_buf = vec![0u8; 192 * 100];
let mut bgra_buf = vec![0u8; 256 * 100];
rgb_to_bgra_strided(&rgb_buf, &mut bgra_buf, 60, 100, 192, 256)?;
# Ok::<(), garb::SizeError>(())

Type-safe conversions (feature rgb)

If you're already using the rgb crate, garb::typed_rgb gives you typed wrappers. In-place swaps return reinterpreted references — zero-copy, zero-allocation.

use rgb::{Rgba, Bgra};
use garb::typed_rgb;

let mut pixels: Vec<Rgba<u8>> = vec![Rgba::new(255, 0, 128, 255); 100];
let bgra: &mut [Bgra<u8>] = typed_rgb::rgba_to_bgra_mut(&mut pixels);

Whole-image conversions (feature imgref)

garb::imgref handles strided ImgVec / ImgRef / ImgRefMut types from the imgref crate. In-place swaps consume and return the ImgVec with the buffer reinterpreted. Copy conversions take ImgRef + ImgRefMut — you own the destination buffer.

use rgb::{Rgba, Bgra};
use imgref::ImgVec;
use garb::imgref;

let rgba_img = ImgVec::new(vec![Rgba::new(255, 0, 128, 200); 640 * 480], 640, 480);
let bgra_img: ImgVec<Bgra<u8>> = imgref::swap_rgba_to_bgra(rgba_img);

Feature flags

The crate is no_std + alloc by default. The imgref feature requires alloc. The core byte-slice API has no allocator requirement.

SIMD dispatch

garb uses archmage for runtime SIMD detection with compile-time acceleration. On each platform:

• x86-64: AVX2 (checked at runtime via cpuid)
• aarch64: NEON (compile-time guaranteed on AArch64)
• wasm32: SIMD128 (compile-time via target-feature=+simd128)
• Fallback: Scalar code on all platforms, always available

The first call to each function detects and caches the best available tier. There's no setup, no feature flags to configure, and no unsafe — archmage handles it all behind safe token types.

Function reference

Functions follow {src}_to_{dst} for copies, {src}_to_{dst}_inplace for mutations. Symmetric swaps (like RGBA↔BGRA) provide both names as aliases. Append _strided for padded row layouts.

Core API — garb::bytes (&[u8])

Every function returns Result<(), SizeError>. All have _strided variants.

Aliases: bgra_to_rgba_inplace, bgra_to_rgba, bgr_to_rgb_inplace, bgr_to_rgb, gray_to_bgra, gray_alpha_to_bgra.

Experimental (feature = "experimental")

Aliases: bgr_to_gray, bgra_to_gray, plus _identity and BGR variants for all gray conversions.

typed_rgb (feature rgb)

Typed wrappers using rgb crate pixel types. In-place swaps return reinterpreted &mut references (zero-copy).

With experimental: gray_to_rgb_buf, gray_alpha_to_rgb_buf, gray_to_gray_alpha_buf, gray_alpha_to_gray_buf, rgb_to_gray_*_buf, rgba_to_gray_*_buf, premultiply_rgba_f32, unpremultiply_rgba_f32, plus identity and BGR variants.

imgref (feature imgref)

Whole-image conversions on ImgVec / ImgRef / ImgRefMut. In-place swaps consume and return an ImgVec with the buffer reinterpreted.

With experimental: convert_gray_to_rgb, convert_gray_alpha_to_rgb, convert_gray_to_gray_alpha, convert_gray_alpha_to_gray, convert_rgb_to_gray_*, convert_rgba_to_gray_*, premultiply_rgba_f32, unpremultiply_rgba_f32.

License

MIT OR Apache-2.0