Skip to content

Report the bitstream location of each tile from oapvd_info_tile - #260

Merged
cpncf merged 1 commit into
mainfrom
add_tile_bs_info
Aug 8, 2026
Merged

Report the bitstream location of each tile from oapvd_info_tile#260
cpncf merged 1 commit into
mainfrom
add_tile_bs_info

Conversation

@kpchoi

@kpchoi kpchoi commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Requested in #228: seeking directly to a tile requires knowing where it is in the bitstream, which the API did not expose. The frame header already carries the tile sizes when tile_size_present_in_fh_flag is set (written by default since #238), but the decoder parsed them for validation only and discarded them.

oapv_tile_pos_t gains two fields, filled by oapvd_info_tile():

  • offset — byte offset of the tile unit from the start of the PBU
  • size — byte size of the tile data

A tile unit spans 4 + size bytes: the 4-byte size field followed by the tile data. Both fields are zero when the frame header does not carry the tile sizes, so a zero size means the location is unknown and the PBU has to be walked sequentially. The sizes are reported into the caller-supplied array, so nothing is allocated and the existing capacity-check contract of oapvd_info_tile() is unchanged; the frame header parser gained an internal variant that reports the sizes, with the existing entry point delegating to it.

This is what makes the memory-mapped input path in the programmers guide practical for partial decoding: only the pages of the tiles actually decoded are touched, instead of paging in the whole PBU.

The guide documents the assumptions an application has to make about these values, since they are optional and relative:

  • availability is a per-frame choice of the encoder (tile_size_present_in_fh_flag, on by default here, switchable with OAPV_CFG_SET_TILE_SIZE_IN_FH), and a stream from another encoder may not carry the sizes at all, so size has to be checked and the sequential path kept
  • the values are relative to the start of the frame PBU, not to the file or the access unit, so a file reader adds the position where the PBU begins (past au_size, the aPv1 signature and that PBU's pbu_size)
  • they describe only the tile data of that frame PBU; metadata PBUs and other frames of the same access unit are separate PBUs
  • tiles are reported in raster scan order and their units are contiguous, so the end of the last tile coincides with the end of the PBU
  • a successful call reports locations inside the PBU, because the decoder now rejects a frame whose tile sizes do not fit within it, but an application forwarding them to its I/O layer should still bound-check against the buffer or mapping it actually holds

Malformed tile sizes are rejected with OAPV_ERR_MALFORMED_BITSTREAM: the accumulated tile extent is validated against pbu_size while the offsets are computed.

Verified against the real bitstream layout with a harness that re-reads the 4-byte size field at every reported offset and checks it equals the reported size and stays inside the PBU: 2-tile, 135-tile (4K), 255-tile, 400-tile and 32,400-tile (UNCONST 16x16) streams, plus a non-uniform tile grid; in every case the end of the last tile lands exactly on the PBU size. Streams encoded with --disable-tile-size-in-fh and the conformance streams without tile sizes report zeros. All 18 ctest cases pass.

@cpncf cpncf left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Signed-off-by: KP Choi <kp5.choi@samsung.com>
@kpchoi
kpchoi force-pushed the add_tile_bs_info branch from 0e062ec to 94c09f0 Compare August 8, 2026 02:55
@cpncf
cpncf merged commit f1ba30f into main Aug 8, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants