Repository navigation
Releases
v1.1.3.0
v1.1.3.0: API documentation, fixes and hardening
A maintenance release of API set 1. No public function was added or removed, and the layout of the public structures is unchanged.
Shared library name
The SOVERSION is now derived from both the API set and the major version (OAPV_VER_APISET * 10 + OAPV_VER_MAJOR), so this release installs liboapv.so.11 (liboapv-11.dll on Windows). Previous 1.1.x releases installed liboapv.so.1, the same name as 0.1.x. Applications linked against the shared library must be relinked (#308).
Fixes
- Encoder: small leftover tiles at the frame boundary (e.g. 262x262 with 256x256 tiles) no longer fail with
OAPV_ERR_OUT_OF_BS_BUF(#306) - Encoder:
OAPVE_PARAM_QP_AUTO, the default QP, now selectsOAPV_RC_ABR, andOAPV_RC_ABRwithout a bitrate targets the maximum bitrate of the level and band. Before, encoding with the defaults clipped the QP to its maximum. A numeric QP withOAPV_RC_CQPencodes as before (#310) - Frame hash: the encoder and the decoder hash the frame padded to the MB boundary as derived from the frame size, not from the
aw/ahof the caller's buffer (#309) - Frame hash: requesting it without a reconstruction buffer no longer dereferences a NULL pointer (#309)
- Metadata:
oapvm_read_mdcv()reads the primaries in the order of the APV syntax; before, the x and y chromaticities came back mixed up (#312) - Metadata:
oapvm_rem()drops a group once its last payload is removed, instead of leaving an empty group that counted towardOAPV_MAX_NUM_METASand was written as an empty metadata PBU (#313) - Metadata: a failed
oapvm_set()no longer leaves an empty group behind (#303) - Decoder: an out-of-range access of the output frames in
oapvd_decode()was fixed (#303) oapv_app_decreturns the error status when decoding fails (#313)
Robustness
- Public API calls return the error code that matches each failure, and their argument checks were hardened (#303)
oapve_create()rejects a non-positivemax_bs_buf_sizeand checksmax_num_frmsbefore any allocation (#304)- Group IDs above
OAPV_MAX_GROUP_IDare rejected byoapve_encode()andoapvm_set()instead of being truncated to 16 bits, and a reserved group ID in the AU information PBU is rejected (#304, #311) - Bitstream size fields are rewritten only within the bitstream buffer, and the AU signature is read through the bounded bitstream reader (#311)
oapvd_config()checks its size argument asoapve_config()does (#311)
Documentation and tools
oapv.hdocuments the API: an overview, the meaning of each error code, and each public function and structure. The header is reordered into sections (#304)- The release workflow generates
SHA256SUMSafter all assets are uploaded, and uploads the packages to the release that triggered it (#302) - test/README.md lists the right frame count for syn_A and syn_B (#313)
Upgrading from v1.1.2.0
Applications linked against the shared library must be relinked against liboapv.so.11. Source code needs changes only if it relies on one of the following:
OAPV_MAX_GRP_SIZEwas replaced byOAPV_MAX_GROUP_ID, the maximum valid group ID (0xFFFE), and the unusedOAPV_PBU_NUMSwas removed (#304)frm_sizeinoapve_stat_tandoapvd_stat_tis now the size of the frame PBU itself, without the 4-bytepbu_sizefield, so it matches thepbu_sizevalue.oapvd_decode_frame()already reported this size (#313)- Frame hash with a
OAPV_CF_PLANAR2image buffer is rejected withOAPV_ERR_UNSUPPORTEDbyoapve_encode(),oapvd_decode()andoapvd_decode_frame()(#309) - Encoding with the default QP now uses rate control, as described above (#310)
- Some API calls return a more specific error code than before (#303)
v1.1.2.0
v1.1.2.0: faster decoding and hardening
A maintenance release of API set 1. No public function was added, removed or changed, and the ABI is unchanged.
Performance
VLC coefficient decoding was reworked:
- The exp-Golomb prefix is read with a count-leading-zeros instead of bit by bit.
- The bit buffer is topped up with whole bytes before each symbol, so the prefix and suffix of a normal code are read in one step. The buffer end is never read past.
- The separate
k = 0readers were removed; all run and level codes go through one reader.
Decoding is about 20â30% faster at high bitrates and about 8% faster at low bitrates, measured on x86 with both single- and multi-threaded decoding. The decoded output is bit-exact with v1.1.1.0.
Correctness and robustness
- Dequantization no longer left-shifts negative values or overflows
intat high QP; the SIMD paths now saturate correctly - The exp-Golomb prefix sum no longer wraps
u32on malformed input, so builds with-fsanitize=unsigned-integer-overflow(such as Android) no longer abort - The exp-Golomb prefix length is bounded to keep decoded values within
int - Metadata
payload_typeandpayload_sizeare checked againstu32wraparound OAPV_MAX_NUM_META_PAYLOADSis enforced per access unit inoapvm_set()- Encoder error paths release the input and reconstruction image references
- Reconstructed AC coefficients are checked against the 16-bit range
- The encoder enforces the minimum tile width and height of the constrained profiles
- Decoder API hardening: output stride and plane count validation, NULL argument checks
Code cleanup
- Include guards renamed to non-reserved
OPENAPV_<FILE>_H_names static inlinehelpers useforce_inline- Quantization and dequantization matrices renamed to
q_matanddq_mat - Comments explain why the VLC prefix loops have no per-bit range check
- Unused bitstream reader code removed
Tools and documentation
- ImHex pattern: tile, access unit info, gain map and ICC parsing, bit-exact frame header size
- README: related projects section
Upgrading from v1.1.1.0
Applications only need to relink. Two things to note:
- The include guard of
oapv.hchanged from__OAPV_H__...toOPENAPV_OAPV_H_. Code that tested the old guard macro must be updated. - The encoder now rejects
tile_w/tile_hvalues that are not a multiple of 16 when set directly inoapve_param_t. Some of these were silently accepted before. The string parameter parser already rejected them.
v1.1.1.0
The first release of the 1.x line.
About the version number
OpenAPV versions are APISET.MAJOR.MINOR.PATCH. The first component is the API set, not a semantic-versioning major. v0.3.0.0 was the last release of API set 0; this is the first release that carries API set 1.
API set 0 is unchanged and remains fully supported. Nothing was removed.
Decoder API set 1: PBU-based decoding
oapvd_decode() decodes a whole access unit in one call. API set 1 lets an application walk the bitstream PBU by PBU and decide what to do with each one.
Seven new entry points:
oapvd_info_pbu() |
PBU type and group ID, without decoding |
oapvd_info_frame() |
frame format and tile grid, without decoding |
oapvd_info_tile() |
per-tile dimensions, and each tile's location in the PBU |
oapvd_decode_auinfo() |
access unit information |
oapvd_decode_frame() |
one frame PBU into an oapv_imgb_t |
oapvd_decode_tiles() |
a chosen set of tiles, each into its own buffer |
oapvd_decode_metadata() |
one metadata PBU into an oapvm_t container |
oapvd_decode_tiles() is what makes a partial decode cheap: each tile gets a destination sized to a tile rather than to the picture, so a viewport-driven client allocates for its tile budget instead of for the frame. When the frame header carries the tile sizes â written by default â every tile is located from the header alone and unselected tiles are never touched. Combined with a memory-mapped access unit, only the pages the selected tiles occupy are read.
oapvd_decode_metadata() stores every payload of a metadata PBU into a container under the PBU's group ID, so HDR10 and user-defined metadata are read back with oapvm_get_all() exactly as after oapvd_decode().
See Decoder API in the Programmer's Guide.
APV Extensions: UNCONST profiles
Seven profiles without the tile partitioning constraints of RFC 9924:
422-10-UNCONST, 422-12-UNCONST, 444-10-UNCONST, 444-12-UNCONST,
4444-10-UNCONST, 4444-12-UNCONST, 400-10-UNCONST. Smaller tiles give
more parallelism and finer-grained partial decoding. See
APV Extensions.
Custom memory allocator
oapve_cdesc_t and oapvd_cdesc_t gained an ops_mem field. Point it at your own allocator to keep the codec off the C library heap, or leave it NULL for the standard behaviour.
Performance
- AVX2 and NEON implementations of
oapv_blk_to_pic_16() - Tile scheduling made linear instead of quadratic
- New NEON
oapv_dc_removed_had8x8() - SIMD kernel cleanup, and an always-waiting thread removed from the encoder pool
Correctness and robustness
- Fixed MD5 frame hash mismatch on big-endian systems (s390x)
- DC coefficient differences beyond 16 bits are allowed and validated
- Fixed truncated size and stale capacity in tile array allocation
oapvd_decode_frame()works more than once per decoder instance- QP bounds derived from the coded bit depth instead of a hardcoded 10 bits
- Extensive input validation hardening across decoder, encoder and library
Build and packaging
- Source release tarballs are signed with Sigstore
- Bitstream buffers sized from resolution instead of a fixed 128 MiB
- pkg-config include paths and library install location fixed for non-default prefixes
- CMake fixes for older toolchains
- CI now builds and tests on ARM64 and s390x
Upgrading from v0.3.0.0
No public function was removed, and none changed signature. Applications recompile against the new header because oapve_cdesc_t and oapvd_cdesc_t grew a field; zero the descriptor or set ops_mem to NULL to keep the previous allocator behaviour.
If you have been tracking main rather than a release, note that oapvd_decode_frame() lost its num_part_tiles / part_tile_idxs arguments â tile subset decoding is now oapvd_decode_tiles().
v0.3.0.0
v0.2.1.3
- Validates that the image buffer has enough space for the decoded image
- Fixes wrong version number of the previous tag