Message ID | 20220222062757.20908-1-anton@khirnov.net |
---|---|
State | Accepted |
Commit | 5e7643eff795609bd3878c99277859a56e884135 |
Headers | show |
Series | [FFmpeg-devel,1/2] lavc/bsf: add general documentation | expand |
On 2/22/2022 3:27 AM, Anton Khirnov wrote: > Also, place the BSF api docs in their own doxygen group. > --- > libavcodec/bsf.h | 23 ++++++++++++++++++++++- > 1 file changed, 22 insertions(+), 1 deletion(-) > > diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h > index 8c5355d186..ba8b48f222 100644 > --- a/libavcodec/bsf.h > +++ b/libavcodec/bsf.h > @@ -30,7 +30,28 @@ > #include "packet.h" > > /** > - * @addtogroup lavc_core > + * @defgroup lavc_bsf Bitstream filters > + * @ingroup libavc > + * > + * Bitstream filters transform encoded media data without decoding it. This > + * allows e.g. manipulating various header values. Bitstream filters operate on > + * @ref AVPacket "AVPackets". > + * > + * The bitstream filtering API is centered around two structures: > + * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter Could use @ref here and below, too. > + * in abstract, the latter a specific filtering process. Obtain an > + * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass > + * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable > + * AVBSFContext fields, as described in its documentation, then call > + * av_bsf_init() to prepare the filter context for use. > + * > + * Submit packets for filtering using av_bsf_send_packet(), obtain filtered > + * results with av_bsf_receive_packet(). When no more input packets will be > + * sent, submit a NULL AVPacket to signal the end of the stream to the filter. The doxy for av_bsf_send_packet() states the packet must be "empty", meaning either "NULL, or pkt->data is NULL and pkt->side_data_elems zero", so probably mention the same here so it's consistent. > + * av_bsf_receive_packet() will then return trailing packets, if any are > + * produced by the filter. > + * > + * Finally, free the filter context with av_bsf_free(). > * @{ > */ LGTM otherwise.
Quoting James Almer (2022-02-22 18:09:59) > > > On 2/22/2022 3:27 AM, Anton Khirnov wrote: > > Also, place the BSF api docs in their own doxygen group. > > --- > > libavcodec/bsf.h | 23 ++++++++++++++++++++++- > > 1 file changed, 22 insertions(+), 1 deletion(-) > > > > diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h > > index 8c5355d186..ba8b48f222 100644 > > --- a/libavcodec/bsf.h > > +++ b/libavcodec/bsf.h > > @@ -30,7 +30,28 @@ > > #include "packet.h" > > > > /** > > - * @addtogroup lavc_core > > + * @defgroup lavc_bsf Bitstream filters > > + * @ingroup libavc > > + * > > + * Bitstream filters transform encoded media data without decoding it. This > > + * allows e.g. manipulating various header values. Bitstream filters operate on > > + * @ref AVPacket "AVPackets". > > + * > > + * The bitstream filtering API is centered around two structures: > > + * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter > > Could use @ref here and below, too. That happens automatically when you write a struct name. > > > + * in abstract, the latter a specific filtering process. Obtain an > > + * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass > > + * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable > > + * AVBSFContext fields, as described in its documentation, then call > > + * av_bsf_init() to prepare the filter context for use. > > + * > > + * Submit packets for filtering using av_bsf_send_packet(), obtain filtered > > + * results with av_bsf_receive_packet(). When no more input packets will be > > + * sent, submit a NULL AVPacket to signal the end of the stream to the filter. > > The doxy for av_bsf_send_packet() states the packet must be "empty", > meaning either "NULL, or pkt->data is NULL and pkt->side_data_elems > zero", so probably mention the same here so it's consistent. The idea here is to provide a quick overview of the API rather than be exhaustive. In retrospect I regard allowing both NULL and "empty packet" (for some quite nontrivial definition of empty, given side-data-only packets) as a mistake, allowing only NULL would be cleaner and less confusing.
On 3/16/2022 8:36 AM, Anton Khirnov wrote: > Quoting James Almer (2022-02-22 18:09:59) >> >> >> On 2/22/2022 3:27 AM, Anton Khirnov wrote: >>> Also, place the BSF api docs in their own doxygen group. >>> --- >>> libavcodec/bsf.h | 23 ++++++++++++++++++++++- >>> 1 file changed, 22 insertions(+), 1 deletion(-) >>> >>> diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h >>> index 8c5355d186..ba8b48f222 100644 >>> --- a/libavcodec/bsf.h >>> +++ b/libavcodec/bsf.h >>> @@ -30,7 +30,28 @@ >>> #include "packet.h" >>> >>> /** >>> - * @addtogroup lavc_core >>> + * @defgroup lavc_bsf Bitstream filters >>> + * @ingroup libavc >>> + * >>> + * Bitstream filters transform encoded media data without decoding it. This >>> + * allows e.g. manipulating various header values. Bitstream filters operate on >>> + * @ref AVPacket "AVPackets". >>> + * >>> + * The bitstream filtering API is centered around two structures: >>> + * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter >> >> Could use @ref here and below, too. > > That happens automatically when you write a struct name. > >> >>> + * in abstract, the latter a specific filtering process. Obtain an >>> + * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass >>> + * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable >>> + * AVBSFContext fields, as described in its documentation, then call >>> + * av_bsf_init() to prepare the filter context for use. >>> + * >>> + * Submit packets for filtering using av_bsf_send_packet(), obtain filtered >>> + * results with av_bsf_receive_packet(). When no more input packets will be >>> + * sent, submit a NULL AVPacket to signal the end of the stream to the filter. >> >> The doxy for av_bsf_send_packet() states the packet must be "empty", >> meaning either "NULL, or pkt->data is NULL and pkt->side_data_elems >> zero", so probably mention the same here so it's consistent. > > The idea here is to provide a quick overview of the API rather than be > exhaustive. In retrospect I regard allowing both NULL and "empty packet" > (for some quite nontrivial definition of empty, given side-data-only > packets) as a mistake, allowing only NULL would be cleaner and less > confusing. Ok, LGTM then.
diff --git a/libavcodec/bsf.h b/libavcodec/bsf.h index 8c5355d186..ba8b48f222 100644 --- a/libavcodec/bsf.h +++ b/libavcodec/bsf.h @@ -30,7 +30,28 @@ #include "packet.h" /** - * @addtogroup lavc_core + * @defgroup lavc_bsf Bitstream filters + * @ingroup libavc + * + * Bitstream filters transform encoded media data without decoding it. This + * allows e.g. manipulating various header values. Bitstream filters operate on + * @ref AVPacket "AVPackets". + * + * The bitstream filtering API is centered around two structures: + * AVBitStreamFilter and AVBSFContext. The former represents a bitstream filter + * in abstract, the latter a specific filtering process. Obtain an + * AVBitStreamFilter using av_bsf_get_by_name() or av_bsf_iterate(), then pass + * it to av_bsf_alloc() to create an AVBSFContext. Fill in the user-settable + * AVBSFContext fields, as described in its documentation, then call + * av_bsf_init() to prepare the filter context for use. + * + * Submit packets for filtering using av_bsf_send_packet(), obtain filtered + * results with av_bsf_receive_packet(). When no more input packets will be + * sent, submit a NULL AVPacket to signal the end of the stream to the filter. + * av_bsf_receive_packet() will then return trailing packets, if any are + * produced by the filter. + * + * Finally, free the filter context with av_bsf_free(). * @{ */