gnomemm r1399 - in gstreamermm/trunk: . gstreamer/src tools/m4

[jaalburqu svn gnome org]

Author: jaalburqu
Date: Sun Mar  9 19:39:06 2008
New Revision: 1399
URL: http://svn.gnome.org/viewvc/gnomemm?rev=1399&view=rev

Log:
2008-03-09  Josà Alburquerque  <jaalburqu svn gnome org>

	* gstreamer/src/caps.ccg:
	* gstreamer/src/caps.hg:
	- Added create(Structure& s) method;
	- Added class and method docs
	- Wrote out get_structure() to return Structure& and not Structure*
	(getting Gst::Structures feels a bit weird because since
	Gst::Structure is a boxed type, copies are always created and
	developers may think that once they get a Gst::Structure, if the owner
	of the Gst::Structure modifies it, it will be reflected in the copy
	they obtain.  This doesn't seem to be so)

	* tools/m4/convert_gst.m4: Fixed GstStructure conversions

Modified:
   gstreamermm/trunk/ChangeLog
   gstreamermm/trunk/gstreamer/src/caps.ccg
   gstreamermm/trunk/gstreamer/src/caps.hg
   gstreamermm/trunk/tools/m4/convert_gst.m4

Modified: gstreamermm/trunk/gstreamer/src/caps.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/caps.ccg	(original)
+++ gstreamermm/trunk/gstreamer/src/caps.ccg	Sun Mar  9 19:39:06 2008
@@ -46,14 +46,16 @@
   return result;
 }
 
-/*
 Glib::RefPtr<Caps>
-Caps::create_full(Structure& structure)
+Caps::create(Structure& structure)
 {
   return Glib::wrap(gst_caps_new_full(structure.gobj()));
 }
-*/
 
+//TODO: Want to return RefPtr to Caps but using RefPtr in expressions such
+//TODO: as 'caps->set_simple(name1, value1)->set_simple(name2, value2)' a
+//TODO: causes Structure immutability warnings because the Caps is referenced
+//TODO: more than once in the expression
 /*
   This method is implemented because gst_caps_set_simple is a variable argument
   function and cannot be wrapped.  In addition, in order for
@@ -73,4 +75,10 @@
   //return Glib::wrap(gobj(), true);
 }
 
+const Structure& Caps::get_structure(guint idx) const
+{
+  const_cast<Caps*>(this)->structure_ = Structure(gst_caps_get_structure(gobj(), idx));
+  return structure_;
+}
+
 } //namespace Gst

Modified: gstreamermm/trunk/gstreamer/src/caps.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/caps.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/caps.hg	Sun Mar  9 19:39:06 2008
@@ -20,6 +20,7 @@
  */
 
 #include <gst/gstcaps.h>
+#include <gstreamermm/structure.h>
 
 _DEFS(gstreamermm,gst)
 
@@ -28,17 +29,54 @@
 
 struct Structure;
 
