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)
• ARGB ↔ RGBA / BGRA / ABGR (in-place and copy)
• RGB → ARGB / ABGR
• BGR → ARGB / ABGR
• ARGB / ABGR → RGB / BGR (drop alpha)
• Gray → ARGB / ABGR
• GrayAlpha → ARGB / ABGR
• Fill alpha (set byte 0 = 255 in each 4-byte pixel, for ARGB/ABGR/XRGB/XBGR layouts)

Experimental (feature experimental — API may change)

• RGB565 → RGBA / BGRA (little-endian packed 16-bit, auto-vectorized)
• RGBA / BGRA → RGB565 (lossy compress, round-to-nearest, auto-vectorized)
• RGBA4444 → RGBA / BGRA (little-endian packed 16-bit, auto-vectorized)
• RGBA / BGRA → RGBA4444 (lossy compress, round-to-nearest, auto-vectorized)
• u8 alpha premultiply for RGBA / BGRA (exact integer, auto-vectorized)
• 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]);

// ARGB → RGBA: rotate bytes left [A,R,G,B] → [R,G,B,A]
let mut argb = vec![255u8, 128, 0, 64];
garb::bytes::argb_to_rgba_inplace(&mut argb)?;
assert_eq!(argb, [128, 0, 64, 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)

With the rgb crate, use garb::convert and garb::convert_inplace with typed pixel slices. The right conversion is selected at compile time from the src/dst types — no need to remember function names. In-place swaps return reinterpreted references (zero-copy).

use rgb::{Rgba, Bgra, Rgb};
use garb::{convert, convert_inplace};

// In-place: type-inferred from the return binding
let mut pixels: Vec<Rgba<u8>> = vec![Rgba::new(255, 0, 128, 255); 100];
let bgra: &mut [Bgra<u8>] = convert_inplace(&mut pixels);

// Copy: type-inferred from src and dst
let rgb = vec![Rgb::new(255u8, 0, 128); 100];
let mut bgra = vec![Bgra::default(); 100];
convert(&rgb, &mut bgra).unwrap();

Whole-image conversions (feature imgref)

garb::convert_imgref and garb::convert_imgref_inplace handle strided ImgVec / ImgRef / ImgRefMut types from the imgref crate. In-place conversions 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::convert_imgref_inplace;

let rgba_img = ImgVec::new(vec![Rgba::new(255, 0, 128, 200); 640 * 480], 640, 480);
let bgra_img: ImgVec<Bgra<u8>> = convert_imgref_inplace(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, abgr_to_bgra_inplace, abgr_to_bgra, bgra_to_abgr_inplace, bgra_to_abgr, bgra_to_argb_inplace, bgra_to_argb, abgr_to_rgba_inplace, abgr_to_rgba, rgba_to_abgr_inplace, rgba_to_abgr, fill_alpha_abgr, fill_alpha_xrgb, fill_alpha_xbgr, bgr_to_argb, bgr_to_abgr, abgr_to_bgr, abgr_to_rgb, gray_to_abgr, gray_alpha_to_abgr.

Experimental (feature = "experimental")

Aliases: premultiply_alpha_bgra_u8, premultiply_alpha_bgra_u8_copy, bgr_to_gray, bgra_to_gray, plus _identity and BGR variants for all gray conversions. All functions have _strided variants.

Generic API — convert / convert_inplace (feature rgb)

Type-inferred conversions on rgb crate pixel slices. The compiler selects the right SIMD-optimized conversion from the source and destination types.

convert_inplace pairs (same-size, zero-copy):

convert pairs (copy):

Additional pairs with experimental:

Weighted luma conversions (rgb_to_gray_bt709_buf, etc.) and premultiply_rgba_f32 / unpremultiply_rgba_f32 remain as named functions.

ARGB/ABGR types are not in the rgb crate, so those conversions are only available through garb::bytes.

The previous named functions (rgba_to_bgra_mut, rgb_to_bgra_buf, etc.) are deprecated but still available.

Generic API — convert_imgref / convert_imgref_inplace (feature imgref)

Type-inferred conversions on ImgVec / ImgRef / ImgRefMut from the imgref crate. Same type pairs as above.

With experimental: additional pairs plus weighted luma and premultiply.

The previous named functions (swap_rgba_to_bgra, convert_rgb_to_bgra, etc.) are deprecated but still available.

License

MIT OR Apache-2.0