Implement `dav1d-rs`'s Rust API by leo030303 · Pull Request #1439 · memorysafety/rav1d

leo030303 · 2025-07-06T15:29:36Z

I've copy pasted the PR from #1362 and updated it with some of the suggestions made on that pull request. The main changes are:

Have all the public-facing Rust API code in its own file.
Used some enums from rav1d instead of redefining new ones, and added in doc comments from the original dav1d-rs library to a few items.
Removed as much unsafe code as I could and replaced it with the Rust methods from rav1d as much as possible.

It currently works as a drop-in replacement for dav1d-rs; adding in use rav1d as dav1d; to my fork of image makes everything work fine.

The only functional changes I made are I removed the unsafe impls of Send and Sync for InnerPicture so Picture is no longer Sync or Send. I looked through the code and I don't believe DisjointMut<Rav1dPictureDataComponentInner>, which is a field of one of its children, is thread safe, though I'm open to correction there; I'm pretty unfamiliar with unsafe Rust.

I also don't have safety comments on the two unsafe blocks in rust_api.rs; I'm unsure what these would look like, so open to suggestions there. These are mostly taken verbatim from the old pull request.

Closes Provide Rust API #1252.

kkysen

Thanks for the much safer implementation! I'm still taking a closer look at the unsafes, as the few remaining are still quite critical, but I wanted to give some initial feedback in general first.

src/rust_api.rs

src/include/dav1d/headers.rs

src/rust_api.rs

Pulled out the docs additions from #1439 into its own PR.

src/rust_api.rs

…1442) Pulled out the `Rav1dError` changes from #1439 into a separate PR.

