[FFmpeg] decoding and demuxing improvements (davisking#2784)

* typo

* - added compile time information to audio object. Not convinced this is needed actually. I'm perfectly happy just using the ffmpeg::frame object. I'm pretty sure I'm the only user who cares about audio.
- created resizing_args and resampling_args

* smaller videos for unit tests

* shorter videos for unit tests

* - decoder and demuxer: you now resize or resample at the time of read. therefore you don't set resizing or resampling parameters in constructor, but you pass them to read()
- added templated read() function
- simplified load_frame()

* inherit from resizing_args and resampling_args

* reorganised the tests to segragate decoding, demuxing, encoding and muxing as much as possible

* much more basic example

* demxing examples split

* examples

* fixing examples

* wip

* Fix load_frame()

* added frame - specific tests

* - makes sense to have a set_params() method rather than constructing a new object and moving. I mean, it works and it absolutely does the right thing, and in fact the same thing as calling set_params() now, but it can look a bit weird.

* notes on defaults and good pairings

* Update ffmpeg_demuxer.h

Watch out for `DLIB_ASSERT` statements. Maybe one of the unit tests should build with asserts enabled.

* Update ffmpeg_details.h

* Update ffmpeg_muxer.h

* WIP

* WIP

* - simplified details::resizer
- added frame::set_params()
- added frame::clear()
- forward packet directly into correct queue

* pick best codec if not specified

* added image data

* warn when we're choosing an appropriate codec

* test load_frame()

* - for some reason, you sometimes get warning messages about too many b-frames. Resetting pict_type suppresses this.
- you can move freshly decoded frames directly out.

* callback passed to push()

* I think it's prettier this way

* WIP

* full callback API for decoder

* updated tests

* updated example

* check the template parameter is callable and has 1 argument first before getting it's first argument

* Potential bug fix

* - write out the enable_if's explictly. It's fine. I think it's clear what's going on if someone cares
- guard push() with a boolean which asserts when recursion is detected

* pre-conditions on callbacks: no recursion

---------

Co-authored-by: pf <pf@me>
Co-authored-by: Your name <[email protected]>

dlib/media/ffmpeg_details.h

@@ -20,15 +20,15 @@
         - ffmpeg_details.h  : contains implementations details only and everything must be in the
                               dlib::ffmpeg::details namespace
         
-        - ffmpeg_utils.h    : contains common public API. Declarations go at the bottom of the file
+        - ffmpeg_utils.h    : contains common public API. Definitions go at the bottom of the file
                               underneath a block comment saying "DEFINITIONS"
                               Also contains implementation details that depend on the public API.
                               This must still go in the dlib::ffmpeg::details namespace
         
-        - ffmpeg_demuxer.h  : contains public API for all things decoding. Similarly, declarations go 
+        - ffmpeg_demuxer.h  : contains public API for all things decoding. Similarly, definitions go 
                               at the bottom of the file underneath a block comment saying "DEFINITIONS".
 
-        - ffmpeg_muxer.h  :   contains public API for all things encoding. Similarly, declarations go 
+        - ffmpeg_muxer.h  :   contains public API for all things encoding. Similarly, definitions go 
                               at the bottom of the file underneath a block comment saying "DEFINITIONS".
                             
 */
@@ -239,12 +239,12 @@ namespace dlib { namespace ffmpeg { namespace details
 
     inline uint64_t get_layout(const AVCodecContext* pCodecCtx)
     {
-        return pCodecCtx->ch_layout.u.mask;
+        return pCodecCtx ? pCodecCtx->ch_layout.u.mask : 0;
     }
 
     inline uint64_t get_layout(const AVFrame* frame)
     {
-        return frame->ch_layout.u.mask;
+        return frame ? frame->ch_layout.u.mask : 0;
     }
 
     inline void set_layout(AVCodecContext* pCodecCtx, const uint64_t channel_layout)
@@ -259,12 +259,12 @@ namespace dlib { namespace ffmpeg { namespace details
 
     inline int get_nchannels(const AVCodecContext* pCodecCtx)
     {
-        return pCodecCtx->ch_layout.nb_channels;
+        return pCodecCtx ? pCodecCtx->ch_layout.nb_channels : 0;
     }
 
     inline int get_nchannels(const AVFrame* frame)
     {
-        return frame->ch_layout.nb_channels;
+        return frame ? frame->ch_layout.nb_channels : 0;
     }
 
     inline int get_nchannels(const uint64_t channel_layout)
@@ -305,12 +305,12 @@ namespace dlib { namespace ffmpeg { namespace details
 
     inline uint64_t get_layout(const AVCodecContext* pCodecCtx)
     {
-        return pCodecCtx->channel_layout;
+        return pCodecCtx ? pCodecCtx->channel_layout : 0;
     }
 
     inline uint64_t get_layout(const AVFrame* frame)
     {
-        return frame->channel_layout;
+        return frame ? frame->channel_layout : 0;
     }
 
     inline void set_layout(AVCodecContext* pCodecCtx, const uint64_t channel_layout)
@@ -330,12 +330,12 @@ namespace dlib { namespace ffmpeg { namespace details
 
     inline int get_nchannels(const AVCodecContext* pCodecCtx)
     {
-        return get_nchannels(pCodecCtx->channel_layout);
+        return pCodecCtx ? get_nchannels(pCodecCtx->channel_layout) : 0;
     }
 
     inline int get_nchannels(const AVFrame* frame)
     {
-        return get_nchannels(frame->channel_layout);
+        return frame ? get_nchannels(frame->channel_layout) : 0;
     }    
 
     inline void check_layout(AVCodecContext* pCodecCtx) 
@@ -484,4 +484,4 @@ namespace dlib { namespace ffmpeg { namespace details
 
 }}}
 
-#endif //DLIB_FFMPEG_DETAILS
+#endif //DLIB_FFMPEG_DETAILS