Skip to main content

Crate garb

Crate garb 

Source
Expand description

§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-optimized pixel format conversions for row-level and whole-image operations. Supports x86-64 AVX2, ARM NEON, and WASM SIMD128 with automatic fallback to scalar code.

§Modules

  • bytes — Core &[u8] conversions (contiguous and strided).
  • [typed_rgb] — Type-safe wrappers using rgb crate pixel types (feature rgb).
  • [imgref] — Whole-image conversions on ImgVec / ImgRef (feature imgref).

§Naming convention

All functions follow the pattern {src}_to_{dst} for copy operations and {src}_to_{dst}_inplace for in-place mutations. Append _strided for multi-row buffers with stride.

§Strides

A stride (also called “pitch” or “row pitch”) 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 &[u8] functions: stride is in bytes.
  • For typed APIs (imgref, typed_rgb): stride is in elements of the slice’s item type — e.g. pixel count for ImgRef<Rgba<u8>>, but byte count for ImgRef<u8>.

When stride == width (in the appropriate unit) the image is contiguous. When stride > width the gap at the end of each row is padding — garb never reads or writes it.

The required buffer length (in elements) for a strided image is: (height - 1) * stride + width

All _strided functions take dimensions before strides:

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

§Feature flags

  • std — Enables std on dependencies (e.g. archmage).
  • experimental — Gray layout, weighted luma, depth conversion, f32 alpha premultiply/unpremultiply. API may change between minor versions.
  • rgb — Type-safe conversions using [rgb] crate pixel types via bytemuck. Zero-copy in-place swaps return reinterpreted references.
  • imgref — Multi-row conversions using ImgRef / ImgRefMut from the imgref crate. No allocation — caller owns all buffers.

Modules§

bytes

Enums§

SizeError
Pixel buffer size or alignment error.