[vlc-devel] [PATCH 1/2] vlc_codec: document pf_decoder_* and pf_packetize

[Thomas Guillem]

---
 include/vlc_codec.h | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/include/vlc_codec.h b/include/vlc_codec.h
index 9927ec1..dfeceec 100644
--- a/include/vlc_codec.h
+++ b/include/vlc_codec.h
@@ -65,11 +65,36 @@ struct decoder_t
     /* Tell the decoder if it is allowed to drop frames */
     bool                b_frame_drop_allowed;
 
+    /* All pf_decode_* and pf_packetize functions have the same behavior.
+     *
+     * These functions are called in a loop with the same pp_block argument
+     * until they return NULL. This allows a module implementation to return
+     * more than one frames/samples for one input block.
+     *
+     * pp_block or *pp_block can be NULL.
+     *
+     * If pp_block and *pp_block are not NULL, the module implementation will
+     * own the input block (*pp_block) and should process and release it. The
+     * module should also set the *pp_block to NULL when it releases it.
+     *
+     * If pp_block is not NULL but *pp_block is NULL, a previous call of the pf
+     * function set the *pp_block to NULL. Here, the module can return new
+     * frames/samples for the same, already processed, input block (the pf
+     * function will be called as long as the module return a frame).
+     *
+     * When the pf fonction returns NULL, the next call to this function will
+     * have a new pp_block argument with a valid pp_block (if not drained).
+     *
+     * If pp_block is NULL, the module implementation should drain the
+     * decoder/packetizer. Therefore, the module has to return all
+     * frames/samples available (the pf function will be called as long as the
+     * module return a frame).
+     */
+    picture_t *         ( * pf_decode_video )( decoder_t *, block_t **pp_block );
+    block_t *           ( * pf_decode_audio )( decoder_t *, block_t **pp_block );
+    subpicture_t *      ( * pf_decode_sub)   ( decoder_t *, block_t **pp_block );
+    block_t *           ( * pf_packetize )   ( decoder_t *, block_t **pp_block );
     /* */
-    picture_t *         ( * pf_decode_video )( decoder_t *, block_t ** );
-    block_t *           ( * pf_decode_audio )( decoder_t *, block_t ** );
-    subpicture_t *      ( * pf_decode_sub)   ( decoder_t *, block_t ** );
-    block_t *           ( * pf_packetize )   ( decoder_t *, block_t ** );
     void                ( * pf_flush ) ( decoder_t * );
 
     /* Closed Caption (CEA 608/708) extraction.
-- 
2.1.4