Add selective multi-mip tiled decoding, 16K tile support, per-frame RC, and codec callbacks

[jsperrier1]

Title: Add selective multi-mip tiled decoding, 16K tile support, per-frame RC, and codec callbacks

---

Summary

This PR adds a set of decoder/encoder capabilities developed for a tiled, multi-resolution ("mip") streaming workflow, ported onto current main. The headline addition is a selective multi-mip tile decoder that decodes an arbitrary subset of tiles across multiple mip levels of an access unit in a single call, with coalesced I/O and multi-threaded tile decode. Supporting changes extend tile limits to 16K, add per-frame rate control, and introduce pluggable memory/logging/CPU-trace callbacks.

Library (src/, inc/) and app (app/) changes only. The test harness and media for this feature are substantial and are being finished on a separate branch; I'd like to land the library first and follow up with tests. Happy to reorder if you'd prefer them together.

Motivation

For large images (up to 16K) encoded as tiled mip pyramids, clients often need only a viewport-dependent subset of tiles at a chosen resolution rather than a full-frame decode. The existing API decodes whole access units. This adds a random-access path that locates the requested mip frames, reads only the needed tile payloads (coalescing adjacent reads), and decodes the selected tiles in parallel.

What's included

Selective multi-mip decode (core)

• oapvd_decode_selective_multi_mips() — decode a set of {mip level, tile coords} requests in one traversal, via a caller-supplied random-access oapvd_istream_t (seek/read/tell). Per-request status is reported per mip; coalesced block I/O minimizes seeks; tiles decode across worker threads.
• Decodes into caller output buffers with either standard planar or tile-major ("tiled") layout, with optional per-tile destination-slot routing for bounded output buffers.

16K tile support

• Tile grid limits raised to 64x64 (OAPV_MAX_TILE_ROWS/OAPV_MAX_TILE_COLS), supporting 16K at 256x256 tiles. Tile arrays are allocated dynamically rather than fixed.

Per-frame rate control

• RC parameters can vary per frame within a sequence (rc_param_frm[]), loaded per frame during encode.

Bitstream: tile_size_present_in_fh_flag

• Now a real, parameterized frame-header flag (oapve_param_t), defaulting to 0 (unchanged/base bitstream). When enabled it writes per-tile sizes into the frame header so a decoder can index individual tiles — required for the selective path. The encoder app sets it under --tmv-mips.

Codec callbacks

• oapv_set_logging_callback() / oapv_set_logging_verbosity() (OAPV_LOG_ERROR|WARNING|INFO|DEBUG), default WARNING.
• oapv_set_memory_callbacks() — pluggable allocators (NULL resets to libc).
• oapv_set_cputrace_callbacks() — optional CPU event tracing (NULL resets to no-op).
• Usage contract (call before creating codec instances; not safe while live) documented in inc/oapv.h.

Encoder app (app/)

• --tmv-mips — enables the tiled/mip workflow: sets tile_size_present_in_fh_flag and emits per-AU tiled output.
• Per-AU output and .oapv/.apv output-extension handling.

Public API additions (inc/oapv.h)

• oapvd_decode_selective_multi_mips, oapvd_istream_t
• oapv_mip_request_t, oapv_multi_mip_decode_t
• oapv_set_logging_callback, oapv_set_logging_verbosity, oapv_log_callback_t, OAPV_LOG_*
• oapv_set_memory_callbacks, oapv_memory_callbacks_t
• oapv_set_cputrace_callbacks, oapv_cputrace_callbacks_t
• OAPV_MAX_TILE_ROWS, OAPV_MAX_TILE_COLS

Backward compatibility

• No change to existing bitstreams or the normal decode path by default: tile_size_present_in_fh_flag defaults to 0, callbacks default to prior behavior, and the standard oapvd_decode() path is untouched (the selective decoder uses its own frame-prepare that skips imgb validation because it decodes into caller buffers).
• All existing ctest cases pass unchanged.

Robustness / hardening