+/** Caps â Structure describing sets of media formats.
+ * Caps (capabilities) are lighweight refcounted objects describing media
+ * types. They are composed of an array of Structure.
+ *
+ * Caps are exposed on PadTemplate to describe all possible types a given pad
+ * can handle. They are also stored in the Registry along with a description of
+ * the Element.
+ *
+ * Caps are exposed on the element pads using the Gst::Pad::get_caps() method.
+ * This method describes the possible types that the pad can handle or produce
+ * at runtime.
+ *
+ * Caps are also attached to buffers to describe to content of the data pointed
+ * to by the buffer with Gst::Buffer:set_caps(). Caps attached to a Buffer
+ * allow for format negotiation upstream and downstream.
+ *
+ * A Caps can be constructed with the following code fragment:
+ *
+ * TODO: Insert C++ translated code fragment from C API docs
+ */
 class Caps 
 {
   _CLASS_OPAQUE_REFCOUNTED(Caps, GstCaps, gst_caps_new_empty, gst_caps_ref, gst_caps_unref)
   _IGNORE(gst_caps_ref, gst_caps_unref)
 
 public:
+  /** Creates a new Caps that indicates that it is compatible with any media
+   * format.
+   *
+   * @return the new Caps
+   */
   static Glib::RefPtr<Caps> create_any();
+
+  /** Creates a new Caps that contains one Structure. Caller is responsible for
+   * unreffing the returned caps.
+   *
+   * @param media_type the media type of the structure
+   * @return the new GstCaps
+   */
   static Glib::RefPtr<Caps> create_simple(const Glib::ustring& media_type);
 
-  //TODO: Parameter should be a list of Structures
-  //static Glib::RefPtr<Caps> create_full(Structure& structure);
+  /** Creates a new GstCaps and adds the first Structure given. The structure
+   * is not copied; the returned Caps owns the structure.
+   *
+   * @param first_struct the first structure to add
+   * @return Returns the new GstCaps
+   */
+  static Glib::RefPtr<Caps> create(Structure& first_struct);
 
   _WRAP_METHOD(Glib::RefPtr<Caps> copy() const, gst_caps_copy)
   _WRAP_METHOD(Glib::RefPtr<Caps> copy_nth(guint nth), gst_caps_copy_nth)
@@ -46,16 +84,23 @@
   _WRAP_METHOD(void merge(const Glib::RefPtr<Caps>& caps), gst_caps_merge)
   _WRAP_METHOD(void append_structure(Structure& structure), gst_caps_append_structure)
   _WRAP_METHOD(void merge_structure(Structure& structure), gst_caps_merge_structure)
-  //TODO: Shouldn't the Structure be reference-counted?
-  _WRAP_METHOD(Structure* get_structure(guint idx), gst_caps_get_structure)
+
+  /** Finds the structure in caps that has the index index, and returns it.
+   *
+   * @param index the index of the structure
+   * @return the Structure corresponding to index
+   */
+  const Structure& get_structure(guint idx) const;
 
   _WRAP_METHOD(void remove_structure(guint idx), gst_caps_remove_structure)
   _WRAP_METHOD(guint get_size() const, gst_caps_get_size)
 
-  //TODO: Want to return RefPtr to Caps but using RefPtr in expressions such
-  //TODO: as 'caps->set_simple(name1, value1)->set_simple(name2, value2)' a
-  //TODO: causes Structure immutability warnings because the Caps is referenced
-  //TODO: more than once in the expression
+  /** Sets a fields in a simple Caps. A simple Caps is one that only has one
+   * structure.
+   *
+   * @param field field to set
+   * @param value the value which the field should be set to
+   */
   void set_simple(const Glib::ustring& name, const Glib::ValueBase& value);
 
   _WRAP_METHOD(void set_simple_valist(char* field, const va_list& varargs), gst_caps_set_simple_valist)
@@ -83,6 +128,10 @@
   _WRAP_METHOD(void truncate(), gst_caps_truncate)
   
   _IGNORE(gst_caps_copy, gst_caps_set_simple, gst_caps_make_writable)
+
+private:
+  Structure structure_;
+  
 };
 
 } //namespace Gst

Modified: gstreamermm/trunk/tools/m4/convert_gst.m4
==============================================================================
--- gstreamermm/trunk/tools/m4/convert_gst.m4	(original)
+++ gstreamermm/trunk/tools/m4/convert_gst.m4	Sun Mar  9 19:39:06 2008
@@ -93,8 +93,7 @@
 _CONVERSION(`GstRegistry*',`Glib::RefPtr<Registry>', `Glib::wrap($3)')
 
 #Structure
-_CONVERSION(`Structure&',`GstStructure*',`((GstStructure*)(&($3)))')
-_CONVERSION(`GstStructure*',`Structure*',`((Structure*) ($3))')
+_CONVERSION(`Structure&',`GstStructure*',`(($3).gobj())')
 
 #TagList
 _CONVERSION(`const Glib::RefPtr<const TagList>&',`const GstTagList*', `Glib::unwrap($3)')