mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-24 09:10:36 +00:00
validate: Document the API with gtk-doc
This commit is contained in:
parent
45ffbdec07
commit
e5b485d776
15 changed files with 516 additions and 5 deletions
|
@ -6,6 +6,7 @@ SUBDIRS = \
|
||||||
gst \
|
gst \
|
||||||
tools \
|
tools \
|
||||||
pkgconfig \
|
pkgconfig \
|
||||||
|
docs \
|
||||||
po
|
po
|
||||||
|
|
||||||
DIST_SUBDIRS = $(SUBDIRS)
|
DIST_SUBDIRS = $(SUBDIRS)
|
||||||
|
|
|
@ -282,6 +282,9 @@ tools/Makefile
|
||||||
tools/launcher/Makefile
|
tools/launcher/Makefile
|
||||||
tools/launcher/apps/Makefile
|
tools/launcher/apps/Makefile
|
||||||
tools/launcher/apps/validate/Makefile
|
tools/launcher/apps/validate/Makefile
|
||||||
|
docs/Makefile
|
||||||
|
docs/version.entities
|
||||||
|
docs/validate/Makefile
|
||||||
])
|
])
|
||||||
AC_OUTPUT
|
AC_OUTPUT
|
||||||
|
|
||||||
|
|
9
validate/docs/Makefile.am
Normal file
9
validate/docs/Makefile.am
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
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
|
101
validate/docs/validate/Makefile.am
Normal file
101
validate/docs/validate/Makefile.am
Normal file
|
@ -0,0 +1,101 @@
|
||||||
|
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
|
||||||
|
|
37
validate/docs/validate/gst-validate-docs.sgml
Normal file
37
validate/docs/validate/gst-validate-docs.sgml
Normal file
|
@ -0,0 +1,37 @@
|
||||||
|
<?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>
|
68
validate/docs/validate/gst-validate-sections.txt
Normal file
68
validate/docs/validate/gst-validate-sections.txt
Normal file
|
@ -0,0 +1,68 @@
|
||||||
|
<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>
|
9
validate/docs/validate/gst-validate.types
Normal file
9
validate/docs/validate/gst-validate.types
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
#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
|
1
validate/docs/version.entities
Normal file
1
validate/docs/version.entities
Normal file
|
@ -0,0 +1 @@
|
||||||
|
<!ENTITY GST_API_VERSION "1.0">
|
1
validate/docs/version.entities.in
Normal file
1
validate/docs/version.entities.in
Normal file
|
@ -0,0 +1 @@
|
||||||
|
<!ENTITY GST_API_VERSION "@GST_API_VERSION@">
|
|
@ -30,6 +30,7 @@ GST_DEBUG_CATEGORY_EXTERN (gstvalidate_debug);
|
||||||
typedef struct _GstValidateScenario GstValidateScenario;
|
typedef struct _GstValidateScenario GstValidateScenario;
|
||||||
typedef struct _GstValidateAction GstValidateAction;
|
typedef struct _GstValidateAction GstValidateAction;
|
||||||
typedef struct _GstValidateActionParameter GstValidateActionParameter;
|
typedef struct _GstValidateActionParameter GstValidateActionParameter;
|
||||||
|
typedef struct _GstValidateActionType GstValidateActionType;
|
||||||
typedef gboolean (*GstValidateExecuteAction) (GstValidateScenario * scenario, GstValidateAction * action);
|
typedef gboolean (*GstValidateExecuteAction) (GstValidateScenario * scenario, GstValidateAction * action);
|
||||||
|
|
||||||
struct _GstValidateActionType
|
struct _GstValidateActionType
|
||||||
|
@ -48,6 +49,9 @@ struct _GstValidateActionType
|
||||||
gpointer _gst_reserved[GST_PADDING_LARGE];
|
gpointer _gst_reserved[GST_PADDING_LARGE];
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
|
GST_EXPORT GType _gst_validate_action_type_type;
|
||||||
|
|
||||||
void init_scenarios (void);
|
void init_scenarios (void);
|
||||||
|
|
||||||
#endif
|
#endif
|
||||||
|
|
|
@ -21,6 +21,15 @@
|
||||||
* Boston, MA 02111-1307, USA.
|
* 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
|
#ifdef HAVE_CONFIG_H
|
||||||
# include "config.h"
|
# include "config.h"
|
||||||
#endif
|
#endif
|
||||||
|
@ -30,6 +39,16 @@
|
||||||
#include "gst-validate-pad-monitor.h"
|
#include "gst-validate-pad-monitor.h"
|
||||||
#include "gst-validate-override-registry.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 *
|
GstValidateMonitor *
|
||||||
gst_validate_monitor_factory_create (GstObject * target,
|
gst_validate_monitor_factory_create (GstObject * target,
|
||||||
GstValidateRunner * runner, GstValidateMonitor * parent)
|
GstValidateRunner * runner, GstValidateMonitor * parent)
|
||||||
|
|
|
@ -35,7 +35,25 @@
|
||||||
* SECTION:gst-validate-runner
|
* SECTION:gst-validate-runner
|
||||||
* @short_description: Class that runs Gst Validate tests for a pipeline
|
* @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
|
#define gst_validate_runner_parent_class parent_class
|
||||||
|
@ -86,6 +104,10 @@ gst_validate_runner_init (GstValidateRunner * runner)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* gst_validate_runner_new:
|
* gst_validate_runner_new:
|
||||||
|
*
|
||||||
|
* Create a new #GstValidateRunner
|
||||||
|
*
|
||||||
|
* Returns: A newly created #GstValidateRunner
|
||||||
*/
|
*/
|
||||||
GstValidateRunner *
|
GstValidateRunner *
|
||||||
gst_validate_runner_new (void)
|
gst_validate_runner_new (void)
|
||||||
|
@ -102,6 +124,14 @@ gst_validate_runner_add_report (GstValidateRunner * runner,
|
||||||
g_signal_emit (runner, _signals[REPORT_ADDED_SIGNAL], 0, report);
|
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
|
guint
|
||||||
gst_validate_runner_get_reports_count (GstValidateRunner * runner)
|
gst_validate_runner_get_reports_count (GstValidateRunner * runner)
|
||||||
{
|
{
|
||||||
|
@ -117,6 +147,17 @@ gst_validate_runner_get_reports (GstValidateRunner * runner)
|
||||||
return runner->reports;
|
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
|
int
|
||||||
gst_validate_runner_printf (GstValidateRunner * runner)
|
gst_validate_runner_printf (GstValidateRunner * runner)
|
||||||
{
|
{
|
||||||
|
|
|
@ -20,6 +20,103 @@
|
||||||
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||||||
* Boston, MA 02111-1307, USA.
|
* 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
|
#ifdef HAVE_CONFIG_H
|
||||||
#include "config.h"
|
#include "config.h"
|
||||||
|
@ -249,6 +346,25 @@ _set_variable_func (const gchar * name, double *value, gpointer user_data)
|
||||||
return FALSE;
|
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
|
gboolean
|
||||||
gst_validate_action_get_clocktime (GstValidateScenario * scenario,
|
gst_validate_action_get_clocktime (GstValidateScenario * scenario,
|
||||||
GstValidateAction * action, const gchar * name, GstClockTime * retval)
|
GstValidateAction * action, const gchar * name, GstClockTime * retval)
|
||||||
|
@ -283,6 +399,26 @@ gst_validate_action_get_clocktime (GstValidateScenario * scenario,
|
||||||
return TRUE;
|
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
|
gboolean
|
||||||
gst_validate_scenario_execute_seek (GstValidateScenario * scenario,
|
gst_validate_scenario_execute_seek (GstValidateScenario * scenario,
|
||||||
GstValidateAction * action, gdouble rate, GstFormat format,
|
GstValidateAction * action, gdouble rate, GstFormat format,
|
||||||
|
@ -1835,6 +1971,18 @@ done:
|
||||||
return res;
|
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
|
void
|
||||||
gst_validate_add_action_type (const gchar * type_name,
|
gst_validate_add_action_type (const gchar * type_name,
|
||||||
GstValidateExecuteAction function,
|
GstValidateExecuteAction function,
|
||||||
|
@ -1892,6 +2040,15 @@ gst_validate_list_action_types (void)
|
||||||
return NULL;
|
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
|
gboolean
|
||||||
gst_validate_print_action_types (gchar ** wanted_types, gint num_wanted_types)
|
gst_validate_print_action_types (gchar ** wanted_types, gint num_wanted_types)
|
||||||
{
|
{
|
||||||
|
|
|
@ -40,24 +40,46 @@ typedef struct _GstValidateScenario GstValidateScenario;
|
||||||
typedef struct _GstValidateScenarioClass GstValidateScenarioClass;
|
typedef struct _GstValidateScenarioClass GstValidateScenarioClass;
|
||||||
typedef struct _GstValidateScenarioPrivate GstValidateScenarioPrivate;
|
typedef struct _GstValidateScenarioPrivate GstValidateScenarioPrivate;
|
||||||
typedef struct _GstValidateAction GstValidateAction;
|
typedef struct _GstValidateAction GstValidateAction;
|
||||||
typedef struct _GstValidateActionType GstValidateActionType;
|
|
||||||
typedef struct _GstValidateActionParameter GstValidateActionParameter;
|
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);
|
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
|
struct _GstValidateAction
|
||||||
{
|
{
|
||||||
GstMiniObject mini_object;
|
GstMiniObject mini_object;
|
||||||
|
|
||||||
|
/*< public > */
|
||||||
const gchar *type;
|
const gchar *type;
|
||||||
const gchar *name;
|
const gchar *name;
|
||||||
|
GstStructure *structure;
|
||||||
|
|
||||||
|
/* < private > */
|
||||||
guint action_number;
|
guint action_number;
|
||||||
gint repeat;
|
gint repeat;
|
||||||
GstClockTime playback_time;
|
GstClockTime playback_time;
|
||||||
GstStructure *structure;
|
|
||||||
|
|
||||||
gpointer _gst_reserved[GST_PADDING_LARGE];
|
gpointer _gst_reserved[GST_PADDING_LARGE];
|
||||||
};
|
};
|
||||||
|
@ -73,6 +95,24 @@ GType gst_validate_action_type_get_type (void);
|
||||||
|
|
||||||
gboolean gst_validate_print_action_types (gchar ** wanted_types, gint num_wanted_types);
|
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
|
struct _GstValidateActionParameter
|
||||||
{
|
{
|
||||||
const gchar *name;
|
const gchar *name;
|
||||||
|
@ -90,14 +130,23 @@ struct _GstValidateScenarioClass
|
||||||
{
|
{
|
||||||
GObjectClass parent_class;
|
GObjectClass parent_class;
|
||||||
|
|
||||||
|
/*< public >*/
|
||||||
|
/*< private >*/
|
||||||
gpointer _gst_reserved[GST_PADDING];
|
gpointer _gst_reserved[GST_PADDING];
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* GstValidateScenario:
|
||||||
|
* @pipeline: The #GstPipeline on which the scenario is being executed.
|
||||||
|
*/
|
||||||
struct _GstValidateScenario
|
struct _GstValidateScenario
|
||||||
{
|
{
|
||||||
GObject parent;
|
GObject parent;
|
||||||
|
|
||||||
|
/*< public >*/
|
||||||
GstElement *pipeline;
|
GstElement *pipeline;
|
||||||
|
|
||||||
|
/*< private >*/
|
||||||
GstValidateScenarioPrivate *priv;
|
GstValidateScenarioPrivate *priv;
|
||||||
|
|
||||||
gpointer _gst_reserved[GST_PADDING];
|
gpointer _gst_reserved[GST_PADDING];
|
||||||
|
|
|
@ -20,6 +20,10 @@
|
||||||
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||||||
* Boston, MA 02111-1307, USA.
|
* Boston, MA 02111-1307, USA.
|
||||||
*/
|
*/
|
||||||
|
/**
|
||||||
|
* SECTION:validate
|
||||||
|
* @short_description: Initialize GstValidate
|
||||||
|
*/
|
||||||
|
|
||||||
#ifdef HAVE_CONFIG_H
|
#ifdef HAVE_CONFIG_H
|
||||||
# include "config.h"
|
# include "config.h"
|
||||||
|
@ -30,6 +34,13 @@
|
||||||
|
|
||||||
GST_DEBUG_CATEGORY (gstvalidate_debug);
|
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
|
void
|
||||||
gst_validate_init (void)
|
gst_validate_init (void)
|
||||||
{
|
{
|
||||||
|
|
Loading…
Reference in a new issue