Given the recent fuzz-hardening work upstream (#224, #226), the selective path validates its inputs in the same spirit:

• Every istream->read() return is checked; a short read flags the affected coalesced block, its tiles are skipped (never decoded from stale memory), and the call returns OAPV_ERR_MALFORMED_BITSTREAM.
• Per-tile sizes are validated against the PBU payload bounds before being used to compute offsets.
• Header parsing cannot loop indefinitely when a header exceeds the 64 KB grow cap.
• Missing tile_size_present_in_fh_flag is a hard OAPV_ERR_UNSUPPORTED for the selective path rather than a silent fallback.
• Bounded logging (vsnprintf); NULL-safe callback setters.

Testing

The dedicated test suite (a data-driven decoder_test, multi-mip performance/error-handling programs, and media) lives on a separate branch and is not part of this PR. Validation performed there against this code: existing ctest suite 16/16; a 4K selective-decode case matrix (single/sparse/contiguous/strip tile sets across mip levels); multi-mip error-handling and performance programs; and a truncated/corrupt-input check that returns cleanly (no crash/hang) at 1/4/32 threads. I can bring a minimal subset of tests into this PR if you'd prefer coverage to land together.

Notes for reviewers

• The selective decoder requires random-access input (oapvd_istream_t), distinct from the existing in-memory AU API.
• Feedback welcome on: the callback API surface, whether the 16K tile-limit bump warrants a level/profile note, and whether you'd like (a subset of) tests included here vs. a follow-up.

[jsperrier1]

Reference presentation: https://youtu.be/qs6wo67YzME?si=NKcoVqIwD2s_6xpd

[kpchoi]

This is kind of super patch.
It would be recommended that one PR has one feature.
Anyway, let's solve one by one from the easiest feature by discussion, first.

[kpchoi]

Proposal: 16k tile support

Tile grid limits raised to 64x64 (OAPV_MAX_TILE_ROWS/OAPV_MAX_TILE_COLS), supporting 16K at 256x256 tiles. Tile arrays are allocated dynamically rather than fixed.

Discussion

The max tile rows and max tile coloums are defined in section 9.4.1 of RFC 9984;
https://www.rfc-editor.org/rfc/rfc9924.html#section-9.4.1

The value of TileCols MUST be less than or equal to 20.
The value of TileRows MUST be less than or equal to 20.

Therefore, oapv.h defines the following values;

#define OAPV_MAX_TILE_ROWS              (20) // max number of tiles in row
#define OAPV_MAX_TILE_COLS              (20) // max number of tiles in column
#define OAPV_MAX_TILES                  (OAPV_MAX_TILE_ROWS * OAPV_MAX_TILE_COLS)

Basically, it is kind of 'spec violation' if the max values are changed.
Unfortunately, changing the values is not a straightforward decision.

[kpchoi]

Proposal: Callbacks

Codec callbacks
oapv_set_logging_callback() / oapv_set_logging_verbosity() (OAPV_LOG_ERROR|WARNING|INFO|DEBUG), default WARNING.
oapv_set_memory_callbacks() — pluggable allocators (NULL resets to libc).
oapv_set_cputrace_callbacks() — optional CPU event tracing (NULL resets to no-op).
Usage contract (call before creating codec instances; not safe while live) documented in inc/oapv.h.

Discussion

Could explain main purposes of the callbacks?
Basically, liboapv doesn't log any message now.
And, memory callback is for replacing malloc() function, for example?

[kpchoi]

Proposal: Rate control per-frame

RC parameters can vary per frame within a sequence (rc_param_frm[]), loaded per frame during encode.

Discussion

In order to support indivisual multi-frames rate controlling, the oapve_rc_param_t rc_param; should be changed to oapve_rc_param_t rc_param[OAPV_MAX_NUM_FRAMES];.
But you implementation seems to be different way.
@mss-park , could you make a code patch only for this issue and raise PR?

[kpchoi]

Tile-based decoding

Discussion

There is new API to support partial decoding based on tile position;
OAPV_EXPORT int oapvd_decode_frame(oapvd_t did, oapv_bitb_t *bitb, oapv_imgb_t *imgb, oapvd_stat_t *stat, oapv_tile_info_t * part);

Have you checked the function can supports the requested feature?

[mss-park]

Proposal: Rate control per-frame

RC parameters can vary per frame within a sequence (rc_param_frm[]), loaded per frame during encode.

Discussion

In order to support indivisual multi-frames rate controlling, the oapve_rc_param_t rc_param; should be changed to oapve_rc_param_t rc_param[OAPV_MAX_NUM_FRAMES];. But you implementation seems to be different way. @mss-park , could you make a code patch only for this issue and raise PR?

I agree that the rate control model should be managed on a per-frame basis. However, in order to support multiple frames within a single AU (Access Unit), further changes seem to be required. Could you please clarify if your goal is to encode multiple frames within a single AU?

[jsperrier1]

Rate control per-frame

---

Could you please clarify if your goal is to encode multiple frames within a single AU?

Yes, it is the goal. In particular for TMV use case, we encode mip 0 as the primary full resolution frame and the lower resolution mips (1, 2, 3, ... N) as non-primary frames in the same AU. For interop: Non-TMV compliant players ignore non-primary frames and can still play the sequence normally (although only confirmed with ffplay).

[jsperrier1]

Callbacks

---

Could explain main purposes of the callbacks?

Memory allocator callbacks:

And, memory callback is for replacing malloc() function, for example?

Correct. It is the usually clean method of supporting Unreal engine's custom memory allocators. UE supports hot module reload (live coding) and other complex operations. It is preferable to have the cleanest interface possible.

log and cpu trace callbacks:

The approach we are proposing for TMV is to have a more complex "request-based" decoding API. We can elaborate that in parallel in the decoding api discussion, but for the purpose of this answer, the idea is that the complexity of the AU parsing and tile decoding worker thread management of TMV implementation is pushed in oapv itself, to facilitate implementation of a TMV-like player outside of Unreal. Because the decoding api is now request-based and more complex, profiling and error management is also more complex. In UE, the general approach in that case is to expose log and cpu trace to ease trouble shooting for errors or performance issues. We often ask users to run the problematic levels of their game with verbose logging and using Unreal Insights to capture traces, then send us the logs and traces so we can figure out what is wrong.

So, those callbacks are not critical to this implementation (and we can debate the pertinence of each log individually), but have been proven to provide great help for long term user support and maintenance.

[jsperrier1]

Tile-based decoding

---

Have you checked the function can supports the requested feature?

For the TMV player implementation, we want to play very high resolution content in a 3d viewport where only a part of the content is visible, either a lower resolution mip or part of the content at high resolution. The typical example is viewing a 16K video on a 4K display. The API we need should allow of partial read of the AU (or frame), i.e. we don't want to have to read the entire compressed frame or access unit if we don't have to. It will be typically the case that only a sub-set of the compressed byte stream is needed for decoding the requested mips/tiles.

The existing oapvd_decode_frame API requires the access unit to be loaded in memory. In most cases, we can't afford to read the whole AU or even encoded frame. This is why, in oapvd_decode_selective_multi_mips, we are using read callbacks (oapvd_istream_t) to allow for a selective reading of the byte stream itself.

The other issue is with the performance of tile decoding related to batching patterns. If we batch work per frame (i.e. per mip in tmv context), we have very inefficient use of the worker thread pool:

We don't want the decoder to wait on all worker thread to finish decoding a "mip" before starting to decode tiles from the next mips. This is why oapvd_decode_selective_multi_mips is also "request based", i.e. a single call to oapvd_decode_selective_multi_mips will batch all of the requested mips (frames) as efficiently as possible in terms of both reading and decoding:

oapvd_decode_frame is a middle ground that we can't use. Either we would have to go with an even lower level api like oapvd_decode_tile and the entire AU partial reading, parsing and worker thread management would be part of UE, or we go with the current proposal with is to push all that in opav so it can be reused to implement TMV-like player outside of UE.
That was the thinking behind this.

[kpchoi]

Callbacks

Could explain main purposes of the callbacks?

Memory allocator callbacks:

And, memory callback is for replacing malloc() function, for example?

Correct. It is the usually clean method of supporting Unreal engine's custom memory allocators. UE supports hot module reload (live coding) and other complex operations. It is preferable to have the cleanest interface possible.

log and cpu trace callbacks:

The approach we are proposing for TMV is to have a more complex "request-based" decoding API. We can elaborate that in parallel in the decoding api discussion, but for the purpose of this answer, the idea is that the complexity of the AU parsing and tile decoding worker thread management of TMV implementation is pushed in oapv itself, to facilitate implementation of a TMV-like player outside of Unreal. Because the decoding api is now request-based and more complex, profiling and error management is also more complex. In UE, the general approach in that case is to expose log and cpu trace to ease trouble shooting for errors or performance issues. We often ask users to run the problematic levels of their game with verbose logging and using Unreal Insights to capture traces, then send us the logs and traces so we can figure out what is wrong.

So, those callbacks are not critical to this implementation (and we can debate the pertinence of each log individually), but have been proven to provide great help for long term user support and maintenance.

@jsperrier1 — this really helps clarify the intent. Let me split my response into the two callback groups, since I think they need to be handled quite differently.

Memory callbacks

I fully understand the motivation (clean integration with Unreal's custom allocators, live coding, etc.), and I agree it's a reasonable thing to want.

My main concern is security. Since liboapv parses untrusted bitstreams, allowing the allocator to be replaced can
easily become a serious vulnerability if it isn't done very carefully. Given the fuzz-hardening work we've been
doing recently (#224, #226), I want to be cautious here.

I don't want to just say no, though — I'd like to think more about whether there's a safe way to achieve the same
goal, and come back to you with a proposal. Let me take some time on this.

Logging and CPU-trace callbacks

Looking at the code, all of the log_msg() calls and the CPU-trace hooks live inside the new selective /
tile-based partial decoding path (oapvd_decode_selective_multi_mips) — none of the existing encode/decode paths
emit anything. So these callbacks really only have meaning in the context of that new decoding API.

Because of that, I'd prefer to review them together with the tile-based partial decoding discussion rather than
as a standalone feature. And if it turns out they aren't strictly necessary for that feature, I'd like to drop
them to keep the surface minimal. We can absolutely revisit the individual logs there, as you suggested.

[kpchoi]

Callbacks

Could explain main purposes of the callbacks?

Memory allocator callbacks:

And, memory callback is for replacing malloc() function, for example?

Correct. It is the usually clean method of supporting Unreal engine's custom memory allocators. UE supports hot module reload (live coding) and other complex operations. It is preferable to have the cleanest interface possible.
log and cpu trace callbacks:
The approach we are proposing for TMV is to have a more complex "request-based" decoding API. We can elaborate that in parallel in the decoding api discussion, but for the purpose of this answer, the idea is that the complexity of the AU parsing and tile decoding worker thread management of TMV implementation is pushed in oapv itself, to facilitate implementation of a TMV-like player outside of Unreal. Because the decoding api is now request-based and more complex, profiling and error management is also more complex. In UE, the general approach in that case is to expose log and cpu trace to ease trouble shooting for errors or performance issues. We often ask users to run the problematic levels of their game with verbose logging and using Unreal Insights to capture traces, then send us the logs and traces so we can figure out what is wrong.
So, those callbacks are not critical to this implementation (and we can debate the pertinence of each log individually), but have been proven to provide great help for long term user support and maintenance.

@jsperrier1 — this really helps clarify the intent. Let me split my response into the two callback groups, since I think they need to be handled quite differently.

Memory callbacks

I fully understand the motivation (clean integration with Unreal's custom allocators, live coding, etc.), and I agree it's a reasonable thing to want.

My main concern is security. Since liboapv parses untrusted bitstreams, allowing the allocator to be replaced can easily become a serious vulnerability if it isn't done very carefully. Given the fuzz-hardening work we've been doing recently (#224, #226), I want to be cautious here.

I don't want to just say no, though — I'd like to think more about whether there's a safe way to achieve the same goal, and come back to you with a proposal. Let me take some time on this.

Logging and CPU-trace callbacks

Looking at the code, all of the log_msg() calls and the CPU-trace hooks live inside the new selective / tile-based partial decoding path (oapvd_decode_selective_multi_mips) — none of the existing encode/decode paths emit anything. So these callbacks really only have meaning in the context of that new decoding API.

Because of that, I'd prefer to review them together with the tile-based partial decoding discussion rather than as a standalone feature. And if it turns out they aren't strictly necessary for that feature, I'd like to drop them to keep the surface minimal. We can absolutely revisit the individual logs there, as you suggested.

@jsperrier1 , BTW, does it require to use the custom memory allocator for oapvm_xxx functions (metadata related functions)? The memory allocator could be introduced for encoder and decoder, but metadata manager seems to be a little difficult because oapvm_create() function doesn't have the cdesc parameter. The current API needs to be changed if it should be supported.

[kpchoi]

Callbacks

Could explain main purposes of the callbacks?

Memory allocator callbacks:

And, memory callback is for replacing malloc() function, for example?

Correct. It is the usually clean method of supporting Unreal engine's custom memory allocators. UE supports hot module reload (live coding) and other complex operations. It is preferable to have the cleanest interface possible.
log and cpu trace callbacks:
The approach we are proposing for TMV is to have a more complex "request-based" decoding API. We can elaborate that in parallel in the decoding api discussion, but for the purpose of this answer, the idea is that the complexity of the AU parsing and tile decoding worker thread management of TMV implementation is pushed in oapv itself, to facilitate implementation of a TMV-like player outside of Unreal. Because the decoding api is now request-based and more complex, profiling and error management is also more complex. In UE, the general approach in that case is to expose log and cpu trace to ease trouble shooting for errors or performance issues. We often ask users to run the problematic levels of their game with verbose logging and using Unreal Insights to capture traces, then send us the logs and traces so we can figure out what is wrong.
So, those callbacks are not critical to this implementation (and we can debate the pertinence of each log individually), but have been proven to provide great help for long term user support and maintenance.

@jsperrier1 — this really helps clarify the intent. Let me split my response into the two callback groups, since I think they need to be handled quite differently.

Memory callbacks

I fully understand the motivation (clean integration with Unreal's custom allocators, live coding, etc.), and I agree it's a reasonable thing to want.
My main concern is security. Since liboapv parses untrusted bitstreams, allowing the allocator to be replaced can easily become a serious vulnerability if it isn't done very carefully. Given the fuzz-hardening work we've been doing recently (#224, #226), I want to be cautious here.
I don't want to just say no, though — I'd like to think more about whether there's a safe way to achieve the same goal, and come back to you with a proposal. Let me take some time on this.

Logging and CPU-trace callbacks

Looking at the code, all of the log_msg() calls and the CPU-trace hooks live inside the new selective / tile-based partial decoding path (oapvd_decode_selective_multi_mips) — none of the existing encode/decode paths emit anything. So these callbacks really only have meaning in the context of that new decoding API.
Because of that, I'd prefer to review them together with the tile-based partial decoding discussion rather than as a standalone feature. And if it turns out they aren't strictly necessary for that feature, I'd like to drop them to keep the surface minimal. We can absolutely revisit the individual logs there, as you suggested.

@jsperrier1 , BTW, does it require to use the custom memory allocator for oapvm_xxx functions (metadata related functions)? The memory allocator could be introduced for encoder and decoder, but metadata manager seems to be a little difficult because oapvm_create() function doesn't have the cdesc parameter. The current API needs to be changed if it should be supported.

Again, Hi @jsperrier1,

The memory allocator will not use a process-global callback approach. A global, mutable set of function pointers
invoked on every allocation is a control-flow-hijack target in a library that parses untrusted bitstreams — the
same reason glibc removed __malloc_hook/__free_hook — and adding one is undesirable, especially after the recent
fuzz-hardening (#224, #226).

Instead, a per-instance allocator has been implemented and pushed here:
https://github.com/AcademySoftwareFoundation/openapv/tree/add_memory_interface_functions
You could refer this link how it works.
https://github.com/AcademySoftwareFoundation/openapv/tree/add_memory_interface_functions#custom-memory-allocator

The allocator interface is supplied by the caller through the codec descriptor (oapve_cdesc_t / oapvd_cdesc_t)
and copied into the codec instance, so no global state is involved. It carries an opaque udata that is passed
back to every callback (so a host allocator such as Unreal's can be wired in without globals), requires all four
callbacks plus a magic value (partial or invalid interfaces are rejected), and falls back to the standard C
library when unset. All internal encoder/decoder allocations are routed through it.

This has not been extended to the metadata API (oapvm_*). oapvm_create() has no descriptor to carry an allocator,
and changing its signature would break existing users (e.g. FFmpeg's liboapvenc). Metadata allocations are
small, so keeping them on the standard C library should be sufficient; a backward-compatible variant can be added
later if a concrete need arises.

Anyway, let me know your opinons.

[jsperrier1]

Memory allocator callbacks

Instead, a per-instance allocator has been implemented and pushed here: https://github.com/AcademySoftwareFoundation/openapv/tree/add_memory_interface_functions

fine by me.

This has not been extended to the metadata API (oapvm_*). oapvm_create() [...]

I am little on the fence for that one. Metadata allocations are byte-stream driven, so are attacker-influenced and not necessarily small.

For my opinion, given that having all allocations instrumented is used in integration validation and troubleshooting. I would prefer not to leave stones unturned and have all byte-stream driven allocations instrumented. We have had memory corruptions to debug during integration (happens regularly). This is why I added the global hook to make sure I catch everything.

Knowing meta data allocations are not instrumented, it becomes a special case that needs to be tracked and managed. For instance, I would have to make sure it is somehow disabled to make sure corruption doesn't come from that. Ideally, we should make sure that a NILL mid means to skip meta data parsing rather than failing the whole decode.

For oapvd_decode_selective_multi_mips, we are currently not parsing the meta data so it is fine for TMV (for now, although, it probably should). But we also have the Electra/Protron player that has a vanilla OpenApv decoder which would parse meta data.

My vote would be to extend memory hooks to metadata api to avoid making it a special case.