camerabin2: Adding top-level element documentation

gst/camerabin2/gstcamerabin2.c

@@ -19,19 +19,115 @@
 /**
  * SECTION:element-camerabin2
  *
- * GstCameraBin22 is a high-level camera object that encapsulates the gstreamer
- * internals and provides a task based API for the application.
+ * CameraBin2 is a high-level camera object that encapsulates gstreamer
+ * elements, providing an API for controlling a digital camera.
  *
  * <note>
- * Note that camerabin2 is still UNSTABLE, EXPERIMENTAL and under heavy
+ * Note that camerabin2 is still UNSTABLE, EXPERIMENTAL and under
  * development.
  * </note>
  *
+ * CameraBin2 has the following main features:
+ * <itemizedlist>
+ * <listitem>
+ * Record videos
+ * </listitem>
+ * <listitem>
+ * Capture pictures
+ * </listitem>
+ * <listitem>
+ * Display a viewfinder
+ * </listitem>
+ * <listitem>
+ * Post preview images for each capture (video and image)
+ * </listitem>
+ * </itemizedlist>
+ *
+ * <refsect2>
+ * <title>Usage</title>
+ * <para>
+ * Camerabin2 can be created using gst_element_factory_make() just like
+ * any other element. Video or image capture mode can be selected using
+ * the #GstCameraBin2:mode property and the file to save the capture is
+ * selected using #GstCameraBin2:location property.
+ *
+ * After creating camerabin2, applications might want to do some
+ * customization (there's a section about this below), then select
+ * the desired mode and start capturing.
+ *
+ * In image capture mode, just send a #GstCameraBin:start-capture and a
+ * picture will be captured. When the picture is stored on the selected
+ * location, a %GST_MESSAGE_ELEMENT named 'image-done' will be posted on
+ * the #GstBus.
+ *
+ * In video capture mode, send a #GstCameraBin2:start-capture to start
+ * recording, then send a #GstCameraBin2:stop-capture to stop recording.
+ * Note that both signals are asynchronous, so, calling
+ * #GstCameraBin2:stop-capture doesn't guarantee that the video has been
+ * properly finished yet. Users can check the #GstCameraBin2:idle property
+ * to verify that it has stopped.
+ *
+ * In both modes, if #GstCameraBin2:post-previews is %TRUE, a #GstBuffer
+ * will be post to the #GstBus in a field named 'buffer', in a
+ * 'preview-image' message of type %GST_MESSAGE_ELEMENT.
+ * </para>
+ * </refsect2>
+
+ * <refsect2>
+ * <title>Customization</title>
+ * <para>
+ * Camerabin2 provides various customization properties, allowing the user
+ * to set custom filters, selecting the viewfinder sink and formats to
+ * use to encode the captured images/videos.
+ *
+ * #GstEncodingProfile<!-- -->s are used to tell camerabin2 which formats it
+ * should encode the captures to, those should be set to
+ * #GstCameraBin2:image-profile and #GstCameraBin2:video-profile. Default is
+ * jpeg for images, and ogg (theora and vorbis) for video. If a profile without
+ * an audio stream is set for video, audio will be disabled on recordings.
+ *
+ * #GstCameraBin2:preview-caps can be used to select which format preview
+ * images should be posted on the #GstBus. It has to be a raw video format.
+ *
+ * Camerabin2 has a #GstCameraBin2:camera-source property so applications can
+ * set their source that will provide buffers for the viewfinder and for
+ * captures. This camera source is a special type of source that has 3 pads.
+ * To use a 'regular' source with a single pad you should use
+ * #GstWrapperCameraBinSource, it will adapt your source and provide 3 pads.
+ *
+ * Applications can also select the desired viewfinder sink using
+ * #GstCameraBin2:viewfinder-sink, it is also possible to select the audio
+ * source using #GstCameraBin2:audio-source.
+ *
+ * The viewfinder resolution can be configured using
+ * #GstCameraBin2:viewfinder-caps, these #GstCaps should be a subset of
+ * #GstCameraBin2:viewfinder-supported-caps.
+ *
+ * To select the desired resolution for captures, camerabin2 provides
+ * #GstCameraBin2:image-capture-caps and #GstCameraBin2:video-capture-caps,
+ * these caps must be a subset of what the source can produce. The allowed
+ * caps can be probed using #GstCameraBin2:image-capture-supported-caps and
+ * #GstCameraBin2:video-capture-supported-caps. In an analogous way, there
+ * are #GstCameraBin2:audio-capture-caps and
+ * #GstCameraBin2:audio-capture-supported-caps.
+ *
+ * Camerabin2 also allows applications to insert custom #GstElements on any
+ * of its branches: video capture, image capture, viewfinder and preview.
+ * Check #GstCameraBin2:video-filter, #GstCameraBin2:image-filter,
+ * #GstCameraBin2:viewfinder-filter and #GstCameraBin2:preview-filter.
+ * </para>
+ * </refsect2>
+ *
  * <refsect2>
  * <title>Example launch line</title>
+ * <para>
+ * Unfortunatelly, camerabin2 can't be really used from gst-launch, as you need
+ * to send signals to control it. The following pipeline might be able
+ * to show the viewfinder using all the default elements.
  * |[
  * gst-launch -v -m camerabin2
  * ]|
+ * </para>
  * </refsect2>
 
  */