README.md

zstbi

Zig bindings and build package for stb_image, stb_image_resize and stb_image_write from Sean Barrett's stb single-file C libraries

Features

• Supports Zig memory allocators
• Supports decoding most popular formats
• Supports HDR images
• Supports 8-bits and 16-bits per channel
• Supports image resizing
• Supports image writing (.png, .jpg)

Getting started

Add zstbi to your build.zig.zon .dependencies and in your build.zig add:

pub fn build(b: *std.Build) void {
    const exe = b.addExecutable(.{ ... });

    const zstbi = b.dependency("zstbi", .{});
    exe.root_module.addImport("zstbi", zstbi.module("root"));
    exe.linkLibrary(zstbi.artifact("zstbi"));
}

Now in your code you may import and use zstbi.

Init the lib. zstbi.init() is cheap and you may call it whenever you need to change memory allocator. Must be called from the main thread.

const zstbi = @import("zstbi");

zstbi.init(allocator);
defer zstbi.deinit();

pub const Image = struct {
    data: []u8,
    width: u32,
    height: u32,
    num_components: u32,
    bytes_per_component: u32,
    bytes_per_row: u32,
    is_hdr: bool,
    ...

pub fn loadFromFile(pathname: [:0]const u8, forced_num_components: u32) !Image

pub fn loadFromMemory(data: []const u8, forced_num_components: u32) !Image

pub fn createEmpty(width: u32, height: u32, num_components: u32, args: struct {
    bytes_per_component: u32 = 0,
    bytes_per_row: u32 = 0,
}) !Image

pub fn info(pathname: [:0]const u8) struct {
    is_supported: bool,
    width: u32,
    height: u32,
    num_components: u32,
}

pub fn resize(image: *const Image, new_width: u32, new_height: u32) Image

pub fn writeToFile(
    image: *const Image,
    filename: [:0]const u8,
    image_format: ImageWriteFormat,
) ImageWriteError!void

pub fn writeToFn(
    image: *const Image,
    write_fn: *const fn (ctx: ?*anyopaque, data: ?*anyopaque, size: c_int) callconv(.C) void,
    context: ?*anyopaque,
    image_format: ImageWriteFormat,
) ImageWriteError!void

var image = try zstbi.Image.loadFromFile("data/image.png", forced_num_components);
defer image.deinit();

const new_resized_image = image.resize(1024, 1024);

Misc functions:

pub fn isHdr(filename: [:0]const u8) bool
pub fn is16bit(filename: [:0]const u8) bool

pub fn setFlipVerticallyOnLoad(should_flip: bool) void