|
| 1 | +# [zstbi](https://github.com/zig-gamedev/zstbi) |
| 2 | + |
| 3 | +Zig bindings and build package for stb_image, stb_image_resize and stb_image_write from [Sean Barrett's stb single-file C libraries](https://github.com/nothings/stb) |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +* Supports Zig memory allocators |
| 8 | +* Supports decoding most popular formats |
| 9 | +* Supports HDR images |
| 10 | +* Supports 8-bits and 16-bits per channel |
| 11 | +* Supports image resizing |
| 12 | +* Supports image writing (.png, .jpg) |
| 13 | + |
| 14 | +## Getting started |
| 15 | + |
| 16 | +Add `zstbi` to your `build.zig.zon` .dependencies with: |
| 17 | + |
| 18 | +``` |
| 19 | +zig fetch --save git+https://github.com/zig-gamedev/zstbi |
| 20 | +``` |
| 21 | + |
| 22 | +and in your `build.zig` add: |
| 23 | + |
| 24 | +```zig |
| 25 | +pub fn build(b: *std.Build) void { |
| 26 | + const exe = b.addExecutable(.{ ... }); |
| 27 | +
|
| 28 | + const zstbi = b.dependency("zstbi", .{}); |
| 29 | + exe.root_module.addImport("zstbi", zstbi.module("root")); |
| 30 | +} |
| 31 | +``` |
| 32 | +Now in your code you may import and use `zstbi`. |
| 33 | + |
| 34 | +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. |
| 35 | +```zig |
| 36 | +const zstbi = @import("zstbi"); |
| 37 | +
|
| 38 | +zstbi.init(allocator); |
| 39 | +defer zstbi.deinit(); |
| 40 | +``` |
| 41 | +```zig |
| 42 | +pub const Image = struct { |
| 43 | + data: []u8, |
| 44 | + width: u32, |
| 45 | + height: u32, |
| 46 | + num_components: u32, |
| 47 | + bytes_per_component: u32, |
| 48 | + bytes_per_row: u32, |
| 49 | + is_hdr: bool, |
| 50 | + ... |
| 51 | +``` |
| 52 | +```zig |
| 53 | +pub fn loadFromFile(pathname: [:0]const u8, forced_num_components: u32) !Image |
| 54 | +
|
| 55 | +pub fn loadFromMemory(data: []const u8, forced_num_components: u32) !Image |
| 56 | +
|
| 57 | +pub fn createEmpty(width: u32, height: u32, num_components: u32, args: struct { |
| 58 | + bytes_per_component: u32 = 0, |
| 59 | + bytes_per_row: u32 = 0, |
| 60 | +}) !Image |
| 61 | +
|
| 62 | +pub fn info(pathname: [:0]const u8) struct { |
| 63 | + is_supported: bool, |
| 64 | + width: u32, |
| 65 | + height: u32, |
| 66 | + num_components: u32, |
| 67 | +} |
| 68 | +
|
| 69 | +pub fn resize(image: *const Image, new_width: u32, new_height: u32) Image |
| 70 | +
|
| 71 | +pub fn writeToFile( |
| 72 | + image: *const Image, |
| 73 | + filename: [:0]const u8, |
| 74 | + image_format: ImageWriteFormat, |
| 75 | +) ImageWriteError!void |
| 76 | +
|
| 77 | +pub fn writeToFn( |
| 78 | + image: *const Image, |
| 79 | + write_fn: *const fn (ctx: ?*anyopaque, data: ?*anyopaque, size: c_int) callconv(.C) void, |
| 80 | + context: ?*anyopaque, |
| 81 | + image_format: ImageWriteFormat, |
| 82 | +) ImageWriteError!void |
| 83 | +``` |
| 84 | +```zig |
| 85 | +var image = try zstbi.Image.loadFromFile("data/image.png", forced_num_components); |
| 86 | +defer image.deinit(); |
| 87 | +
|
| 88 | +const new_resized_image = image.resize(1024, 1024); |
| 89 | +``` |
| 90 | +Misc functions: |
| 91 | +```zig |
| 92 | +pub fn isHdr(filename: [:0]const u8) bool |
| 93 | +pub fn is16bit(filename: [:0]const u8) bool |
| 94 | +
|
| 95 | +pub fn setFlipVerticallyOnLoad(should_flip: bool) void |
| 96 | +``` |
0 commit comments