gst \
tools \
pkgconfig \
+ docs \
po
DIST_SUBDIRS = $(SUBDIRS)
tools/launcher/Makefile
tools/launcher/apps/Makefile
tools/launcher/apps/validate/Makefile
+docs/Makefile
+docs/version.entities
+docs/validate/Makefile
])
AC_OUTPUT
--- /dev/null
+SUBDIRS = validate
+DIST_SUBDIRS = validate
+
+upload:
+ @if test "x$(SUBDIRS)" != x; then for a in $(SUBDIRS); do cd $$a; make upload; cd ..; done; fi
+
+libs: validate
+
+include $(top_srcdir)/common/parallel-subdirs.mak
--- /dev/null
+GST_DOC_SCANOBJ = $(top_srcdir)/common/gstdoc-scangobj
+## Process this file with automake to produce Makefile.in
+
+# The name of the module, e.g. 'glib'.
+MODULE=gst-validate
+DOC_MODULE=gst-validate
+
+# don't want $(DOC_MODULE)-scan.c to be built with -Werror
+ERROR_CFLAGS=
+
+# for upload-doc.mak
+DOC=gst-validate
+FORMATS=html
+html: html-build.stamp
+include $(top_srcdir)/common/upload-doc.mak
+
+# The top-level SGML file. Change it if you want.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code.
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting functions and macros.
+DOC_SOURCE_DIR=$(top_srcdir)/gst/validate/
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=--deprecated-guards="GST_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-fixref.
+FIXXREF_OPTIONS=--extra-dir=$(top_builddir)/docs/gst/html \
+ --extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html \
+ --extra-dir=$(datadir)/gtk-doc/html
+
+# Used for dependencies.
+HFILE_GLOB=$(top_srcdir)/gst/validate/gst-validate-scenario.h
+CFILE_GLOB=$(top_srcdir)/gst/validate/gst-validate-scenario.c
+
+# Extra options to pass to gtkdoc-scanobj or gtkdoc-scangobj.
+SCANOBJ_OPTIONS=--type-init-func="gst_init(&argc,&argv); gst_validate_init()"
+
+# Header files to ignore when scanning.
+IGNORE_HFILES = \
+ gettext.h \
+ gst-validate-internal.h \
+ gst-validate-monitor.h \
+ gst-validate-bin-monitor.h \
+ gst-validate-element-monitor.h \
+ gst-validate-pad-monitor.h \
+ gst-validate-override.h \
+ gst-validate-override-registry.h \
+ gst-validate-utils.h \
+ gst-validate-media-info.h \
+ gst-validate-report.h \
+ media-descriptor.h \
+ media-descriptor-parser.h \
+ media-descriptor-writer.h \
+ gst-validate-i18n-lib.h
+
+IGNORE_CFILES = \
+ gst-validate-monitor.c \
+ gst-validate-bin-monitor.c \
+ gst-validate-pad-monitor.c \
+ gst-validate-element-monitor.c \
+ gst-validate-override.c \
+ gst-validate-override-registry.c \
+ gst-validate-utils.c \
+ gst-validate-report.c \
+ gst-validate-media-info.c \
+ media-descriptor.c \
+ media-descriptor-parser.c \
+ media-descriptor-writer.c \
+ gst-validate-i18n-lib.c
+
+# Images to copy into HTML directory.
+# HTML_IMAGES = gdp-header.png
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+content_files =
+
+# Other files to distribute.
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
+# contains GtkObjects/GObjects and you want to document signals and properties.
+GTKDOC_CFLAGS = -I$(top_srcdir) $(GST_PBUTILS_CFLAGS) $(GST_BASE_CFLAGS) \
+ $(GST_CFLAGS) $(GIO_CFLAGS) $(GCOV_CFLAGS)
+GTKDOC_LIBS = \
+ $(top_builddir)/gst/validate/libgstvalidate-@GST_API_VERSION@.la \
+ $(GST_BASE_LIBS) $(GST_LIBS) $(GIO_LIBS) $(GCOV_LIBS)
+
+GTKDOC_CC=$(LIBTOOL) --tag=CC --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --tag=CC --mode=link $(CC)
+
+# If you need to override some of the declarations, place them in this file
+# and uncomment this line.
+DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
+
+include $(top_srcdir)/common/gtk-doc.mak
+
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+ <bookinfo>
+ <title>gst-validate Reference Manual</title>
+ <releaseinfo>
+ for GstValidate &GST_API_VERSION;
+ </releaseinfo>
+ </bookinfo>
+
+ <chapter>
+ <title>GstValidate documentation</title>
+ <xi:include href="xml/validate.xml"/>
+ <xi:include href="xml/gst-validate-runner.xml"/>
+ <xi:include href="xml/gst-validate-scenario.xml"/>
+ <xi:include href="xml/gst-validate-monitor-factory.xml"/>
+
+ </chapter>
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
--- /dev/null
+<SECTION>
+<FILE>validate</FILE>
+<TITLE>Initialization</TITLE>
+gst_validate_init
+</SECTION>
+
+<SECTION>
+<FILE>gst-validate-monitor-factory</FILE>
+<TITLE>GstValidate monitoring system</TITLE>
+gst_validate_monitor_factory_create
+</SECTION>
+
+<SECTION>
+<FILE>gst-validate-runner</FILE>
+<TITLE>GstValidateRunner</TITLE>
+GstValidateRunner
+GstValidateRunnerClass
+gst_validate_runner_new
+gst_validate_runner_get_reports_count
+gst_validate_runner_printf
+<SUBSECTION Private>
+gst_validate_runner_get_reports
+gst_validate_runner_add_report
+<SUBSECTION Standard>
+GST_IS_VALIDATE_RUNNER
+GST_VALIDATE_RUNNER_CAST
+GST_VALIDATE_RUNNER_CLASS_CAST
+GST_IS_VALIDATE_RUNNER_CLASS
+GST_TYPE_VALIDATE_RUNNER
+GST_VALIDATE_RUNNER
+GST_VALIDATE_RUNNER_CLASS
+GST_VALIDATE_RUNNER_GET_CLASS
+gst_validate_runner_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gst-validate-scenario</FILE>
+<TITLE>GstValidateScenario</TITLE>
+GstValidateExecuteAction
+GstValidateAction
+GstValidateActionParameter
+GstValidateScenario
+GstValidateScenarioClass
+gst_validate_print_action_types
+gst_validate_list_scenarios
+gst_validate_add_action_type
+gst_validate_action_get_clocktime
+gst_validate_scenario_execute_seek
+GstValidateActionType
+<SUBSECTION Private>
+gst_validate_scenario_factory_create
+<SUBSECTION Standard>
+GST_IS_VALIDATE_ACTION
+GST_IS_VALIDATE_ACTION_TYPE
+GST_IS_VALIDATE_SCENARIO
+GST_IS_VALIDATE_SCENARIO_CLASS
+GST_TYPE_VALIDATE_ACTION
+GST_TYPE_VALIDATE_ACTION_TYPE
+GST_TYPE_VALIDATE_SCENARIO
+GST_VALIDATE_ACTION_TYPE
+GST_VALIDATE_SCENARIO
+GST_VALIDATE_SCENARIO_CLASS
+GST_VALIDATE_SCENARIO_GET_CLASS
+GstValidateScenarioPrivate
+gst_validate_action_get_type
+gst_validate_action_type_get_type
+gst_validate_scenario_get_type
+</SECTION>
--- /dev/null
+#include <gst/gst.h>
+#include <gst/validate/validate.h>
+
+gst_validate_action_get_type
+gst_validate_action_type_get_type
+gst_validate_report_get_type
+gst_validate_reporter_get_type
+gst_validate_runner_get_type
+gst_validate_scenario_get_type
--- /dev/null
+<!ENTITY GST_API_VERSION "1.0">
--- /dev/null
+<!ENTITY GST_API_VERSION "@GST_API_VERSION@">
typedef struct _GstValidateScenario GstValidateScenario;
typedef struct _GstValidateAction GstValidateAction;
typedef struct _GstValidateActionParameter GstValidateActionParameter;
+typedef struct _GstValidateActionType GstValidateActionType;
typedef gboolean (*GstValidateExecuteAction) (GstValidateScenario * scenario, GstValidateAction * action);
struct _GstValidateActionType
gpointer _gst_reserved[GST_PADDING_LARGE];
};
+
+GST_EXPORT GType _gst_validate_action_type_type;
+
void init_scenarios (void);
#endif
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gst-validate-monitor-factory
+ * @short_description: Lets you start monitoring a #GstObject with GstValidate
+ *
+ * To start monitoring and thus run GstValidate tests on a #GstPipeline, the only thing to
+ * do is to instanciate a #GstValidateRunner and then attach a #GstValidateMonitor
+ * to it with #gst_validate_monitor_factory_create
+ */
+
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
#include "gst-validate-pad-monitor.h"
#include "gst-validate-override-registry.h"
+/**
+ * gst_validate_monitor_factory_create:
+ * @target: The #GstObject to create a #GstValidateMonitor for
+ * @runner: The #GstValidateRunner to use for the new monitor
+ * @parent: (optional): The parent of the new monitor
+ *
+ * Create a new monitor for @target and starts monitoring it.
+ *
+ * Returns: The newly created #GstValidateMonitor
+ */
GstValidateMonitor *
gst_validate_monitor_factory_create (GstObject * target,
GstValidateRunner * runner, GstValidateMonitor * parent)
* SECTION:gst-validate-runner
* @short_description: Class that runs Gst Validate tests for a pipeline
*
- * TODO
+ * Allows you to test a pipeline within GstValidate. It is the object where
+ * all issue reporting is done.
+ *
+ * In the tools using GstValidate the only minimal code to be able to monitor
+ * your pipelines is:
+ *
+ * |[
+ * GstPipeline *pipeline = gst_pipeline_new ("monitored-pipeline");
+ * GstValidateRunner *runner = gst_validate_runner_new ();
+ * GstValidateMonitor *monitor = gst_validate_monitor_factory_create (
+ * GST_OBJECT (pipeline), runner, NULL);
+ *
+ * // Run the pipeline and do whatever you want with it
+ *
+ * // In that same order
+ * gst_object_unref (pipeline);
+ * gst_object_unref (runner);
+ * gst_object_unref (monitor);
+ * ]|
*/
#define gst_validate_runner_parent_class parent_class
/**
* gst_validate_runner_new:
+ *
+ * Create a new #GstValidateRunner
+ *
+ * Returns: A newly created #GstValidateRunner
*/
GstValidateRunner *
gst_validate_runner_new (void)
g_signal_emit (runner, _signals[REPORT_ADDED_SIGNAL], 0, report);
}
+/**
+ * gst_validate_runner_get_reports_count:
+ * @runner: The $GstValidateRunner to get the number of report from
+ *
+ * Get the number of reports present in the runner:
+ *
+ * Returns: The number of report present in the runner.
+ */
guint
gst_validate_runner_get_reports_count (GstValidateRunner * runner)
{
return runner->reports;
}
+/**
+ * gst_validate_runner_printf:
+ * @runner: The #GstValidateRunner to print all the reports for
+ *
+ * Prints all the report on the terminal or on wherever set
+ * on the #GST_VALIDATE_FILE env variable.
+ *
+ * Retrurns: 0 if no critical error has been found and 18 if a critical
+ * error as been detected. That return value is usually to be used as
+ * exit code of the application.
+ * */
int
gst_validate_runner_printf (GstValidateRunner * runner)
{
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gst-validate-scenario
+ * @short_description: A GstValidateScenario represents a set of actions to be executed on a pipeline.
+ *
+ * A #GstValidateScenario represents the scenario that will be executed on a #GstPipeline.
+ * It is basically an ordered list of #GstValidateAction that will be executed during the
+ * execution of the pipeline.
+ *
+ * To be able to simply define that list of actions, a dedicated file format is used. This
+ * file format is based on the #GstStructure serialized format which is a basic, type aware,
+ * key value format. It takes the type of the action as first coma separeted field, and then
+ * the key values pair of the form 'parameter=value' are separated by comas. The values
+ * type will be guessed if not casted as in 'parameter=(string)value'. You can force the type
+ * guessing system to actually know what type you want by giving it the right hints. For example
+ * to make sure the value is a double, you should add a decimal (ie '1' will be concidered as a
+ * int, but '1.0' will be concidered as a double and '"1.0"' will be concidered as a string)
+ *
+ * For example to represent a seek action, you should add the following line in the '.scenario'
+ * file.
+ *
+ * |[
+ * seek, playback_time=10.0, start=0.0, flags=accurate+flush
+ * ]|
+ *
+ *
+ * The files to be used as scenario should have a '.scenario' extension and
+ * should be placed either in $USER_DATA_DIR/gstreamer-1.0/validate-scenario ,
+ * $GST_DATADIR/gstreamer-1.0/validate-scenario or in a path defined in the
+ * $GST_VALIDATE_SCENARIOS_PATH environment variable.
+ *
+ * Each line in the '.scenario' file represent an action (you can also use \ at the end of a line
+ * write a single action on multiple lines). Usually you should start you scenario with a 'description'
+ * "config" action in order for the user to have more information about the scenario. It can contain
+ * a 'summary' field which is a string explaning what the scenario does and then several info fields
+ * about the scenario. You can find more info about it running:
+ *
+ * |[
+ * gst-validate-1.0 --list-action-types description
+ * ]|
+ *
+ * So a basic scenario file that will seek three times and stop would look like:
+ *
+ * |[
+ *
+ * description, summary="Seeks at 1.0 to 2.0 then at \
+ * 3.0 to 0.0 and then seeks at \
+ * 1.0 to 2.0 for 1.0 second (between 2.0 and 3.0).", \
+ * seek=true, duration=5.0, min-media-duration=4.0
+ * seek, playback_time=1.0, rate=1.0, start=2.0, flags=accurate+flush
+ * seek, playback_time=3.0, rate=1.0, start=0.0, flags=accurate+flush
+ * seek, playback_time=1.0, rate=1.0, start=2.0, stop=3.0, flags=accurate+flush
+ * ]|
+ *
+ * Many action types have been implemented to help users define their own scenarios.
+ * For example there are:
+ * <itemizedlist><title>Action type examples:</title>
+ * <listitem><para>
+ * seek: Seeks into the stream
+ * </para></listitem>
+ * <listitem><para>
+ * play: Set the pipeline state to GST_STATE_PLAYING
+ * </para></listitem>
+ * <listitem><para>
+ * pause: Set the pipeline state to GST_STATE_PAUSED
+ * </para></listitem>
+ * <listitem><para>
+ * stop: Stop the execution of the pipeline. NOTE: That action actually post a
+ * #GST_MESSAGE_REQUEST_STATE (requesting #GST_STATE_NULL) message on the bus and
+ * the application should quit.
+ * </para></listitem>
+ * <listitem><para>
+ * ...
+ * </para></listitem>
+ * </itemizedlist>
+ *
+ * To get all the details about the registered action types, you can list them all with:
+ *
+ * |[
+ * gst-validate-1.0 --list-action-types
+ * ]|
+ *
+ * and (includes transcoding specific action types):
+ *
+ * |[
+ * gst-validate-transcoding-1.0 --list-action-types
+ * ]|
+ *
+ * You can also register new types yourself thanks to #gst_validate_add_action_type. And you will be able
+ * to print the action types details thanks to the #gst_validate_print_action_types function in your own
+ * tool.
+ *
+ * Many scenarios are distributed with gst-validate, you can list them all using:
+ *
+ * |[
+ * gst-validate-1.0 --list-scenarios
+ * ]|
+ */
#ifdef HAVE_CONFIG_H
#include "config.h"
return FALSE;
}
+/**
+ * gst_validate_action_get_clocktime:
+ * @scenario: The #GstValidateScenario from which to get a time
+ * for a parameter of an action
+ * @action: The action from which to retrieve the time for @name
+ * parameter.
+ * @name: The name of the parameter for which to retrive a time
+ * @retval: (out): The return value for the wanted time
+ *
+ *
+ * Get a time value for the @name parameter of an action. This
+ * method should be called to retrived and compute a timed value of a given
+ * action. It will first try to retrieve the value as a double,
+ * then get it as a string and execute any formula taking into account
+ * the 'position' and 'duration' variables. And it will always convert that
+ * value to a GstClockTime.
+ *
+ * Returns: %TRUE if the time value could be retrieved/computed or %FALSE otherwize
+ */
gboolean
gst_validate_action_get_clocktime (GstValidateScenario * scenario,
GstValidateAction * action, const gchar * name, GstClockTime * retval)
return TRUE;
}
+/**
+ * gst_validate_scenario_execute_seek:
+ * @scenario: The #GstValidateScenario for which to execute a seek action
+ * @action: The seek action to execute
+ * @rate: The playback rate of the seek
+ * @format: The #GstFormat of the seek
+ * @flags: The #GstSeekFlags of the seek
+ * @start_type: The #GstSeekType of the start value of the seek
+ * @start: The start time of the seek
+ * @stop_type: The #GstSeekType of the stop value of the seek
+ * @stop: The stop time of the seek
+ *
+ * Executes a seek event on the scenario' pipeline. You should always use
+ * that method when you want to execute a seek inside a new action types
+ * so that the scenario state is updated taking into account that seek.
+ *
+ * For more information you should have a look at #gst_event_new_seek
+ *
+ * Returns: %TRUE if the seek could be executed, %FALSE otherwize
+ */
gboolean
gst_validate_scenario_execute_seek (GstValidateScenario * scenario,
GstValidateAction * action, gdouble rate, GstFormat format,
return res;
}
+/**
+ * gst_validate_add_action_type:
+ * @type_name: The name of the new action type to add
+ * @function: (scope notified): The function to be called to execute the action
+ * @parameters: The #GstValidateActionParameter usable as parameter of the type
+ * @description: A description of the new type
+ * @is_config: Whether the action is a config action or not. A config action will
+ * be executed even before the pipeline starts processing
+ *
+ * Register a new action type to the action type system. If the action type already
+ * exists, it will be overriden by that new definition
+ */
void
gst_validate_add_action_type (const gchar * type_name,
GstValidateExecuteAction function,
return NULL;
}
+/**
+ * gst_validate_print_action_types:
+ * @wanted_types: (array length=num_wanted_types): (optional): List of types to be printed
+ * @num_wanted_types: (optional): Length of @wanted_types
+ *
+ * Prints the action types details wanted in @wanted_types
+ *
+ * Returns: True if all types could be printed
+ */
gboolean
gst_validate_print_action_types (gchar ** wanted_types, gint num_wanted_types)
{
typedef struct _GstValidateScenarioClass GstValidateScenarioClass;
typedef struct _GstValidateScenarioPrivate GstValidateScenarioPrivate;
typedef struct _GstValidateAction GstValidateAction;
-typedef struct _GstValidateActionType GstValidateActionType;
typedef struct _GstValidateActionParameter GstValidateActionParameter;
+GST_EXPORT GType _gst_validate_action_type;
+
+/**
+ * GstValidateExecuteAction:
+ * @scenario: The #GstValidateScenario from which the @action is executed
+ * @action: The #GstValidateAction being executed
+ *
+ *
+ * This function that executes a #GstValidateAction
+ *
+ * Returns: %True if the action could be executed %FALSE otherwise
+ */
typedef gboolean (*GstValidateExecuteAction) (GstValidateScenario * scenario, GstValidateAction * action);
-GST_EXPORT GType _gst_validate_action_type;
-GST_EXPORT GType _gst_validate_action_type_type;
+/**
+ * GstValidateAction:
+ * @type: The type of the #GstValidateAction, which is the name of the
+ * GstValidateActionType registered with
+ * #gst_validate_add_action_type
+ * @name: The name of the action, set from the user in the scenario
+ * @structure: the #GstStructure defining the action
+ *
+ * The GstValidateAction defined to be executed as part of a scenario
+ */
struct _GstValidateAction
{
GstMiniObject mini_object;
+ /*< public > */
const gchar *type;
const gchar *name;
+ GstStructure *structure;
+
+ /* < private > */
guint action_number;
gint repeat;
GstClockTime playback_time;
- GstStructure *structure;
gpointer _gst_reserved[GST_PADDING_LARGE];
};
gboolean gst_validate_print_action_types (gchar ** wanted_types, gint num_wanted_types);
+/**
+ * GstValidateActionParameter:
+ * @name: The name of the parameter
+ * @description: The description of the parameter
+ * @mandatory: Whether the parameter is mandatory for
+ * a specific action type
+ * @types: The types the parameter can take described as a
+ * string. It can be precisely describing how the typing works
+ * using '\n' between the various acceptable types.
+ * @possible_variables: The name of the variables that can be
+ * used to compute the value of the parameter.
+ * For example for the start value of a seek
+ * action, we will accept to take 'duration'
+ * which will be replace by the total duration
+ * of the stream on which the action is executed.
+ * @def: The default value of a parametter as a string, should be %NULL
+ * for mandatory streams.
+ */
struct _GstValidateActionParameter
{
const gchar *name;
{
GObjectClass parent_class;
+ /*< public >*/
+ /*< private >*/
gpointer _gst_reserved[GST_PADDING];
};
+/**
+ * GstValidateScenario:
+ * @pipeline: The #GstPipeline on which the scenario is being executed.
+ */
struct _GstValidateScenario
{
GObject parent;
+ /*< public >*/
GstElement *pipeline;
+
+ /*< private >*/
GstValidateScenarioPrivate *priv;
gpointer _gst_reserved[GST_PADDING];
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:validate
+ * @short_description: Initialize GstValidate
+ */
#ifdef HAVE_CONFIG_H
# include "config.h"
GST_DEBUG_CATEGORY (gstvalidate_debug);
+/**
+ * gst_validate_init:
+ *
+ * Initializes GstValidate, call that before any usage of GstValidate.
+ * You should take care of initilizing GStreamer before calling this
+ * function.
+ */
void
gst_validate_init (void)
{
projects / platform / upstream / gstreamer.git / commitdiff