gnomemm r1739 - in gstreamermm/trunk: . gstreamer/src tests

[jaalburqu svn gnome org]

Author: jaalburqu
Date: Mon Oct 13 01:16:47 2008
New Revision: 1739
URL: http://svn.gnome.org/viewvc/gnomemm?rev=1739&view=rev

Log:
2008-10-12  Josà Alburquerque  <jaalburqu svn gnome org>

	* gstreamer/src/pad.ccg:
	* gstreamer/src/pad.hg: Added create() methods without requiring a
	name param.  Added method docs (a couple are still missing); Added
	signal docs.
	* tests/Makefile.am:
	* tests/test-ghost-pad.cc:
	* tests/test-pad.cc: Rewrote test-pad to test Gst::Pad::create()
	methods and copied old contents to test-ghost-pad.cc (for future ghost
	pad test).

Added:
   gstreamermm/trunk/tests/test-ghost-pad.cc
Modified:
   gstreamermm/trunk/ChangeLog
   gstreamermm/trunk/gstreamer/src/pad.ccg
   gstreamermm/trunk/gstreamer/src/pad.hg
   gstreamermm/trunk/tests/Makefile.am
   gstreamermm/trunk/tests/test-pad.cc

Modified: gstreamermm/trunk/gstreamer/src/pad.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/pad.ccg	(original)
+++ gstreamermm/trunk/gstreamer/src/pad.ccg	Mon Oct 13 01:16:47 2008
@@ -84,11 +84,20 @@
 namespace Gst
 {
 
+Pad::Pad(PadDirection dir)
+  : _CONSTRUCT("name", NULL, "direction", dir)
+{}
+
 Pad::Pad(const Glib::RefPtr<PadTemplate>& templ, const Glib::ustring& name)
   : _CONSTRUCT("name", name.c_str(), "direction", templ->get_direction(),
       "template", templ->gobj())
 {}
 
+Pad::Pad(const Glib::RefPtr<PadTemplate>& templ)
+  : _CONSTRUCT("name", NULL, "direction", templ->get_direction(), "template",
+      templ->gobj())
+{}
+
 // This is handcoded because the documentation tells us that we need to copy
 // the Caps
 Glib::RefPtr<const Caps> Pad::get_pad_template_caps() const

Modified: gstreamermm/trunk/gstreamer/src/pad.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/pad.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/pad.hg	Mon Oct 13 01:16:47 2008
@@ -79,7 +79,9 @@
 
 protected:
   _WRAP_CTOR(Pad(const Glib::ustring& name, PadDirection direction), gst_pad_new)
+  Pad(PadDirection dir);
   Pad(const Glib::RefPtr<PadTemplate>& templ, const Glib::ustring& name);
+  Pad(const Glib::RefPtr<PadTemplate>& templ);
 
 public:
   /** For example,
@@ -95,7 +97,36 @@
    */
   typedef sigc::slot< bool, const Glib::RefPtr<Pad>&, const Glib::RefPtr<MiniObject>& > SlotData;
 
+  /** Creates a new pad with the given name in the given direction.
+   *
+   * @param name The name of the new pad.
+   * @param direction The GstPadDirection of the pad.
+   * @return A new Gst::Pad, or NULL in case of an error. MT safe.
+   */
   _WRAP_CREATE(const Glib::ustring& name, PadDirection dir)
+
+  /** Creates a new pad with a guaranteed unique name (across all pads) in the
+   * given direction.
+   *
+   * @param direction The GstPadDirection of the pad.
+   * @return A new Gst::Pad, or NULL in case of an error. MT safe.
+   */
+  _WRAP_CREATE(PadDirection dir)
+
+  /** Creates a new pad with the given name from the given template.
+   *
+   * @param templ The pad template to use.
+   * @param name The name of the element.
+   * @return A new Gst::Pad, or NULL in case of an error.
+   */
+  _WRAP_CREATE(const Glib::RefPtr<PadTemplate>& pad_template)
+
+  /** Creates a new pad with a guaranteed unique name (across all pads) from
+   * the given template.
+   *
+   * @param templ The pad template to use.
+   * @return A new Gst::Pad, or NULL in case of an error.
+   */
   _WRAP_CREATE(const Glib::RefPtr<PadTemplate>& pad_template, const Glib::ustring& name)
 
   _WRAP_METHOD(PadDirection get_direction() const, gst_pad_get_direction)
@@ -200,11 +231,40 @@
 
   //This is handwritten because conversion from Glib::RefPtr<Buffer>& to
   //GstBuffer** is difficult.
+  /** Allocates a new, empty buffer optimized to push to pad pad. This function
+   * only works if pad is a source pad and has a peer.
+   *
+   * A new, empty Gst::Buffer will be put in the buf argument. You need to
+   * check the caps of the buffer after performing this function and
+   * renegotiate to the format if needed.
+   *
+   * @param offset The offset of the new buffer in the stream.
+   * @param size The size of the new buffer.
+   * @param caps The caps of the new buffer.
+   * @param buf A newly allocated buffer.
+   * @return A result code indicating success of the operation. Any result code
+   * other than Gst::FLOW_OK is an error and buf should not be used. An error
+   * can occur if the pad is not connected or when the downstream peer elements
+   * cannot provide an acceptable buffer. MT safe.
+   */
   FlowReturn alloc_buffer(guint64 offset, int size, const Glib::RefPtr<Caps>& caps, Glib::RefPtr<Buffer>& buf);
   _IGNORE(gst_pad_alloc_buffer)
 
   //This is handwritten because conversion from Glib::RefPtr<Buffer>& to
   //GstBuffer** is difficult.
+  /** In addition to the function alloc_buffer(), this function automatically
+   * calls set_caps() when the caps of the newly allocated buffer are different
+   * from the pad caps.  Again, the pad must be a source pad.
+   *
+   * @param offset The offset of the new buffer in the stream.
+   * @param size The size of the new buffer.
+   * @param caps The caps of the new buffer.
+   * @param buf A newly allocated buffer.
+   * @return A result code indicating success of the operation. Any result code
+   * other than Gst::FLOW_OK is an error and buf should not be used. An error
+   * can occur if the pad is not connected or when the downstream peer elements
+   * cannot provide an acceptable buffer. MT safe.
+   */
   FlowReturn alloc_buffer_and_set_caps(guint64 offset, int size, const Glib::RefPtr<Caps>& caps, Glib::RefPtr<Buffer>& buf);
   _IGNORE(gst_pad_alloc_buffer_and_set_caps)
 
@@ -221,10 +281,35 @@
   _WRAP_METHOD(bool peer_accept_caps(const Glib::RefPtr<Caps>& caps), gst_pad_peer_accept_caps)
 
   // This method is written manually because an extra ref is necessary
+  /** Pushes a buffer to the peer of the pad. The pad must be a source pad,
+   * otherwise this method returns Gst::FLOW_ERROR.
+   *
+   * This function will call an installed pad block before triggering any
+   * installed pad probes.
+   *
+   * If the caps on buffer are different from the currently configured caps on
+   * pad, this function will call any installed setcaps function on pad (see
+   * the C API gst_pad_set_setcaps_function()). In case of failure to
+   * renegotiate the new format, this function returns
+   * Gst::FLOW_NOT_NEGOTIATED.
+   *
+   * The function proceeds calling chain() on the peer pad and returns the
+   * value from that function. If pad has no peer, Gst::FLOW_NOT_LINKED will
+   * be returned.
+   *
+   * @param buffer The Gst::Buffer to push.
+   * @return A Gst::FlowReturn from the peer pad. MT safe.
+   */
   FlowReturn push(const Glib::RefPtr<Buffer>& buffer);
   _IGNORE(gst_pad_push)
 
   // This method is written manually because an extra ref is necessary
+  /** Sends the event to the peer of the pad. This function is mainly used by
+   * elements to send events to their peer elements.
+   *
+   * @param event The GstEvent to send to the pad.
+   * @return true if the event was handled. MT safe.
+   */
   bool push_event(const Glib::RefPtr<Event>& event);
   _IGNORE(gst_pad_push_event)
 
@@ -237,6 +322,28 @@
   _WRAP_METHOD(bool activate_push(bool active = true), gst_pad_activate_push)
 
   // This method is written manually because an extra ref is necessary
+  /** Sends the event to the pad. This function can be used by applications to
+   * send events in the pipeline.
+   *
+   * If the pad is a source pad, event should be an upstream event. If the pad
+   * is a sink pad, the event should be a downstream event. For example, you
+   * would not send a Gst::EVENT_EOS on a src pad; EOS events only propagate
+   * downstream.  Furthermore, some downstream events have to be serialized
+   * with data flow, like EOS, while some can travel out-of-band, like
+   * Gst::EVENT_FLUSH_START.  If the event needs to be serialized with data
+   * flow, this function will take the pad's stream lock while calling its
+   * event function.
+   *
+   * To find out whether an event type is upstream, downstream, or downstream
+   * and serialized, see Gst::EventTypeFlags, Gst::Enums::get_flags(),
+   * is_upstream(), Gst::Event::is_downstream(), and
+   * Gst::Event::is_serialized(). Note that in practice that an application or
+   * plugin doesn't need to bother itself with this information; the core
+   * handles all necessary locks and checks.
+   *
+   * @param event The Gst::Event to send to the pad.
+   * @return true if the event was handled. 
+   */
   bool send_event(const Glib::RefPtr<Event>& event);
   _IGNORE(gst_pad_send_event)
 
@@ -246,19 +353,40 @@
   _WRAP_METHOD(bool query_default(const Glib::RefPtr<Query>& query), gst_pad_query_default)
   _WRAP_METHOD(bool query_position(Format& format, gint64& position) const, gst_pad_query_position)
 
+  /** Queries a pad for the stream position parsing only the format.
+   * @param format A reference to the Gst::Format asked for. On return contains
+   * the Gst::Format used.
+   * @return true if the query could be performed.
+   */
   bool query_position(Format& format) const;
 
   _WRAP_METHOD(bool query_duration(Format& format, gint64& duration) const, gst_pad_query_duration)
 
+  /** Queries a pad for the total stream duration parsing only the format.
+   * @param format A reference to the Gst::Format asked for. On return contains
+   * the GstFormat used.
+   * @return true if the query could be performed.
+   */
   bool query_duration(Format& format) const;
 
   _WRAP_METHOD(bool query_convert(Format src_format, gint64 src_value, Format& dst_format, gint64& dst_value) const, gst_pad_query_convert)
   _WRAP_METHOD(bool query_peer_position(Format& format, gint64& position) const, gst_pad_query_peer_position)
 
+  /** Queries the peer of a given sink pad for the stream position parsing only
+   * the format.
+   * @param format A reference to the Gst::Format asked for. On return contains
+   * the Gst::Format used.
+   * @return true if the query could be performed.
+   */
   bool query_peer_position(Format& format) const;
 
    _WRAP_METHOD(bool query_peer_duration(Format& format, gint64& duration) const, gst_pad_query_peer_duration)
 
+  /** Queries the peer pad of a given sink pad for the total stream duration.
+   * @param format A reference to the Gst::Format asked for. On return contains
+   * the Gst::Format used.
+   * @return true if the query could be performed.
+   */
   bool query_peer_duration(Format& format) const;
 
    _WRAP_METHOD(bool query_peer_convert(Format src_format, gint64 src_value, Format& dst_format, gint64& dst_value) const, gst_pad_query_peer_convert)
@@ -306,8 +434,16 @@
   _IGNORE_SIGNAL(have_data)
 
 #m4 _CONVERSION(`GstPad*',`const Glib::RefPtr<Pad>&',`Glib::wrap($3, true)')
+  /** Signals that a pad has been linked to the peer pad.
+   */
   _WRAP_SIGNAL(void linked(const Glib::RefPtr<Pad>& peer_pad), "linked")
+
+  /** Signals that a pad connection has been requested.
+   */
   _WRAP_SIGNAL(void request_link(), "request-link")
+
+  /** Signals that a pad has been unlinked from the peer pad.
+   */
   _WRAP_SIGNAL(void unlinked(const Glib::RefPtr<Pad>& peer_pad), "unlinked")
 
   _WRAP_PROPERTY("caps", Glib::RefPtr<Caps>)

Modified: gstreamermm/trunk/tests/Makefile.am
==============================================================================
--- gstreamermm/trunk/tests/Makefile.am	(original)
+++ gstreamermm/trunk/tests/Makefile.am	Mon Oct 13 01:16:47 2008
@@ -8,11 +8,11 @@
                   test-link-elements test-create-bin test-miniobject-wrap \
                   test-message-wrap test-event-wrap test-query-wrap \
 		  test-structure test-caps-structures test-interface \
-		  test-create-bus test-taglist test-tagsetter \
+		  test-create-bus test-taglist test-tagsetter test-pad \
 		  test-init-check test-init test-init-check-noargs \
 		  test-init-noargs test-iterator test-property-caps
 
-#TODO: Add test-pad to tests when bug #539108 is fixed.
+#TODO: Add test-ghost-pad to tests when bug #539108 is fixed.
 
 test_caps_SOURCES=test-caps.cc
 test_caps_LDFLAGS= GSTREAMERMM_LIBS@
@@ -59,8 +59,11 @@
 test_tagsetter_SOURCES=test-tagsetter.cc
 test_tagsetter_LDFLAGS= GSTREAMERMM_LIBS@
 
-#TODO: test_pad_SOURCES=test-pad.cc
-#TODO: test_pad_LDFLAGS= GSTREAMERMM_LIBS@
+test_pad_SOURCES=test-pad.cc
+test_pad_LDFLAGS= GSTREAMERMM_LIBS@
+
+#TODO: test_ghost_pad_SOURCES=test-ghost-pad.cc
+#TODO: test_ghost_pad_LDFLAGS= GSTREAMERMM_LIBS@
 
 test_init_check_SOURCES=test-init-check.cc
 test_init_check_LDFLAGS= GSTREAMERMM_LIBS@

Added: gstreamermm/trunk/tests/test-ghost-pad.cc
==============================================================================
--- (empty file)
+++ gstreamermm/trunk/tests/test-ghost-pad.cc	Mon Oct 13 01:16:47 2008
@@ -0,0 +1,85 @@
+// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+
+/* gstreamermm - a C++ wrapper for gstreamer
+ *
+ * Copyright 2008 The gstreamermm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <gstreamermm.h>
+#include <iostream>
+
+int main (int argc, char* argv[])
+{
+  Gst::init(argc, argv);
+
+  Glib::RefPtr<Gst::Caps> caps = Gst::Caps::create_simple("video/x-raw-yuv");
+  caps->set_simple("width", 500);
+  caps->set_simple("framerate", Gst::Fraction(25, 1));
+
+  Glib::RefPtr<Gst::PadTemplate> templ =
+    Gst::PadTemplate::create("source-template", Gst::PAD_SINK, Gst::PAD_ALWAYS,
+      caps);
+
+  if (templ)
+    std::cout << "Successfully created pad template '" <<
+      templ->get_name_template() << "'; direction = " << 
+        templ->get_direction() << "." << std::endl;
+
+  Glib::RefPtr<Gst::Pad> pad1 = Gst::Pad::create(Gst::PAD_SINK);
+  if (pad1)
+    std::cout << "Successfully created pad '" << pad1->get_name() <<
+      "'; direction = " << pad1->get_direction() << "." << std::endl;
+
+  Glib::RefPtr<Gst::Pad> pad2 = Gst::Pad::create(templ);
+
+  if (pad2)
+    std::cout << "Successfully created pad '" << pad2->get_name() <<
+      "'; direction = " << pad2->get_direction() << "." << std::endl;
+
+//Uuncomment the following lines to produce an error while creating the ghost
+//pad.
+/*
+  Glib::RefPtr<Gst::GhostPad> gpad1 = Gst::GhostPad::create("gpad1", pad1);
+  if (gpad1)
+    std::cout << "Successfully created pad '" << gpad1->get_name() <<
+      "'; direction = " << gpad1->get_direction() << "." << std::endl;
+*/
+
+  Glib::RefPtr<Gst::GhostPad> gpad2 =
+    Gst::GhostPad::create("gpad2", Gst::PAD_SRC);
+  if (gpad2)
+    std::cout << "Successfully created pad '" << gpad2->get_name() <<
+      "'; direction = " << gpad2->get_direction() << "." << std::endl;
+
+//Uuncomment the following lines to produce an error while creating the ghost
+//pad.
+/*
+  Glib::RefPtr<Gst::GhostPad> gpad3 =
+    Gst::GhostPad::create("gpad3", pad1, templ);
+  if (gpad3)
+    std::cout << "Successfully created pad '" << gpad3->get_name() <<
+      "'; direction = " << gpad3->get_direction() << "." << std::endl;
+*/
+
+  Glib::RefPtr<Gst::GhostPad> gpad4 =
+    Gst::GhostPad::create("gpad4", templ);
+  if (gpad4)
+    std::cout << "Successfully created pad '" << gpad4->get_name() <<
+      "'; direction = " << gpad4->get_direction() << "." << std::endl;
+
+  return 0;
+}

