diff mbox series

[FFmpeg-devel] dox/examples/encode_video: add explanations in comments.

Message ID 20210816130713.28457-1-george@nsup.org
State Accepted
Commit 1698cd8422c8a363e25dd94beb61c0a6d68bd67c
Headers show
Series [FFmpeg-devel] dox/examples/encode_video: add explanations in comments. | expand

Checks

Context Check Description
andriy/x86_make success Make finished
andriy/x86_make_fate success Make fate finished
andriy/PPC64_make success Make finished
andriy/PPC64_make_fate success Make fate finished

Commit Message

Nicolas George Aug. 16, 2021, 1:07 p.m. UTC 
Signed-off-by: Nicolas George <george@nsup.org>
---
 doc/examples/encode_video.c | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

Comments

Nicolas George Aug. 20, 2021, 10:07 a.m. UTC | #1 
Nicolas George (12021-08-16):
> Signed-off-by: Nicolas George <george@nsup.org>
> ---
>  doc/examples/encode_video.c | 24 +++++++++++++++++++++---
>  1 file changed, 21 insertions(+), 3 deletions(-)

I fixed dox → doc in the subject. Will push soon unless somebody
comments.

Regards,
Jan Ekström Aug. 20, 2021, 1:19 p.m. UTC | #2 
On Mon, Aug 16, 2021 at 4:07 PM Nicolas George <george@nsup.org> wrote:
>
> Signed-off-by: Nicolas George <george@nsup.org>
> ---

Looks good to me with the dox->doc fixup you've already done in the
commit message.

Generally I've become accustomed to trying to push people to look at
the transcode* examples since I've seen people try to do things
manually which our APIs would do for them when they see these minimal
examples and try to extend them.

Best regards,
Jan
Nicolas George Aug. 20, 2021, 3:14 p.m. UTC | #3 
Jan Ekström (12021-08-20):
> Looks good to me with the dox->doc fixup you've already done in the
> commit message.

Thanks, pushed.

Regards,
diff mbox series

Patch

diff --git a/doc/examples/encode_video.c b/doc/examples/encode_video.c
index 908eb203d5..939ed68324 100644
--- a/doc/examples/encode_video.c
+++ b/doc/examples/encode_video.c
@@ -155,12 +155,25 @@  int main(int argc, char **argv)
     for (i = 0; i < 25; i++) {
         fflush(stdout);
 
-        /* make sure the frame data is writable */
+        /* Make sure the frame data is writable.
+           On the first round, the frame is fresh from av_frame_get_buffer()
+           and therefore we know it is writable.
+           But on the next rounds, encode() will have called
+           avcodec_send_frame(), and the codec may have kept a reference to
+           the frame in its internal structures, that makes the frame
+           unwritable.
+           av_frame_make_writable() checks that and allocates a new buffer
+           for the frame only if necessary.
+         */
         ret = av_frame_make_writable(frame);
         if (ret < 0)
             exit(1);
 
-        /* prepare a dummy image */
+        /* Prepare a dummy image.
+           In real code, this is where you would have your own logic for
+           filling the frame. FFmpeg does not care what you put in the
+           frame.
+         */
         /* Y */
         for (y = 0; y < c->height; y++) {
             for (x = 0; x < c->width; x++) {
@@ -185,7 +198,12 @@  int main(int argc, char **argv)
     /* flush the encoder */
     encode(c, NULL, pkt, f);
 
-    /* add sequence end code to have a real MPEG file */
+    /* Add sequence end code to have a real MPEG file.
+       It makes only sense because this tiny examples writes packets
+       directly. This is called "elementary stream" and only works for some
+       codecs. To create a valid file, you usually need to write packets
+       into a proper file format or protocol; see muxing.c.
+     */
     if (codec->id == AV_CODEC_ID_MPEG1VIDEO || codec->id == AV_CODEC_ID_MPEG2VIDEO)
         fwrite(endcode, 1, sizeof(endcode), f);
     fclose(f);