diff mbox

[FFmpeg-devel] avcodec/avcodec: Adapt the doc of av_bsf_send_packet

Message ID 20191114144415.23841-1-andreas.rheinhardt@gmail.com
State Accepted
Headers show

Commit Message

Andreas Rheinhardt Nov. 14, 2019, 2:44 p.m. UTC
to match its actual implementation.

Explicitly allowing empty packets to signal flushing helps getting rid
of special cases. It does not hinder the ability to send i.e.
timing-only packets, because one can send packets with zero size and
pkt->data set.

Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@gmail.com>
---
I used "vanish" as an umbrella term for "being NULL or zero"
(pkt->side_data_elems is an int). Maybe using C directly (i.e.
!pkt->data) would be more clear? It would certainly be briefer.

 libavcodec/avcodec.h | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

Comments

James Almer Nov. 14, 2019, 3:04 p.m. UTC | #1
On 11/14/2019 11:44 AM, Andreas Rheinhardt wrote:
> to match its actual implementation.
> 
> Explicitly allowing empty packets to signal flushing helps getting rid
> of special cases. It does not hinder the ability to send i.e.
> timing-only packets, because one can send packets with zero size and
> pkt->data set.
> 
> Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt@gmail.com>
> ---
> I used "vanish" as an umbrella term for "being NULL or zero"
> (pkt->side_data_elems is an int). Maybe using C directly (i.e.
> !pkt->data) would be more clear? It would certainly be briefer.
> 
>  libavcodec/avcodec.h | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index bcb931f0dd..82f04f1130 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -5946,11 +5946,13 @@ int av_bsf_init(AVBSFContext *ctx);
>   *
>   * @param pkt the packet to filter. The bitstream filter will take ownership of
>   * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
> - * This parameter may be NULL, which signals the end of the stream (i.e. no more
> - * packets will be sent). That will cause the filter to output any packets it
> - * may have buffered internally.
> + * If pkt is empty (i.e. NULL or pkt->data is NULL and pkt->side_data_elems zero),
> + * it signals the end of the stream (i.e. no more non-empty packets will be sent;
> + * sending more empty packets does nothing) and will cause the filter to output
> + * any packets it may have buffered internally.
>   *
>   * @return 0 on success, a negative AVERROR on error.
> + *         This function never fails if pkt is empty.
>   */
>  int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt);

Applied, thanks.
diff mbox

Patch

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index bcb931f0dd..82f04f1130 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -5946,11 +5946,13 @@  int av_bsf_init(AVBSFContext *ctx);
  *
  * @param pkt the packet to filter. The bitstream filter will take ownership of
  * the packet and reset the contents of pkt. pkt is not touched if an error occurs.
- * This parameter may be NULL, which signals the end of the stream (i.e. no more
- * packets will be sent). That will cause the filter to output any packets it
- * may have buffered internally.
+ * If pkt is empty (i.e. NULL or pkt->data is NULL and pkt->side_data_elems zero),
+ * it signals the end of the stream (i.e. no more non-empty packets will be sent;
+ * sending more empty packets does nothing) and will cause the filter to output
+ * any packets it may have buffered internally.
  *
  * @return 0 on success, a negative AVERROR on error.
+ *         This function never fails if pkt is empty.
  */
 int av_bsf_send_packet(AVBSFContext *ctx, AVPacket *pkt);