summaryrefslogtreecommitdiff
path: root/sys
diff options
context:
space:
mode:
authorThibault Saunier <thibault.saunier@osg.samsung.com>2017-01-23 16:36:11 -0300
committerThibault Saunier <thibault.saunier@osg.samsung.com>2017-03-10 18:19:17 -0300
commit099ac9faf2c6e6fcf55fe4bee812c9f90aeb8602 (patch)
treee1c72b6424115e95c69fad3f9e39bff6979e0b20 /sys
parenta122135194c693edaeb14a1ecddf946d76523d2f (diff)
docs: Convert gtkdoc comments to markdown
Modernizing the documentation, making it simpler to read an modify and allowing us to possibly switch to hotdoc in the future.
Diffstat (limited to 'sys')
-rw-r--r--sys/ximage/ximagesink.c55
-rw-r--r--sys/ximage/ximagesink.h2
-rw-r--r--sys/xvimage/xvimagesink.c45
3 files changed, 49 insertions, 53 deletions
diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c
index 748dcd5dc..cf5f19c33 100644
--- a/sys/ximage/ximagesink.c
+++ b/sys/ximage/ximagesink.c
@@ -19,6 +19,7 @@
/**
* SECTION:element-ximagesink
+ * @title: ximagesink
*
* XImageSink renders video frames to a drawable (XWindow) on a local or remote
* display. This element can receive a Window ID from the application through
@@ -26,27 +27,24 @@
* drawable. If no Window ID was provided by the application, the element will
* create its own internal window and render into it.
*
- * <refsect2>
- * <title>Scaling</title>
- * <para>
+ * ## Scaling
+ *
* As standard XImage rendering to a drawable is not scaled, XImageSink will use
* reverse caps negotiation to try to get scaled video frames for the drawable.
* This is accomplished by asking the peer pad if it accepts some different caps
* which in most cases implies that there is a scaling element in the pipeline,
- * or that an element generating the video frames can generate them with a
+ * or that an element generating the video frames can generate them with a
* different geometry. This mechanism is handled during buffer allocations, for
* each allocation request the video sink will check the drawable geometry, look
* at the #GstXImageSink:force-aspect-ratio property, calculate the geometry of
* desired video frames and then check that the peer pad accept those new caps.
* If it does it will then allocate a buffer in video memory with this new
* geometry and return it with the new caps.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Events</title>
- * <para>
+ *
+ * ## Events
+ *
* XImageSink creates a thread to handle events coming from the drawable. There
- * are several kind of events that can be grouped in 2 big categories: input
+ * are several kind of events that can be grouped in 2 big categories: input
* events and window state related events. Input events will be translated to
* navigation events and pushed upstream for other elements to react on them.
* This includes events such as pointer moves, key press/release, clicks etc...
@@ -54,49 +52,48 @@
* is not flowing (GST_STATE_PAUSED). That means that even when the element is
* paused, it will receive expose events from the drawable and draw the latest
* frame with correct borders/aspect-ratio.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Pixel aspect ratio</title>
- * <para>
+ *
+ * ## Pixel aspect ratio
+ *
* When changing state to GST_STATE_READY, XImageSink will open a connection to
* the display specified in the #GstXImageSink:display property or the default
- * display if nothing specified. Once this connection is open it will inspect
- * the display configuration including the physical display geometry and
+ * display if nothing specified. Once this connection is open it will inspect
+ * the display configuration including the physical display geometry and
* then calculate the pixel aspect ratio. When caps negotiation will occur, the
- * video sink will set the calculated pixel aspect ratio on the caps to make
+ * video sink will set the calculated pixel aspect ratio on the caps to make
* sure that incoming video frames will have the correct pixel aspect ratio for
* this display. Sometimes the calculated pixel aspect ratio can be wrong, it is
* then possible to enforce a specific pixel aspect ratio using the
* #GstXImageSink:pixel-aspect-ratio property.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Examples</title>
+ *
+ * ## Examples
* |[
* gst-launch-1.0 -v videotestsrc ! queue ! ximagesink
- * ]| A pipeline to test reverse negotiation. When the test video signal appears
+ * ]|
+ * A pipeline to test reverse negotiation. When the test video signal appears
* you can resize the window and see that scaled buffers of the desired size are
* going to arrive with a short delay. This illustrates how buffers of desired
* size are allocated along the way. If you take away the queue, scaling will
* happen almost immediately.
* |[
* gst-launch-1.0 -v videotestsrc ! navigationtest ! videoconvert ! ximagesink
- * ]| A pipeline to test navigation events.
+ * ]|
+ * A pipeline to test navigation events.
* While moving the mouse pointer over the test signal you will see a black box
- * following the mouse pointer. If you press the mouse button somewhere on the
+ * following the mouse pointer. If you press the mouse button somewhere on the
* video and release it somewhere else a green box will appear where you pressed
* the button and a red one where you released it. (The navigationtest element
* is part of gst-plugins-good.)
* |[
* gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink
- * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]|
+ * This is faking a 4/3 pixel aspect ratio caps on video frames produced by
* videotestsrc, in most cases the pixel aspect ratio of the display will be
- * 1/1. This means that videoscale will have to do the scaling to convert
+ * 1/1. This means that videoscale will have to do the scaling to convert
* incoming frames to a size that will match the display pixel aspect ratio
- * (from 320x240 to 320x180 in this case). Note that you might have to escape
+ * (from 320x240 to 320x180 in this case). Note that you might have to escape
* some characters for your shell like '\(fraction\)'.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
diff --git a/sys/ximage/ximagesink.h b/sys/ximage/ximagesink.h
index cc9c2224a..b16c7fb25 100644
--- a/sys/ximage/ximagesink.h
+++ b/sys/ximage/ximagesink.h
@@ -152,7 +152,7 @@ struct _GstXWindow
* @pool_lock: used to protect the buffer pool
* @buffer_pool: a list of #GstXImageBuffer that could be reused at next buffer
* allocation call
- * @synchronous: used to store if XSynchronous should be used or not (for
+ * @synchronous: used to store if XSynchronous should be used or not (for
* debugging purpose only)
* @keep_aspect: used to remember if reverse negotiation scaling should respect
* aspect ratio
diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c
index e008d09a0..9cd0da1a4 100644
--- a/sys/xvimage/xvimagesink.c
+++ b/sys/xvimage/xvimagesink.c
@@ -20,6 +20,7 @@
/**
* SECTION:element-xvimagesink
+ * @title: xvimagesink
*
* XvImageSink renders video frames to a drawable (XWindow) on a local display
* using the XVideo extension. Rendering to a remote display is theoretically
@@ -30,20 +31,17 @@
* application, the element will create its own internal window and render
* into it.
*
- * <refsect2>
- * <title>Scaling</title>
- * <para>
+ * ## Scaling
+ *
* The XVideo extension, when it's available, handles hardware accelerated
* scaling of video frames. This means that the element will just accept
* incoming video frames no matter their geometry and will then put them to the
* drawable scaling them on the fly. Using the #GstXvImageSink:force-aspect-ratio
* property it is possible to enforce scaling with a constant aspect ratio,
* which means drawing black borders around the video frame.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Events</title>
- * <para>
+ *
+ * ## Events
+ *
* XvImageSink creates a thread to handle events coming from the drawable. There
* are several kind of events that can be grouped in 2 big categories: input
* events and window state related events. Input events will be translated to
@@ -53,11 +51,9 @@
* is not flowing (GST_STATE_PAUSED). That means that even when the element is
* paused, it will receive expose events from the drawable and draw the latest
* frame with correct borders/aspect-ratio.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Pixel aspect ratio</title>
- * <para>
+ *
+ * ## Pixel aspect ratio
+ *
* When changing state to GST_STATE_READY, XvImageSink will open a connection to
* the display specified in the #GstXvImageSink:display property or the
* default display if nothing specified. Once this connection is open it will
@@ -68,26 +64,27 @@
* Sometimes the calculated pixel aspect ratio can be wrong, it is
* then possible to enforce a specific pixel aspect ratio using the
* #GstXvImageSink:pixel-aspect-ratio property.
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Examples</title>
+ *
+ * ## Examples
* |[
* gst-launch-1.0 -v videotestsrc ! xvimagesink
- * ]| A pipeline to test hardware scaling.
+ * ]|
+ * A pipeline to test hardware scaling.
* When the test video signal appears you can resize the window and see that
* video frames are scaled through hardware (no extra CPU cost). By default
* the image will never be distorted when scaled, instead black borders will
* be added if needed.
* |[
* gst-launch-1.0 -v videotestsrc ! xvimagesink force-aspect-ratio=false
- * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to
+ * ]|
+ * Same pipeline with #GstXvImageSink:force-aspect-ratio property set to
* false. You can observe that no borders are drawn around the scaled image
* now and it will be distorted to fill the entire frame instead of respecting
* the aspect ratio.
* |[
* gst-launch-1.0 -v videotestsrc ! navigationtest ! xvimagesink
- * ]| A pipeline to test navigation events.
+ * ]|
+ * A pipeline to test navigation events.
* While moving the mouse pointer over the test signal you will see a black box
* following the mouse pointer. If you press the mouse button somewhere on the
* video and release it somewhere else a green box will appear where you pressed
@@ -99,15 +96,17 @@
* image area
* |[
* gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=4/3 ! xvimagesink
- * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]|
+ * This is faking a 4/3 pixel aspect ratio caps on video frames produced by
* videotestsrc, in most cases the pixel aspect ratio of the display will be
* 1/1. This means that XvImageSink will have to do the scaling to convert
* incoming frames to a size that will match the display pixel aspect ratio
* (from 320x240 to 320x180 in this case).
* |[
* gst-launch-1.0 -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100
- * ]| Demonstrates how to use the colorbalance interface.
- * </refsect2>
+ * ]|
+ * Demonstrates how to use the colorbalance interface.
+ *
*/
/* for developers: there are two useful tools : xvinfo and xvattr */