--- /dev/null
+From ce8841a1b178ca7e9cd139d4e687a36650392cd6 Mon Sep 17 00:00:00 2001
+From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= <tim.muller@collabora.co.uk>
+Date: Fri, 22 May 2009 19:38:01 +0100
+Subject: [PATCH] tag: add new GstTagReader interface to allow fine-tuning of
+ tag-reading behaviour
+
+API: gst_tag_reader_get_type
+API: gst_tag_reader_add_interface_to_type
+API: gst_tag_reader_set_tag_reading_mode
+API: gst_tag_reader_get_tag_reading_mode
+API: gst_tag_reading_mode_get_type
+
+The GstTagReader interface may be implemented by elements that
+extract metadata to allow the fine-tuning of the tag-reading
+process (see #564749).
+---
+ docs/libs/gst-plugins-base-libs-docs.sgml | 1 +
+ docs/libs/gst-plugins-base-libs-sections.txt | 17 ++
+ gst-libs/gst/tag/Makefile.am | 5 +-
+ gst-libs/gst/tag/gsttagreader.c | 286 ++++++++++++++++++++++++++
+ gst-libs/gst/tag/gsttagreader.h | 110 ++++++++++
+ 5 files changed, 417 insertions(+), 2 deletions(-)
+ create mode 100644 gst-libs/gst/tag/gsttagreader.c
+ create mode 100644 gst-libs/gst/tag/gsttagreader.h
+
+diff --git a/docs/libs/gst-plugins-base-libs-docs.sgml b/docs/libs/gst-plugins-base-libs-docs.sgml
+index b7b61a7..453fb9a 100644
+--- a/docs/libs/gst-plugins-base-libs-docs.sgml
++++ b/docs/libs/gst-plugins-base-libs-docs.sgml
+@@ -190,6 +190,7 @@
+ <xi:include href="xml/gsttagxmp.xml" />
+ <xi:include href="xml/gsttagdemux.xml" />
+ <xi:include href="xml/gsttaglanguagecodes.xml" />
++ <xi:include href="xml/gsttagreader.xml" />
+ </chapter>
+
+ <chapter id="gstreamer-base-utils">
+diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt
+index 41235a0..b667b45 100644
+--- a/docs/libs/gst-plugins-base-libs-sections.txt
++++ b/docs/libs/gst-plugins-base-libs-sections.txt
+@@ -1822,6 +1822,23 @@ gst_tag_get_language_code_iso_639_2B
+ gst_tag_get_language_code_iso_639_2T
+ </SECTION>
+
++<SECTION>
++<FILE>gsttagreader</FILE>
++<INCLUDE>gst/tag/gsttagreader.h</INCLUDE>
++GstTagReader
++GstTagReadingMode
++gst_tag_reader_add_interface_to_type
++gst_tag_reader_set_tag_reading_mode
++gst_tag_reader_get_tag_reading_mode
++<SUBSECTION Standard>
++gst_tag_reading_mode_get_type
++GST_TAG_READER
++GST_TYPE_TAG_READER
++GST_IS_TAG_READER
++GST_TAG_READER_GET_IFACE
++GstTagReaderInterface
++</SECTION>
++
+ # base utils
+
+ <SECTION>
+diff --git a/gst-libs/gst/tag/Makefile.am b/gst-libs/gst/tag/Makefile.am
+index 9977d66..d12c7b7 100644
+--- a/gst-libs/gst/tag/Makefile.am
++++ b/gst-libs/gst/tag/Makefile.am
+@@ -2,13 +2,14 @@ libgsttagincludedir = \
+ $(includedir)/gstreamer-@GST_MAJORMINOR@/gst/tag
+
+ libgsttaginclude_HEADERS = \
+- tag.h gsttagdemux.h xmpwriter.h
++ tag.h gsttagdemux.h xmpwriter.h gsttagreader.h
+
+ lib_LTLIBRARIES = libgsttag-@GST_MAJORMINOR@.la
+
+ libgsttag_@GST_MAJORMINOR@_la_SOURCES = \
+ gstvorbistag.c gstid3tag.c gstxmptag.c gstexiftag.c \
+- lang.c tags.c gsttagdemux.c gsttageditingprivate.c xmpwriter.c
++ lang.c tags.c gsttagdemux.c gsttageditingprivate.c xmpwriter.c \
++ gsttagreader.c
+ libgsttag_@GST_MAJORMINOR@_la_CFLAGS = $(GST_PLUGINS_BASE_CFLAGS) $(GST_BASE_CFLAGS) $(GST_CFLAGS)
+ libgsttag_@GST_MAJORMINOR@_la_LIBADD = $(GST_BASE_LIBS) $(GST_LIBS) $(LIBM)
+ libgsttag_@GST_MAJORMINOR@_la_LDFLAGS = $(GST_LIB_LDFLAGS) $(GST_ALL_LDFLAGS) $(GST_LT_LDFLAGS)
+diff --git a/gst-libs/gst/tag/gsttagreader.c b/gst-libs/gst/tag/gsttagreader.c
+new file mode 100644
+index 0000000..cfbd480
+--- /dev/null
++++ b/gst-libs/gst/tag/gsttagreader.c
+@@ -0,0 +1,286 @@
++/* GStreamer Tag Reader interface
++ * Copyright (C) 2009 Tim-Philipp Müller <tim centricular net>
++ * Copyright (C) 2008 Nokia Corporation.
++ *
++ * Contact: Stefan Kost <stefan.kost@nokia.com>
++ *
++ * tagreader.c: Tag Reader interface design
++ *
++ * 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., 59 Temple Place - Suite 330,
++ * Boston, MA 02111-1307, USA.
++ */
++
++/**
++ * SECTION:gsttagreader
++ * @short_description: Interface for setting a tag reading mode on elements
++ * supporting it
++ *
++ * <refsect2>
++ * <para>
++ * The #GstTagReader interface may be implemented by elements that extract
++ * metadata to allow the fine-tuning of the tag-reading process. The interface
++ * is not required by all elements that extract tags - it is perfectly
++ * acceptable to post tag messages on the bus and not implement this
++ * interface. The interface merely serves to indicate that an element supports
++ * one or more special tag reading modes which when set might result in
++ * more efficient tag processing in certain cases.
++ * </para>
++ * </refsect2>
++ * <refsect2>
++ * <title>Use cases</title>
++ * <para>
++ * There are currently two main use cases for this interface:
++ * <itemizedlist>
++ * <listitem>
++ * by-passing possibly time- or memory-consuming tag extraction: useful
++ * for example if the goal is to just play a file, but things like embedded
++ * coverart or tags are not of interest.
++ * </listitem>
++ * <listitem>
++ * optimised tag and stream info extraction: useful if all that's of interest
++ * is tags and other metadata and full-scale playback functionality is not
++ * required; this allows demuxers to bypass possibly expensive index processing
++ * or index building, for example.
++ * </listitem>
++ * </itemizedlist>
++ * </para>
++ * </refsect2>
++ * <refsect2>
++ * <title>How to use #GstTagReader in applications</title>
++ * <para>
++ * Application writers who want to avoid the (usually very small) overhead of
++ * tag extraction when playing back media can put uridecodebin or decodebin2
++ * (or the elements in their pipeline directly, if they implement the
++ * interface) into tag reading mode #GST_TAG_READING_MODE_SKIP_TAGS using
++ * gst_tag_reader_set_tag_reading_mode() before starting the pipeline.
++ * </para>
++ * <para>
++ * Application writers who want to extract tags and other metadata as fast and
++ * efficiently as possible should use the 'tagreadbin' element, which will
++ * handle everything for them, and which will then use the #GstTagReader
++ * interface internally.
++ * </para>
++ * </refsect2>
++ * <refsect2>
++ * <title>How to implement the #GstTagReader in elements</title>
++ * <para>
++ * #GstTagReader is a 'dummy interface' similar to #GstTagSetter, meaning that
++ * there are no interface methods to implement. All that needs to be done is
++ * to add the interface to an element's GType in the element's _get_type()
++ * function or GST_BOILERPLATE_FULL macro. This can be done using the
++ * convenience function gst_tag_reader_add_interface_to_type().
++ * </para>
++ * <para>
++ * Elements implementing the interface should then query the configured tag
++ * reading mode when starting up (ie. in the start function or in the
++ * state change function in the NULL to READY transition), using
++ * gst_tag_reader_get_tag_reading_mode().
++ * </para>
++ * <para>
++ * In #GST_TAG_READING_MODE_SKIP_TAGS mode elements should skip metadata
++ * processing wherever this is possible without affecting functionality
++ * otherwise. Element should not post TAG messages on the bus in this mode.
++ * </para>
++ * <para>
++ * In #GST_TAG_READING_MODE_DEFAULT mode elements should behave like they
++ * normally would. For most elements this means tag extraction and normal
++ * stream handling.
++ * </para>
++ * <para>
++ * In #GST_TAG_READING_MODE_TAGS_ONLY mode elements are requested to skip
++ * any non-essential data processing. Demuxers, for example, may choose not
++ * to parse a seek index or build a seek table, but should still parse
++ * file headers and add pads and push newsegment events and data as they
++ * usually would (however, they are not required to reproduce output in the
++ * way they would for normal playback, e.g. they may push only key frames,
++ * which is all that is required for thumbnailing purposes).
++ * </para>
++ * <para>
++ * Elements in #GST_TAG_READING_MODE_TAGS_ONLY are required to properly
++ * aggregate or pass upstream flow returns. If they are driving the pipeline
++ * they will also need to EOS on #GST_FLOW_UNEXPECTED flow returns from
++ * downstream. This is how the <literal>tagreadbin</literal> element will
++ * stop streaming once it has collected all information.
++ * </para>
++ * </refsect2>
++ * <refsect2>
++ * <title>Tag-handling guidelines for all demuxers and parsers</title>
++ * <para>
++ * Below some general guidelines on how demuxers, parsers and decoders should
++ * handle tags.
++ * </para>
++ * <para>
++ * Demuxers should push tag events for 'global' tag before pushing tags
++ * with per-stream information. This global tag list should contain a
++ * #GST_TAG_CONTAINER_FORMAT tag. They also should push global tags and
++ * per-stream tags separately.
++ * </para>
++ * <para>
++ * Parsers and decoders should ensure that they cache tag events received from
++ * upstream and push them on their source pad before any tags of their own
++ * are pushed, maintaining the order of the tag events as they came in.
++ * </para>
++ * <para>
++ * Since 0.10.24
++ * </para>
++ * </refsect2>
++ */
++
++#ifdef HAVE_CONFIG_H
++#include "config.h"
++#endif
++
++#include "gsttagreader.h"
++
++/* key for g_object_{set|get}_qdata() */
++static GQuark tag_reading_mode_quark = 0;
++
++#define GST_TAG_READER_GET_MODE(obj) \
++ GPOINTER_TO_INT (g_object_get_qdata (obj, tag_reading_mode_quark))
++#define GST_TAG_READER_SET_MODE(obj,mode) \
++ g_object_set_qdata (obj, tag_reading_mode_quark, GINT_TO_POINTER (mode))
++
++GType
++gst_tag_reader_get_type (void)
++{
++ static GType gst_tag_reader_type = 0;
++
++ if (!gst_tag_reader_type) {
++ static const GTypeInfo gst_tag_reader_info = {
++ sizeof (GstTagReaderInterface),
++ (GBaseInitFunc) NULL,
++ NULL,
++ NULL,
++ NULL,
++ NULL,
++ 0,
++ 0,
++ NULL,
++ };
++
++ gst_tag_reader_type = g_type_register_static (G_TYPE_INTERFACE,
++ "GstTagReader", &gst_tag_reader_info, 0);
++
++ tag_reading_mode_quark = g_quark_from_static_string ("GstTagReadingMode");
++ }
++
++ return gst_tag_reader_type;
++}
++
++/**
++ * gst_tag_reader_add_interface_to_type:
++ * @type: a newly-registered GType
++ *
++ * Convenience function to add the #GstTagReader interface to an element.
++ * Use from within the element's _get_type() function or in connection
++ * with GST_BOILERPLATE_FULL.
++ *
++ * Since: 0.10.24
++ */
++void
++gst_tag_reader_add_interface_to_type (GType type)
++{
++ static const GInterfaceInfo tr_iface_info = { NULL, NULL, NULL, };
++
++ g_type_add_interface_static (type, GST_TYPE_TAG_READER, &tr_iface_info);
++}
++
++/**
++ * gst_tag_reader_set_tag_reading_mode:
++ * @reader: a #GstTagReader to set the tag reading mode on.
++ * @mode: tag reading mode to operate in.
++ *
++ * This will set the tag reader's mode of operation. You should
++ * use this method to tell a tag reader capable element in which
++ * #GstTagReadingMode the reader should operate in.
++ *
++ * This function will take the object lock and must not be called with the
++ * object lock already held.
++ *
++ * Since: 0.10.24
++ */
++void
++gst_tag_reader_set_tag_reading_mode (GstTagReader * reader,
++ GstTagReadingMode mode)
++{
++ GObject *obj;
++
++ g_return_if_fail (reader != NULL);
++ g_return_if_fail (GST_IS_TAG_READER (reader));
++ g_return_if_fail (GST_IS_ELEMENT (reader));
++
++ obj = G_OBJECT (reader);
++
++ GST_OBJECT_LOCK (obj);
++ if (GST_STATE (obj) == GST_STATE_NULL) {
++ GST_TAG_READER_SET_MODE (obj, mode);
++ GST_LOG_OBJECT (obj, "configured mode: %d", mode);
++ } else if (GST_TAG_READER_GET_MODE (obj) != mode) {
++ g_warning ("Can't set tag reading mode on element '%s': element must be "
++ "in NULL state", GST_ELEMENT_NAME (obj));
++ }
++ GST_OBJECT_UNLOCK (obj);
++}
++
++/**
++ * gst_tag_reader_get_tag_reading_mode:
++ * @reader: a #GstTagReader to get the tag reading mode from.
++ *
++ * Query the currently configured #GstTagReadingMode.
++ *
++ * This function will take the object lock and must not be called with the
++ * object lock already held.
++ *
++ * Returns: configured tag reading mode.
++ *
++ * Since: 0.10.24
++ */
++GstTagReadingMode
++gst_tag_reader_get_tag_reading_mode (GstTagReader * reader)
++{
++ GstTagReadingMode mode;
++ GObject *obj;
++
++ g_return_val_if_fail (reader != NULL, GST_TAG_READING_MODE_DEFAULT);
++ g_return_val_if_fail (GST_IS_TAG_READER (reader),
++ GST_TAG_READING_MODE_DEFAULT);
++ g_return_val_if_fail (GST_IS_ELEMENT (reader), GST_TAG_READING_MODE_DEFAULT);
++
++ obj = G_OBJECT (reader);
++
++ GST_OBJECT_LOCK (obj);
++ mode = GST_TAG_READER_GET_MODE (obj);
++ GST_OBJECT_UNLOCK (obj);
++
++ return mode;
++}
++
++GType
++gst_tag_reading_mode_get_type (void)
++{
++ static GType etype = 0;
++ if (etype == 0) {
++ static const GEnumValue values[] = {
++ {GST_TAG_READING_MODE_DEFAULT, "GST_TAG_READING_MODE_DEFAULT", "default"},
++ {GST_TAG_READING_MODE_TAGS_ONLY, "GST_TAG_READING_MODE_TAGS_ONLY",
++ "tags-only"},
++ {GST_TAG_READING_MODE_SKIP_TAGS, "GST_TAG_READING_MODE_SKIP_TAGS",
++ "skip-tags"},
++ {0, NULL, NULL}
++ };
++ etype = g_enum_register_static ("GstTagReadingMode", values);
++ }
++ return etype;
++}
+diff --git a/gst-libs/gst/tag/gsttagreader.h b/gst-libs/gst/tag/gsttagreader.h
+new file mode 100644
+index 0000000..5c39f85
+--- /dev/null
++++ b/gst-libs/gst/tag/gsttagreader.h
+@@ -0,0 +1,110 @@
++/* GStreamer Tag Reader interface
++ * Copyright (C) 2009 Tim-Philipp Müller <tim centricular net>
++ * Copyright (C) 2008 Nokia Corporation.
++ *
++ * Contact: Stefan Kost <stefan.kost@nokia.com>
++ *
++ * tagreader.h: Tag Reader interface design
++ *
++ * 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., 59 Temple Place - Suite 330,
++ * Boston, MA 02111-1307, USA.
++ */
++
++#ifndef __GST_TAG_READER_H__
++#define __GST_TAG_READER_H__
++
++#include <gst/gst.h>
++
++G_BEGIN_DECLS
++
++/**
++ * GstTagReadingMode:
++ * @GST_TAG_READING_MODE_DEFAULT: parse both metadata and audio/video stream
++ * data
++ * @GST_TAG_READING_MODE_TAGS_ONLY: parse metadata and process only as much
++ * audio/video data as required to extract basic information about the
++ * stream such as tags, available streams and duration
++ * @GST_TAG_READING_MODE_SKIP_TAGS: don't extract any metadata, just process
++ * the audio/video stream data (behaviour should generally be the same as
++ * with #GST_TAG_READING_MODE_DEFAULT, only that tag extraction is skipped)
++ *
++ * Available tag reading modes.
++ *
++ * Since: 0.10.24
++ */
++/* keep gst_tag_reading_mode_get_type() in sync when adding enums here */
++typedef enum {
++ GST_TAG_READING_MODE_DEFAULT = 0,
++ GST_TAG_READING_MODE_TAGS_ONLY,
++ GST_TAG_READING_MODE_SKIP_TAGS
++} GstTagReadingMode;
++
++#define GST_TYPE_TAG_READING_MODE (gst_tag_reading_mode_get_type())
++GType gst_tag_reading_mode_get_type (void);
++
++
++#define GST_TYPE_TAG_READER \
++ (gst_tag_reader_get_type ())
++#define GST_TAG_READER(obj) \
++ (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_TAG_READER, GstTagReader))
++#define GST_IS_TAG_READER(obj) \
++ (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_TAG_READER))
++#define GST_TAG_READER_GET_IFACE(inst) \
++ (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GST_TYPE_TAG_READER, \
++ GstTagReaderInterface))
++
++/**
++ * GstTagReader:
++ *
++ * Opaque #GstTagReader structure (dummy typedef to denote object instances
++ * which implement the #GstTagReader interface).
++ *
++ * Since: 0.10.24
++ */
++typedef struct _GstTagReader GstTagReader;
++typedef struct _GstTagReaderInterface GstTagReaderInterface;
++
++/**
++ * GstTagReaderInterface:
++ *
++ * Dummy interface structure. Elements do not need to implement any interface
++ * methods, all they need to do is query the desired tag reading mode via
++ * gst_tag_reader_get_tag_reading_mode() where and when appropriate/required.
++ *
++ * Since: 0.10.24
++ */
++struct _GstTagReaderInterface {
++ GTypeInterface iface;
++
++ /* methods: no methods to implement at this time */
++
++ /* interfaces don't need padding, so no padding here */
++};
++
++GType gst_tag_reader_get_type (void);
++
++void gst_tag_reader_add_interface_to_type (GType type);
++
++/* public methods */
++
++void gst_tag_reader_set_tag_reading_mode (GstTagReader * reader,
++ GstTagReadingMode mode);
++
++GstTagReadingMode gst_tag_reader_get_tag_reading_mode (GstTagReader * reader);
++
++G_END_DECLS
++
++#endif /* __GST_TAG_READER_H__ */
++
projects / mafwsubrenderer / blobdiff