…e `u32` (#1443) Pulled out type changes from here #1439 into its own PR.

kkysen

@leo030303, could you rebase this on main? There are a lot of other commits in here now, so it's harder to review.

Co-authored-by: Khyber Sen <kkysen@gmail.com>

kkysen · 2026-02-11T11:29:47Z

It does let use other types like [u8; N], Box<[u8]>, Vec, Arc<[u8]>, etc. I'm not sure how useful any of those are from the caller's perspective, as I don't have much familiarity with that.

They aren't useful because all of them can be turned into a &[u8] with a single .as_slice() call or sometimes even automatically by the compiler with only a & operator.

I'm not sure what this means. Why does that make it not useful?

This is how it's currently wired up to dav1d: https://github.com/image-rs/image/blob/5d0418d0eff747c829d52738c092581312f775c9/src/codecs/avif/decoder.rs

That seems to be passing a Vec (at least .to_vec(). So wouldn't supporting Vec<u8> help?

Shnatsel · 2026-02-11T11:38:02Z

Vec<u8>.as_slice() is a cheap conversion from Vec<u8> to &[u8], so generics like AsRef<&[u8]> are only a slight ergonomic improvement and generally don't pull their weight in terms of additional complexity.

That seems to be passing a Vec (at least .to_vec()).

Yes, due to the limitations of the dav1d API. The .to_vec() call makes a copy of the data. image would pass the input directly if it could, but I believe the 'static bound makes it impossible.

I'm not terribly concerned about avoiding this copy in the initial version of the API. AV1/AVIF has a very high compression ratio so if we're copying the data in memory the amount is still very small and will only add a couple percent of overhead to the entire decoding, if that. I'm perfectly happy to get rid of the C dependency first and optimize later.

kkysen · 2026-02-11T23:45:44Z

Vec<u8>.as_slice() is a cheap conversion from Vec<u8> to &[u8], so generics like AsRef<&[u8]> are only a slight ergonomic improvement and generally don't pull their weight in terms of additional complexity.

When used as a superficial conversion, this is very true. But rav1d, unlike dav1d, can take ownership of a Vec<u8>, etc. and thread it through everything, which seems legitimately useful.

That seems to be passing a Vec (at least .to_vec()).

Yes, due to the limitations of the dav1d API. The .to_vec() call makes a copy of the data. image would pass the input directly if it could, but I believe the 'static bound makes it impossible.

We can fix the rav1d API, so this should be very fixable.

I'm not terribly concerned about avoiding this copy in the initial version of the API. AV1/AVIF has a very high compression ratio so if we're copying the data in memory the amount is still very small and will only add a couple percent of overhead to the entire decoding, if that. I'm perfectly happy to get rid of the C dependency first and optimize later.

Okay, I think we'll go with option 1 here then. No unsafe and an extra allocation that we can later optimize out.

kkysen

@Shnatsel, if you change the .to_vec() (https://github.com/image-rs/image/blob/5d0418d0eff747c829d52738c092581312f775c9/src/codecs/avif/decoder.rs#L86) to Box::<[u8]>::from(...) and change the dav1d-rs API to just accept Box<[u8]> instead of the impl AsRef<[u8]>, we should be able to avoid an extra copy or two here. We'll still need the one, the Box::<[u8]>::from(...), but we won't be able to fix that one until we fix the 'static lifetime, which is much more tricky. #1470 sets things up to work well with Box<[u8]>.

…rap_c` (#1470) This can be used by #1439 in `fn send_data` to safely create a `Rav1dData` without a second extra allocation. We'll still need one copy with the way the APIs are right now, but this should keep things obviously safe and without a second extra allocation. Next, we can work on redesigning the API to allow zero-copy usage.

…API (#1471) This does some API simplification for #1439 while also supporting other `impl AsRef` types. It separates `CRef` from `CBox`. `CBox` is the pure C abstraction over an owned C reference/"Box". `CRef` is an `enum` over `CBox` and other Rust-native `impl AsRef`s. I tried using `dyn AsRef` first, but we make some safety guarantees about reference stability that we can't make about any `impl AsRef`, and that would force an extra `Box`. Moving the `dyn AsRef` one level higher to `Arc<dyn AsRef<T>>` would be super nice, but in order to send the `Arc`s through FFI boundaries, they can't wrap an unsized type, as we can't send unsized pointers over FFI boundaries (the ptr metadata API is still very unstable). Adding support for non `'static` `&T`s would be extremely useful and would allow us to eliminate a data copy, but that is much more tricky, as we'd have to thread the lifetime through a lot of places and probably rearrange some of the `Rav1dContext`/`Rav1dState` API.

src/rust_api.rs

Co-authored-by: Sergey "Shnatsel" Davidoff <shnatsel@gmail.com>

Co-authored-by: Khyber Sen <kkysen@gmail.com>

leo030303 · 2026-02-14T14:25:40Z

This all looks good so far to me, only note is I had to remove

static_assertions::assert_impl_all!(Decoder: Send, Sync);

Since CRef isn't Send or Sync, if its trivial to add that back in then we should but I'm not sure what safety assumptions you made on the C backend so I didn't want to go messing with that, otherwise I don't think remove the assertion is a very big deal since it just restricts the API a bit

kkysen

Oh, I added Rc to CRef, which isn't Send or Sync. I can remove that.

kkysen

Since CRef isn't Send or Sync, if its trivial to add that back in then we should

I've added it back in #1472 now. Once that merges you can rebase/merge.

src/rust_api.rs

leo030303 · 2026-02-21T11:46:16Z

Think that's most of the outstanding issues wrapped up!

plops · 2026-03-01T12:16:24Z

I can't wait for this to be finished!

kkysen · 2026-03-02T18:58:16Z

src/rust_api.rs

+            .as_byte_mut_ptr()
+            .cast_const();
+
+        if stride == 0 || raw_plane_data_pointer.is_null() {


This should never be null. Let me see if I can fix the API for that.

kkysen requested changes Jul 7, 2025

View reviewed changes

leo030303 mentioned this pull request Jul 7, 2025

Add some docs on AV1 items #1441

Merged

kkysen changed the title ~~Implement Rust API~~ Implement dav1d-rs's Rust API Jul 7, 2025

This was referenced Jul 7, 2025

enum Rav1dError: rename fields to more Rusty versions and add docs #1442

Merged

struct Rav1dSettings: change n_threads and max_frame_delay to be u32 #1443

Merged

kkysen added a commit that referenced this pull request Jul 7, 2025

Add some docs on AV1 items (#1441)

6ccfb84

Pulled out the docs additions from #1439 into its own PR.

kkysen requested changes Jul 8, 2025

View reviewed changes

leo030303 requested a review from kkysen July 8, 2025 22:23

kkysen added a commit that referenced this pull request Jul 15, 2025

enum Rav1dError: rename fields to more Rusty versions and add docs (#…

fb56c0e

…1442) Pulled out the `Rav1dError` changes from #1439 into a separate PR.

kkysen added a commit that referenced this pull request Jul 15, 2025

struct Rav1dSettings: change n_threads and max_frame_delay to b…

ab750d8

…e `u32` (#1443) Pulled out type changes from here #1439 into its own PR.

kkysen reviewed Jul 18, 2025

View reviewed changes

leo030303 and others added 19 commits July 19, 2025 12:29

Implement Rust API

3d6a828

Update src/rust_api.rs

f616c50

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Update src/rust_api.rs

14c32b6

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Update src/rust_api.rs

f5ae0e8

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Replaced Error type with Rav1dError and added better enum names and docs

1aae7a8

Changed types to more reasonable ones

7c10775

Update src/rust_api.rs

a654fc4

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Cleaned up imports, expose DecodeFrameType publicly

282b6d8

Removed option_nonnull

0b85bd8

Update src/rust_api.rs

391c557

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Remove TryFromEnumError as its no longer used

fa961b2

Rename Decoder.dec to Decoder.ctx

7895fda

Cleanup

86c41fb

Update src/rust_api.rs

f2fc387

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Update src/rust_api.rs

fab1bb1

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Update src/rust_api.rs

3a41838

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Cleanup

7c69894

Update src/rust_api.rs

9953560

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Removed an unsafe block

f0540e8

kkysen mentioned this pull request Feb 12, 2026

fn Rav1dData::wrap_rust: add a safe, pure Rust alternative to fn wrap_c #1470

Merged

kkysen reviewed Feb 12, 2026

View reviewed changes

kkysen mentioned this pull request Feb 12, 2026

enum CRef: separate from struct CBox and simplify but expand the API #1471

Merged

kkysen reviewed Feb 13, 2026

View reviewed changes

src/rust_api.rs Outdated Show resolved Hide resolved

leo030303 and others added 6 commits February 14, 2026 13:54

Handle grayscale images better

8465178

Co-authored-by: Sergey "Shnatsel" Davidoff <shnatsel@gmail.com>

Add safety comment in rust_api

8acde6d

Co-authored-by: Sergey "Shnatsel" Davidoff <shnatsel@gmail.com>

Improve send_data

5e31f3a

Co-authored-by: Khyber Sen <kkysen@gmail.com>

Merge branch 'memorysafety:main' into add-rust-api

4d6ec0d

Fix some small issues

10e9ee1

Remove Send Sync assertion from Decoder

73c5fac

leo030303 requested review from Shnatsel and kkysen February 14, 2026 14:26

kkysen reviewed Feb 14, 2026

View reviewed changes

kkysen reviewed Feb 19, 2026

View reviewed changes

src/rust_api.rs Outdated Show resolved Hide resolved

kkysen reviewed Feb 19, 2026

View reviewed changes

src/rust_api.rs Outdated Show resolved Hide resolved

leo030303 and others added 4 commits February 20, 2026 17:12

Pull error handling out of unsafe block in rust_api

edcb5a1

Fix nit

2ea4ce6

Merge branch 'memorysafety:main' into add-rust-api

8241252

Add back in Send Sync assertion for Decoder

3a50834

leo030303 requested a review from kkysen February 21, 2026 11:45

kkysen reviewed Mar 2, 2026

View reviewed changes

Conversation

leo030303 commented Jul 6, 2025 • edited by kkysen Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkysen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kkysen left a comment

Choose a reason for hiding this comment

Uh oh!

kkysen commented Feb 11, 2026

Uh oh!

Shnatsel commented Feb 11, 2026

Uh oh!

kkysen commented Feb 11, 2026

Uh oh!

kkysen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

leo030303 commented Feb 14, 2026

Uh oh!

kkysen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkysen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

leo030303 commented Feb 21, 2026

Uh oh!

plops commented Mar 1, 2026

Uh oh!

kkysen Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

leo030303 commented Jul 6, 2025 •

edited by kkysen

Loading

kkysen left a comment •

edited

Loading