Skip to content

Update the README and the programmers guide - #262

Open
kpchoi wants to merge 1 commit into
mainfrom
docs_related_spec
Open

Update the README and the programmers guide#262
kpchoi wants to merge 1 commit into
mainfrom
docs_related_spec

Conversation

@kpchoi

@kpchoi kpchoi commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Documentation updates across the README and the programmers guide. No code change.

Specification references

  • The APV codec bitstream specification now points at RFC 9924 instead of the superseded individual draft, and the "Scope of OpenAPV project" sub-bullet is dropped.
  • The RTP payload format now points at the working group draft draft-ietf-avtcore-rtp-apv, which has replaced the individual draft-lim-rtp-apv.
  • APV Family and APV Extensions are listed in the related specification section as well.
  • "APV Profile Extensions" becomes "APV Extensions" in the features list and in the document title, and readme/profile_ext.md is renamed to readme/apv_ext.md (recorded as a git rename, so history is preserved). No remaining references to the old name.

Features list

  • Gains a tile-based partial decoding entry.
  • The extensions entry now names what the extension profiles are: 444-16C12 and 4444-16C12 for 16-bit source companded to 12-bit, and the UNCONST profiles without the tile partitioning constraints. The RFC 9924 compliance line is unchanged, since RFC 9924 defines exactly the seven profiles it lists.

Application examples

The encoder had two example lines and the decoder one. The encoder section now covers raw versus Y4M input, quality selection (fixed QP with a preset, target bitrate, APV Family), profile selection, RGB content, tiles and threads including an extension profile with small tiles, reconstruction output with a frame hash, and encoding a part of the input. The decoder section covers Y4M and raw output, hash verification and decoding without output, bit depth and P210 conversion, limiting access units with a thread count, and PBU-based decoding with tile-based partial decoding. Every command was run against the sample sequence before being documented.

Programmers guide: common types

The section listed four types and left out the ones a reader meets first, including the instance handles oapve_t and oapvd_t. It now groups the types a caller works with and says what each is for:

  • instance handles (oapve_t, oapvd_t, oapvm_t) with their create and delete functions, what state each holds, and the note that an instance is not internally serialized, so one instance per encoding or decoding thread
  • creation descriptors (oapve_cdesc_t, oapvd_cdesc_t, oapvm_cdesc_t), which configure an instance at create time
  • oapve_param_t on its own, since it is the encoder setting structure rather than a descriptor, noting that it starts from oapve_param_default() and that most of it can be changed per frame at run time with oapve_config()
  • application-owned buffers (oapv_imgb_t, oapv_bitb_t including the bsize versus ssize distinction, oapv_frm_t / oapv_frms_t with the pbu_type values and the role of group_id)
  • types the library fills (oapve_stat_t / oapvd_stat_t, oapv_au_info_t, oapv_frm_info_t, oapv_tile_pos_t, oapvm_payload_t)

Every description was checked against the declarations in oapv.h.

Programmers guide: type members and structure

Each type the guide lists now has a table of its members and what they are for: the creation descriptors, oapve_param_t, oapv_imgb_t, oapv_bitb_t, oapv_frm_t / oapv_frms_t, oapve_stat_t / oapvd_stat_t, oapv_frm_info_t, oapv_tile_pos_t and oapvm_payload_t. Every member name was cross-checked against the declarations in oapv.h, which is not modified by this PR.

The sections "Writing an encoder" and "Writing a decoder" become "Encoder API" and "Decoder API", since the old titles read as if they were about writing prose rather than calling the library, and the introduction and the README pointer are reworded to match. The guide is also reordered so that each topic sits under the API it belongs to: "Encoding RGB content" becomes a subsection of the encoder API, "Zero-copy decoding input with memory-mapped files" a subsection of the decoder API, and the combined "Runtime configuration" section is split into an encoder part covering oapve_config() and a decoder part covering oapvd_config(), each under its own API.

Graphic logo

The black logo and the white logo are each meant for the opposite background, so on any given page one of them blends in and looks blank. A short note now says so and suggests dragging over it, or opening the image file, to see it.

@kpchoi
kpchoi force-pushed the docs_related_spec branch 3 times, most recently from c43509d to 8f480e2 Compare August 8, 2026 05:17
@kpchoi kpchoi changed the title Update related specification links and rename the extensions document Update the README and the programmers guide Aug 8, 2026
@kpchoi
kpchoi force-pushed the docs_related_spec branch 7 times, most recently from 0946b84 to 7a5a27a Compare August 8, 2026 05:59
Signed-off-by: KP Choi <kp5.choi@samsung.com>
@kpchoi
kpchoi force-pushed the docs_related_spec branch from 7a5a27a to f70ad98 Compare August 8, 2026 06:03
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.

1 participant