A pure Zig 2D graphics library - z2d

[vancluever]

Hey folks! I thought I’d post on Ziggit about z2d, my pure Zig 2D graphics library.

GitHub - vancluever/z2d: Pure Zig 2D graphics library

I have been working on this library now for a little over a year (you may have seen me posting progress about it if you are on the Zig or Ghostty Discords!). While there’s always more to do, I’d like to think that over the last few months it’s gotten more and more feature complete.

So what can z2d do currently?

• Vector primitives: lines, splines, and arcs (arc helper approximates using splines).
• Fill and stroke with support for different stroke join styles, cap styles, and dashed lines.
• Transformations of various kinds for a number of operations in the library.
• Sources include pixel and gradient patterns (linear, radial, and conic).
• Composition: 28 different Porter-Duff and blend mode operators using a multi-step compositor.
• Surface formats: RGB/RGBA, and 8/4/1-bit alpha.
• Color space support: RGB, sRGB (simple gamma transfer at the moment) and HSL supported currently (polar interpolation in HSL is supported for gradients as well). More spaces are planned.

There are also other features, like a toy PNG exporter for testing, and dithering support, useful for reducing banding in gradients.

Finally, I should note that z2d is currently CPU rendering only and there is not a current roadmap for GPU support. This is not to say it won’t be done, just that there are still other things that I want to do before moving on to this.

---

I work on z2d regularly and am nowhere close to done. More of the current features will be improved on over the next few months, and text support is planned as well. Check it out and let me know if you have any feedback, questions, or if you’ve found it useful!

[mperillo]

How it the performance compared to Cairo/Pixman?

[vancluever]

How it the performance compared to Cairo/Pixman?

So at this point… not so great. With some caveats!

I did up some benchmarks with zBench this morning just to check. Every now and then I test the performance with poop - I’ll get to that in a second, but the zBench benchmarks will likely be more realistic because we want to track the actual operations without the load time or dynamic linker overhead.

Here’s the results on the logomark README test:

So we’re looking at around 20x worse on default AA, but only about 10x with AA disabled. Funny enough if you’re exporting, things jump a lot (and we actually beat Cairo!). Not too sure what’s going on there, if it’s indicative of libpng performance or something else I’m missing.

Now to illustrate the caveats, here’s the poop output for my default case (no export, default AA):

Quite different.

This shows probably the biggest advantage of using z2d currently over something like Cairo or Pixman - no C dependencies or external libraries, just pure Zig and static linking.

Performance is something I’ll be able to work on a lot more as the feature set matures. I made pretty big inroads in 0.6.0 as most compositor operations are now vectorized, but as we become more feature complete (especially once text support lands) this is something that will get more attention!

Appendix A: Allocator choice

Thinking about certain factors that could affect the benchmark after I posted this, I decided to run the benchmark again, but using c_allocator instead of SmpAllocator. Interesting results:

This drops the performance loss down to only around 10x for default AA and 8x for no AA.

So there’s obviously some other factors that are going to affect your mileage here, the test is not going to be 1:1 at all, and being 1:1 may not be what you actually want; using the C allocator gives you a dependency on libc, with regards to this one example. Again, at the moment, the true benefit to using z2d over something like Cairo or Pixman is the fact that’s it’s pure Zig.

[tsdtas]

Again, at the moment, the true benefit to using z2d over something like Cairo or Pixman is the fact that’s it’s pure Zig.

I’m really interested in if this means it could be used for embedded/freestanding applications. Is it possible to provide an interface of some sort for the surface drawing functions?

[vancluever]

@tsdtas xq (of TinyVG fame and plenty of other Zig things embedded and not) did manage to get z2d functional on a bread-boarded embedded setup some time ago (it’s actually what motivated me to work on the sub 8-bit surfaces and work on reducing the amount of RAM compositing used). There’s a video and a bit of feedback about it in the z2d showcase thread in the Zig Discord if you’re on it.

With that said I’m not too sure the particulars on his setup with regards to how freestanding it was, so I’m not too sure.

I’d be new to working on making a freestanding-supported library but I can definitely make a mental note to at some point at least try to build a “hello world” of sorts to get a freestanding target up and running. Is there anything particular that you can think of off the top of your head that’s needed?

[chung-leong]

If the library works in WebAssembly it can be pretty useful.

[vancluever]

@chung-leong I think that’s probably related to the freestanding concerns, so I’d imagine the same status applies to WASM as it does for freestanding.

I can say for sure that we don’t have any API right now that’s export-ed, and there’s be some work there that would need to be done to make it happen, but again, once z2d is more feature complete baseline I’ll have more time to devote to these kinds of cases (barring low-hanging fruit and getting nerdsniped, at which point it might get done earlier. )

[chung-leong]

Sounds like it should work. If code only performs operations on a memory buffer. I’ll definitely look into using this lib for the purpose in question when I find the time.

[vancluever]

@chung-leong yeah we’re CPU and memory buffer only; the only thing that I think would possibly have issues there is the PNG exporter which writes to the filesystem obviously, but otherwise that’s it. Would love to hear how it ends up going for you if/when you make your attempt!

[igors84]

Very nice library. It sounds like you have some overlap with zigimg (color type and colorspace things maybe). It sounds like it would be a great fit if you made it work with its data types and Image in memory representations. Is that something you considered or are there some factors preventing this interop?

[vancluever]

@igors84 thank you!

WRT zigimg - that has been something that’s come up before, but it’s looking like as development goes on that I want as much as possible to try and take a zero-dependency approach. API wise, I want to assure a consumer that when they pull in z2d that they’re not going to run into any other issues with an indirect dependency; it also gives me freedom to ensure I can do what’s best for z2d’s implementation.

While that means there’s probably going to be overlap with other libraries for sure, interop will be something I will be keeping in mind. On the topic of zigimg: it will almost guaranteed be a better exporter on part of the APIs supporting a much larger feature set (the exporter is a toy primarily designed for library testing), and it should only be a few hops to convert our buffers to a format zigimg can use. With regards to colorspaces, while I admit to not looking at zigimg’s model in depth, there’s a chance that how z2d positions colorspaces differs (as opposed to pixel memory), and with it being an important part of the library, I definitely don’t want it depending on an external implementation.

Hope that helps!

[vancluever]

Hey folks, v0.6.1 has been tagged in z2d to address a few bugfixes. Namely, an overflow issue has been fixed in the compositor in situations where the source surface was being written to negative co-ordinate space in such a way where it would never overlap on part of the x-axis (while still overlapping on the y-axis).

While I’m not aware of this causing anything nefarious at this point, due to the potential for out-of-bounds memory reads/writes in composition, I’m advising that anyone using z2d v0.6.0, or a pre-tagged version after v0.5.1, to update to the latest to address this issue.

There is a GHSA for this issue: OOB composition could lead to invalid memory access and corruption · Advisory · vancluever/z2d · GitHub

Thanks!