lib: Add libvlc_picture API

This API is mostly meant to simplify thumbnailing management, by
exposing a simple picture type, that can be probed for its buffer or
saved to a file

include/vlc/libvlc_picture.h

@@ -0,0 +1,127 @@
+/*****************************************************************************
+ * libvlc_picture.h:  libvlc external API
+ *****************************************************************************
+ * Copyright (C) 2018 VLC authors and VideoLAN
+ *
+ * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2.1 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
+ *****************************************************************************/
+
+#ifndef VLC_LIBVLC_PICTURE_H
+#define VLC_LIBVLC_PICTURE_H 1
+
+# ifdef __cplusplus
+extern "C" {
+# endif
+
+typedef struct libvlc_picture_t libvlc_picture_t;
+
+typedef enum libvlc_picture_type_t
+{
+    libvlc_picture_Argb,
+    libvlc_picture_Png,
+    libvlc_picture_Jpg,
+} libvlc_picture_type_t;
+
+/**
+ * Increment the reference count of this picture.
+ *
+ * \see libvlc_picture_release()
+ * \param pic A picture object
+ */
+LIBVLC_API void
+libvlc_picture_retain( libvlc_picture_t* pic );
+
+/**
+ * Decrement the reference count of this picture.
+ * When the reference count reaches 0, the picture will be released.
+ * The picture must not be accessed after calling this function.
+ *
+ * \see libvlc_picture_retain
+ * \param pic A picture object
+ */
+LIBVLC_API void
+libvlc_picture_release( libvlc_picture_t* pic );
+
+/**
+ * Saves this picture to a file. The image format is the same as the one
+ * returned by \link libvlc_picture_type \endlink
+ *
+ * \param pic A picture object
+ * \param path The path to the generated file
+ * \return 0 in case of success, -1 otherwise
+ */
+LIBVLC_API int
+libvlc_picture_save( const libvlc_picture_t* pic, const char* path );
+
+/**
+ * Returns the image internal buffer, including potential padding.
+ * The libvlc_picture_t owns the returned buffer, which must not be modified nor
+ * freed.
+ *
+ * \param pic A picture object
+ * \param size A pointer to a size_t that will hold the size of the buffer [required]
+ * \return A pointer to the internal buffer.
+ */
+LIBVLC_API const unsigned char*
+libvlc_picture_get_buffer( const libvlc_picture_t* pic, size_t *size );
+
+/**
+ * Returns the picture type
+ *
+ * \param pic A picture object
+ * \see libvlc_picture_type_t
+ */
+LIBVLC_API libvlc_picture_type_t
+libvlc_picture_type( const libvlc_picture_t* pic );
+
+/**
+ * Returns the image stride, ie. the number of bytes per line.
+ * This can only be called on images of type libvlc_picture_Argb
+ *
+ * \param pic A picture object
+ */
+LIBVLC_API unsigned int
+libvlc_picture_get_stride( const libvlc_picture_t* pic );
+
+/**
+ * Returns the width of the image in pixels
+ *
+ * \param pic A picture object
+ */
+LIBVLC_API unsigned int
+libvlc_picture_get_width( const libvlc_picture_t* pic );
+
+/**
+ * Returns the height of the image in pixels
+ *
+ * \param pic A picture object
+ */
+LIBVLC_API unsigned int
+libvlc_picture_get_height( const libvlc_picture_t* pic );
+
+/**
+ * Returns the time at which this picture was generated, in milliseconds
+ * \param pic A picture object
+ */
+LIBVLC_API libvlc_time_t
+libvlc_picture_get_time( const libvlc_picture_t* pic );
+
+# ifdef __cplusplus
+}
+# endif
+
+#endif // VLC_LIBVLC_PICTURE_H

lib/Makefile.am

@@ -19,6 +19,7 @@ pkginclude_HEADERS = \
 	../include/vlc/libvlc_media_list_player.h \
 	../include/vlc/libvlc_media_player.h \
 	../include/vlc/libvlc_renderer_discoverer.h \
+	../include/vlc/libvlc_picture.h \
 	../include/vlc/vlc.h
 
 nodist_pkginclude_HEADERS = ../include/vlc/libvlc_version.h
@@ -34,6 +35,7 @@ libvlc_la_SOURCES = \
 	media_internal.h \
 	media_list_internal.h \
 	media_player_internal.h \
+	picture_internal.h \
 	renderer_discoverer_internal.h \
 	core.c \
 	dialog.c \
@@ -50,7 +52,8 @@ libvlc_la_SOURCES = \
 	media_list_path.h \
 	media_list_player.c \
 	media_library.c \
-	media_discoverer.c
+	media_discoverer.c \
+	picture.c
 EXTRA_DIST = libvlc.pc.in libvlc.sym ../include/vlc/libvlc_version.h.in
 
 libvlc_la_LIBADD = ../src/libvlccore.la ../compat/libcompat.la $(LIBM)

lib/libvlc.sym

@@ -262,3 +262,12 @@ libvlc_set_exit_handler
 libvlc_audio_filter_list_get
 libvlc_video_filter_list_get
 libvlc_module_description_list_release
+libvlc_picture_retain
+libvlc_picture_release
+libvlc_picture_save
+libvlc_picture_get_buffer
+libvlc_picture_type
+libvlc_picture_get_stride
+libvlc_picture_get_width
+libvlc_picture_get_height
+libvlc_picture_get_time