Modified: gstreamermm/trunk/tests/test-pad.cc
==============================================================================
--- gstreamermm/trunk/tests/test-pad.cc	(original)
+++ gstreamermm/trunk/tests/test-pad.cc	Mon Oct 13 01:16:47 2008
@@ -39,45 +39,29 @@
       templ->get_name_template() << "'; direction = " << 
         templ->get_direction() << "." << std::endl;
 
-  Glib::RefPtr<Gst::Pad> pad1 =
-    Gst::Pad::create("pad1", Gst::PAD_SINK);
+  Glib::RefPtr<Gst::Pad> pad1 = Gst::Pad::create("pad1", Gst::PAD_SINK);
+
   if (pad1)
     std::cout << "Successfully created pad '" << pad1->get_name() <<
       "'; direction = " << pad1->get_direction() << "." << std::endl;
 
-  Glib::RefPtr<Gst::Pad> pad2 = Gst::Pad::create(templ, "pad2");
+  Glib::RefPtr<Gst::Pad> pad2 = Gst::Pad::create(Gst::PAD_SINK);
 
   if (pad2)
     std::cout << "Successfully created pad '" << pad2->get_name() <<
       "'; direction = " << pad2->get_direction() << "." << std::endl;
 
-/*
-  Glib::RefPtr<Gst::GhostPad> gpad1 =
-    Gst::GhostPad::create("gpad1", pad1);
-  if (gpad1)
-    std::cout << "Successfully created pad '" << gpad1->get_name() <<
-      "'; direction = " << gpad1->get_direction() << "." << std::endl;
-*/
-
-  Glib::RefPtr<Gst::GhostPad> gpad2 =
-    Gst::GhostPad::create("gpad2", Gst::PAD_SRC);
-  if (gpad2)
-    std::cout << "Successfully created pad '" << gpad2->get_name() <<
-      "'; direction = " << gpad2->get_direction() << "." << std::endl;
-
-/*
-  Glib::RefPtr<Gst::GhostPad> gpad3 =
-    Gst::GhostPad::create("gpad3", pad1, templ);
-  if (gpad3)
-    std::cout << "Successfully created pad '" << gpad3->get_name() <<
-      "'; direction = " << gpad3->get_direction() << "." << std::endl;
-*/
-
-  Glib::RefPtr<Gst::GhostPad> gpad4 =
-    Gst::GhostPad::create("gpad4", templ);
-  if (gpad4)
-    std::cout << "Successfully created pad '" << gpad4->get_name() <<
-      "'; direction = " << gpad4->get_direction() << "." << std::endl;
+  Glib::RefPtr<Gst::Pad> pad3 = Gst::Pad::create(templ, "pad3");
+
+  if (pad3)
+    std::cout << "Successfully created pad '" << pad3->get_name() <<
+      "'; direction = " << pad3->get_direction() << "." << std::endl;
+
+  Glib::RefPtr<Gst::Pad> pad4 = Gst::Pad::create(templ);
+
+  if (pad4)
+    std::cout << "Successfully created pad '" << pad4->get_name() <<
+      "'; direction = " << pad4->get_direction() << "." << std::endl;
 
   return 0;
 }