oggstreampacketin

oggstreampacketin, commonly known in the C API as ogg_stream_packetin, is a function in the libogg library used to submit a packet to an Ogg stream. It is part of the low-level stream management tools that assemble packets into the Ogg page structure.

The function takes two parameters: a pointer to an initialized ogg_stream_state that represents the current position in the logical bitstream, and a pointer to an ogg_packet containing the data to be queued. Its main purpose is to insert the provided packet into the stream’s internal buffers, handling the segmentation of the packet into the stream’s lacing values so that pages can be formed later. It does not itself emit a page; page generation is performed by ogg_stream_pageout or related functions.

A typical usage pattern is to initialize a stream with ogg_stream_init, then repeatedly call ogg_stream_packetin for each incoming packet. After packets are queued, the application can call ogg_stream_pageout to produce complete pages for transmission or storage. The finalization of the stream may involve forcing a flush with ogg_stream_flush to emit any partial pages, often accompanied by setting the end-of-stream flag.

Return values indicate success or error; on successful queuing, the function typically returns 0. Non-zero return values indicate an error condition, such as invalid state or memory allocation failure.

See also ogg_stream_packetout (retrieves packets), ogg_stream_pageout (emits complete pages), ogg_stream_flush (forces emission of partial pages), and the broader libogg and Ogg container format context.