lib/picture.c

@@ -0,0 +1,139 @@
+/*****************************************************************************
+ * picture.c:  libvlc API picture management
+ *****************************************************************************
+ * Copyright (C) 2018 VLC authors and VideoLAN
+ *
+ * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2.1 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
+ *****************************************************************************/
+
+#ifdef HAVE_CONFIG_H
+# include "config.h"
+#endif
+
+#include <vlc/libvlc.h>
+#include <vlc/libvlc_picture.h>
+
+#include <vlc_atomic.h>
+#include <vlc_picture.h>
+#include <vlc_block.h>
+#include <vlc_fs.h>
+
+#include "picture_internal.h"
+
+struct libvlc_picture_t
+{
+    vlc_atomic_rc_t rc;
+    libvlc_picture_type_t type;
+    block_t* converted;
+    video_format_t fmt;
+    libvlc_time_t time;
+};
+
+libvlc_picture_t* libvlc_picture_new( vlc_object_t* p_obj, picture_t* input,
+                                      libvlc_picture_type_t type,
+                                      unsigned int width, unsigned int height )
+{
+    libvlc_picture_t *pic = malloc( sizeof( *pic ) );
+    if ( unlikely( pic == NULL ) )
+        return NULL;
+    vlc_atomic_rc_init( &pic->rc );
+    pic->type = type;
+    pic->time = MS_FROM_VLC_TICK( input->date );
+    vlc_fourcc_t format;
+    switch ( type )
+    {
+        case libvlc_picture_Argb:
+            format = VLC_CODEC_ARGB;
+            break;
+        case libvlc_picture_Jpg:
+            format = VLC_CODEC_JPEG;
+            break;
+        case libvlc_picture_Png:
+            format = VLC_CODEC_PNG;
+            break;
+        default:
+            vlc_assert_unreachable();
+    }
+    if ( picture_Export( p_obj, &pic->converted, &pic->fmt,
+                         input, format, width, height ) != VLC_SUCCESS )
+    {
+        free( pic );
+        return NULL;
+    }
+
+    return pic;
+}
+
+void libvlc_picture_retain( libvlc_picture_t* pic )
+{
+    vlc_atomic_rc_inc( &pic->rc );
+}
+
+void libvlc_picture_release( libvlc_picture_t* pic )
+{
+    if ( vlc_atomic_rc_dec( &pic->rc ) == false )
+        return;
+    video_format_Clean( &pic->fmt );
+    if ( pic->converted )
+        block_Release( pic->converted );
+    free( pic );
+}
+
+int libvlc_picture_save( const libvlc_picture_t* pic, const char* path )
+{
+    FILE* file = vlc_fopen( path, "wb" );
+    if ( !file )
+        return -1;
+    size_t res = fwrite( pic->converted->p_buffer,
+                         pic->converted->i_buffer, 1, file );
+    fclose( file );
+    return res == 1 ? 0 : -1;
+}
+
+const unsigned char* libvlc_picture_get_buffer( const libvlc_picture_t* pic,
+                                                size_t *size )
+{
+    assert( size != NULL );
+    *size = pic->converted->i_buffer;
+    return pic->converted->p_buffer;
+}
+
+libvlc_picture_type_t libvlc_picture_type( const libvlc_picture_t* pic )
+{
+    return pic->type;
+}
+
+unsigned int libvlc_picture_get_stride( const libvlc_picture_t *pic )
+{
+    assert( pic->type == libvlc_picture_Argb );
+    return pic->fmt.i_width * pic->fmt.i_bits_per_pixel / 8;
+}
+
+unsigned int libvlc_picture_get_width( const libvlc_picture_t* pic )
+{
+    return pic->fmt.i_visible_width;
+}
+
+unsigned int libvlc_picture_get_height( const libvlc_picture_t* pic )
+{
+    return pic->fmt.i_visible_height;
+}
+
+libvlc_time_t libvlc_picture_get_time( const libvlc_picture_t* pic )
+{
+    return pic->time;
+}

lib/picture_internal.h

@@ -0,0 +1,45 @@
+/*****************************************************************************
+ * picture_internal.h:  libvlc API picture management
+ *****************************************************************************
+ * Copyright (C) 1998-2018 VLC authors and VideoLAN
+ *
+ * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2.1 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
+ *****************************************************************************/
+
+#ifndef PICTURE_INTERNAL_H
+#define PICTURE_INTERNAL_H
+
+#include <vlc_picture.h>
+
+/**
+ * \brief libvlc_picture_new Wraps a libvlccore's picture_t to a libvlc_picture_t
+ * \param p_obj A vlc object
+ * \param p_input Input picture
+ * \param i_type Desired converted picture type
+ * \param i_width Converted picture width
+ * \param i_height Converted picture height
+ * \return An opaque libvlc_picture_t
+ *
+ * The picture refcount is left untouched by this function, but is converted to
+ * the required format and stored as a block_t
+ * The returned picture must be released through libvlc_picture_release
+ */
+libvlc_picture_t* libvlc_picture_new( vlc_object_t* p_obj, picture_t* p_pic,
+                                      libvlc_picture_type_t i_format,
+                                      unsigned int i_width, unsigned int i_height );
+
+#endif /* PICTURE_INTERNAL_H */