wpe: Update doc cache

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/merge_requests/2252>

3 files changed, 137 insertions, 59 deletions

diff --git a/docs/plugins/gst_plugins_cache.json b/docs/plugins/gst_plugins_cache.json
index 8059a5d55..505c6f36c 100644
--- a/docs/plugins/gst_plugins_cache.json
+++ b/docs/plugins/gst_plugins_cache.json
@@ -227331,20 +227331,102 @@
         "elements": {
             "wpesrc": {
                 "author": "Philippe Normand <philn@igalia.com>, Žan Doberšek <zdobersek@igalia.com>",
-                "description": "Creates a video stream from a WPE browser",
+                "description": "Creates Audio/Video streams from a web page using WPE web engine",
                 "hierarchy": [
                     "GstWpeSrc",
-                    "GstGLBaseSrc",
-                    "GstPushSrc",
-                    "GstBaseSrc",
+                    "GstBin",
                     "GstElement",
                     "GstObject",
                     "GInitiallyUnowned",
                     "GObject"
                 ],
                 "interfaces": [
+                    "GstChildProxy",
                     "GstURIHandler"
                 ],
+                "klass": "Source/Video/Audio",
+                "long-name": "WPE source",
+                "pad-templates": {
+                    "audio_%%u": {
+                        "caps": "audio/x-raw:\n         format: F32LE\n           rate: [ 1, 2147483647 ]\n       channels: [ 1, 2147483647 ]\n         layout: interleaved\naudio/x-raw:\n         format: F64LE\n           rate: [ 1, 2147483647 ]\n       channels: [ 1, 2147483647 ]\n         layout: interleaved\naudio/x-raw:\n         format: S16LE\n           rate: [ 1, 2147483647 ]\n       channels: [ 1, 2147483647 ]\n         layout: interleaved\n",
+                        "direction": "src",
+                        "presence": "sometimes"
+                    },
+                    "src": {
+                        "caps": "video/x-raw(memory:GLMemory):\n         format: RGBA\n          width: [ 1, 2147483647 ]\n         height: [ 1, 2147483647 ]\n      framerate: [ 0/1, 2147483647/1 ]\npixel-aspect-ratio: 1/1\n texture-target: 2D\nvideo/x-raw:\n         format: BGRA\n",
+                        "direction": "src",
+                        "presence": "always"
+                    },
+                    "video": {
+                        "caps": "video/x-raw(memory:GLMemory):\n         format: RGBA\n          width: [ 1, 2147483647 ]\n         height: [ 1, 2147483647 ]\n      framerate: [ 0/1, 2147483647/1 ]\npixel-aspect-ratio: 1/1\n texture-target: 2D\nvideo/x-raw:\n         format: BGRA\n          width: [ 1, 2147483647 ]\n         height: [ 1, 2147483647 ]\n      framerate: [ 0/1, 2147483647/1 ]\npixel-aspect-ratio: 1/1\n",
+                        "direction": "src",
+                        "presence": "sometimes"
+                    }
+                },
+                "properties": {
+                    "draw-background": {
+                        "blurb": "Whether to draw the WebView background",
+                        "conditionally-available": false,
+                        "construct": false,
+                        "construct-only": false,
+                        "controllable": false,
+                        "default": "true",
+                        "mutable": "null",
+                        "readable": true,
+                        "type": "gboolean",
+                        "writable": true
+                    },
+                    "location": {
+                        "blurb": "The URL to display",
+                        "conditionally-available": false,
+                        "construct": false,
+                        "construct-only": false,
+                        "controllable": false,
+                        "default": "NULL",
+                        "mutable": "null",
+                        "readable": true,
+                        "type": "gchararray",
+                        "writable": true
+                    }
+                },
+                "rank": "none",
+                "signals": {
+                    "configure-web-view": {
+                        "args": [
+                            {
+                                "name": "arg0",
+                                "type": "GObject"
+                            }
+                        ],
+                        "return-type": "void",
+                        "when": "last"
+                    },
+                    "load-bytes": {
+                        "action": true,
+                        "args": [
+                            {
+                                "name": "arg0",
+                                "type": "GBytes"
+                            }
+                        ],
+                        "return-type": "void",
+                        "when": "last"
+                    }
+                }
+            },
+            "wpevideosrc": {
+                "author": "Philippe Normand <philn@igalia.com>, Žan Doberšek <zdobersek@igalia.com>",
+                "description": "Creates a video stream from a WPE browser",
+                "hierarchy": [
+                    "GstWpeVideoSrc",
+                    "GstGLBaseSrc",
+                    "GstPushSrc",
+                    "GstBaseSrc",
+                    "GstElement",
+                    "GstObject",
+                    "GInitiallyUnowned",
+                    "GObject"
+                ],
                 "klass": "Source/Video",
                 "long-name": "WPE source",
                 "pad-templates": {
diff --git a/ext/wpe/gstwpe.cpp b/ext/wpe/gstwpe.cpp
index 80be4242b..ceca61e6f 100644
--- a/ext/wpe/gstwpe.cpp
+++ b/ext/wpe/gstwpe.cpp
@@ -17,46 +17,6 @@
  * Boston, MA 02110-1301, USA.
  */
 
-/**
- * SECTION:element-wpesrc
- * @title: wpesrc
- *
- * The wpesrc element is used to produce a video texture representing a web page
- * rendered off-screen by WPE.
- *
- * Starting from WPEBackend-FDO 1.6.x, software rendering support is available. This
- * features allows wpesrc to be used on machines without GPU, and/or for testing
- * purpose. To enable it, set the `LIBGL_ALWAYS_SOFTWARE=true` environment
- * variable and make sure `video/x-raw, format=BGRA` caps are negotiated by the
- * wpesrc element.
- *
- * ## Example launch lines
- *
- * |[
- * gst-launch-1.0 -v wpesrc location="https://gstreamer.freedesktop.org" ! queue ! glimagesink
- * ]|
- * Shows the GStreamer website homepage
- *
- * |[
- * LIBGL_ALWAYS_SOFTWARE=true gst-launch-1.0 -v wpesrc num-buffers=50 location="https://gstreamer.freedesktop.org" ! videoconvert ! pngenc ! multifilesink location=/tmp/snapshot-%05d.png
- * ]|
- * Saves the first 50 video frames generated for the GStreamer website as PNG files in /tmp.
- *
- * |[
- * gst-play-1.0 --videosink gtkglsink wpe://https://gstreamer.freedesktop.org
- * ]|
- * Shows the GStreamer website homepage as played with GstPlayer in a GTK+ window.
- *
- * |[
- * gst-launch-1.0  glvideomixer name=m sink_1::zorder=0 ! glimagesink wpesrc location="file:///home/phil/Downloads/plunk/index.html" draw-background=0 ! m. videotestsrc ! queue ! glupload ! glcolorconvert ! m.
- * ]|
- * Composite WPE with a video stream in a single OpenGL scene.
- *
- * |[
- * gst-launch-1.0 glvideomixer name=m sink_1::zorder=0 sink_0::height=818 sink_0::width=1920 ! gtkglsink wpesrc location="file:///home/phil/Downloads/plunk/index.html" draw-background=0 ! m. uridecodebin uri="http://192.168.1.44/Sintel.2010.1080p.mkv" name=d d. ! queue ! glupload ! glcolorconvert ! m.
- * ]|
- * Composite WPE with a video stream, sink_0 pad properties have to match the video dimensions.
- */
 
 
 #ifdef HAVE_CONFIG_H
diff --git a/ext/wpe/gstwpesrcbin.cpp b/ext/wpe/gstwpesrcbin.cpp
index b080b1f43..3ea006967 100644
--- a/ext/wpe/gstwpesrcbin.cpp
+++ b/ext/wpe/gstwpesrcbin.cpp
@@ -24,11 +24,45 @@
  * The wpesrc element is used to produce a video texture representing a web page
  * rendered off-screen by WPE.
  *
- * Starting from WPEBackend-FDO 1.6.x, software rendering support is available.
- * This features allows wpesrc to be used on machines without GPU, and/or for
- * testing purpose. To enable it, set the `LIBGL_ALWAYS_SOFTWARE=true`
- * environment variable and make sure `video/x-raw, format=BGRA` caps are
- * negotiated by the wpesrc element.
+ * Starting from WPEBackend-FDO 1.6.x, software rendering support is available. This
+ * features allows wpesrc to be used on machines without GPU, and/or for testing
+ * purpose. To enable it, set the `LIBGL_ALWAYS_SOFTWARE=true` environment
+ * variable and make sure `video/x-raw, format=BGRA` caps are negotiated by the
+ * wpesrc element.
+ *
+ * ## Example launch lines
+ *
+ * ### Show the GStreamer website homepage
+ *
+ * ```
+ * gst-launch-1.0 -v wpesrc location="https://gstreamer.freedesktop.org" ! queue ! glimagesink
+ * ```
+ *
+ * ### Save the first 50 video frames generated for the GStreamer website as PNG files in /tmp
+ *
+ * ```
+ * LIBGL_ALWAYS_SOFTWARE=true gst-launch-1.0 -v wpesrc num-buffers=50 location="https://gstreamer.freedesktop.org" ! videoconvert ! pngenc ! multifilesink location=/tmp/snapshot-%05d.png
+ * ```
+ *
+ *
+ * ### Show the GStreamer website homepage as played with GstPlayer in a GTK+ window
+ *
+ * ```
+ * gst-play-1.0 --videosink gtkglsink wpe://https://gstreamer.freedesktop.org
+ * ```
+ *
+ * ### Composite WPE with a video stream in a single OpenGL scene
+ *
+ * ```
+ * gst-launch-1.0  glvideomixer name=m sink_1::zorder=0 ! glimagesink wpesrc location="file:///home/phil/Downloads/plunk/index.html" draw-background=0 ! m. videotestsrc ! queue ! glupload ! glcolorconvert ! m.
+ * ```
+ *
+ *
+ * ### Composite WPE with a video stream, sink_0 pad properties have to match the video dimensions
+ *
+ * ```
+ * gst-launch-1.0 glvideomixer name=m sink_1::zorder=0 sink_0::height=818 sink_0::width=1920 ! gtkglsink wpesrc location="file:///home/phil/Downloads/plunk/index.html" draw-background=0 ! m. uridecodebin uri="http://192.168.1.44/Sintel.2010.1080p.mkv" name=d d. ! queue ! glupload ! glcolorconvert ! m.
+ * ```
  *
  * Additionally, any audio stream created by WPE is exposed as "sometimes" audio
  * source pads.
@@ -38,20 +72,22 @@
  * with the addition of the following fields into the GstMessage details (See
  * gst_message_parse_error_details(), gst_message_parse_warning_details() and
  * gst_message_parse_info_details()):
- *   * `wpesrc_original_src_path`: [Path](gst_object_get_path_string) of the
- *      original element posting the message
+ *
+ * * `wpesrc_original_src_path`: [Path](gst_object_get_path_string) of the
+ *   original element posting the message
  *
  * Other message types are posted as [element custom](gst_message_new_custom)
  * messages reusing the same GstStructure as the one from the message from the
  * message posted in the web page with the addition of the following fields:
- *    * `wpesrc_original_message_type`: Type of the original message from
- *      gst_message_type_get_name().
- *    * `wpesrc_original_src_name`: Name of the original element posting the
- *      message
- *    * `wpesrc_original_src_type`: Name of the GType of the original element
- *      posting the message
- *    * `wpesrc_original_src_path`: [Path](gst_object_get_path_string) of the
- *      original element positing the message
+ *
+ * * `wpesrc_original_message_type`: Type of the original message from
+ *    gst_message_type_get_name().
+ * * `wpesrc_original_src_name`: Name of the original element posting the
+ *   message
+ * * `wpesrc_original_src_type`: Name of the GType of the original element
+ *   posting the message
+ * * `wpesrc_original_src_path`: [Path](gst_object_get_path_string) of the
+ *   original element positing the message
  */
 
 #include "gstwpesrcbin.h"