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

[Thomas Guillem]

On Mon, Dec 14, 2015, at 16:53, Thomas Guillem wrote:
> ---
>  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.

And I just saw that there is a BLOCK_FLAG_END_OF_SEQUENCE flag (used by
few decoders)...

Could we merge BLOCK_FLAG_END_OF_SEQUENCE and draining via pf_decode ?
Or this is 2 differents use case.


> -- 
> 2.1.4
>