diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | AUTHORS | 40 | ||||
| -rw-r--r-- | ChangeLog | 3 | ||||
| -rw-r--r-- | NEWS | 10 | ||||
| -rw-r--r-- | README | 184 | ||||
| -rw-r--r-- | TODO | 16 | ||||
| -rw-r--r-- | docs/HEAD.in | 13 | ||||
| -rw-r--r-- | docs/Makefile.am | 27 | ||||
| -rw-r--r-- | docs/docutils.conf | 9 | ||||
| -rw-r--r-- | docs/gst-python.css | 191 |
10 files changed, 468 insertions, 26 deletions
@@ -2,6 +2,7 @@ Makefile Makefile.in gst-python.spec aclocal.m4 +autoregen.sh config.cache config.guess config.h @@ -1,11 +1,39 @@ -gst-python authors: +.. gst-python AUTHORS +.. This file writen with docutils markup (http://docutils.sourceforge.net/) -David I. Lehn <dlehn@users.sourceforge.net> +Contact +======= +Please feel free to contact the developers. They hang out on IRC_ and the +mailing lists_. + +.. _IRC: http://gstreamer.net/dev/ +.. _lists: http://gstreamer.net/contact/lists.php + +Authors +======= + +Maintainer +---------- + +* David I. Lehn <dlehn@users.sourceforge.net> + +Contributions +------------- + +Patches, suggestions, and other help: + +* Kenichi Sato <ksato@users.sourceforge.net>) Much of the framework for gst-python stolen from gtk and gconf bindings by: -James Henstridge <james@daa.com.au> -Johan Dahlin <jdahlin@telia.com> -Matt Wilson <msw@redhat.com> -and many more... +* James Henstridge <james@daa.com.au> +* Johan Dahlin <jdahlin@telia.com> +* Matt Wilson <msw@redhat.com> +* and many more... + +GStreamer +--------- + +And of course, none of this would be possible without the extreme hacker mojo +of the whole GStreamer crew! @@ -4,6 +4,9 @@ * configure.ac, Makefile.am, pkgconfig/*: add pkgconfig support + * AUTHORS, NEWS, README, TODO, docs/HEAD.in, docs/Makefile.am, + docs/docutils.conf, docs/gst-python.css: docutils based docs + 2003-06-11 Thomas Vander Stichele <thomas at apestaart dot org> * gst-python.spec.in: fix @@ -0,0 +1,10 @@ +.. gst-python NEWS +.. This file writen with docutils markup (http://docutils.sourceforge.net/) + +News +==== + +2003-06-xx - 0.1.0 released +--------------------------- + +* first release @@ -1,36 +1,186 @@ -gst-python -========== +.. gst-python README +.. This file writen with docutils markup (http://docutils.sourceforge.net/) -This is gst-python, the Python[1] bindings for the GStreamer[2] project. +About +===== -For further help ask on a GStreamer mailing list or IRC. +This is **gst-python**, the Python_ bindings for the GStreamer_ project. The +bindings provide access to almost all of the GStreamer C API through an object +oriented Python API. -[1] http://www.python.org/ -[2] http://www.gstreamer.net/ +.. _Python: http://www.python.org/ +.. _GStreamer: http://www.gstreamer.net/ -build/install -------------- +Requirements +============ -For build and install information please refer to the "INSTALL" file. -Installation is optional, gst-python can be used from the build directory. +* Python_ 2.2 +* GStreamer_ 0.6.0 +* PyGTK_ 1.99.14 +.. _PyGTK: http://www.daa.com.au/~james/pygtk/ -using ------ + +Build/Install +============= + +For build and install information please refer to the "``INSTALL``" file. +Installation is optional, gst-python can be used from the build directory. The +quick instructions: build and install PyGTK and GStreamer then build +gst-python:: + + $ ./configure && make + + +Using +===== You either need to install the package or add the root directory to your -Python path. +Python path:: $ export PYTHONPATH=$PYTHONPATH:`pwd` -Try running an example: +Try running examples:: $ cd examples/gstreamer/ $ python cp.py <input file> <output file> + $ cmp <input file> <output file> + $ python vorbisplay.py <a vorbis file> + + +Documentation +============= + +General/API +----------- + +The gst-python bindings are directly generated from the GStreamer headers. +Look at the GStreamer documentation_ for general API and programming issues. +In most cases the GStreamer classes and boxed types map directly to Python +classes. The function-based methods also map onto Python object methods. + +.. _documentation: http://www.gstreamer.net/docs/ + + +Divergence From C API +--------------------- + +Due to the nature of C and Python some of the GStreamer API is handled slightly +different in Python than C. There are a few of the GStreamer C functions that +are not yet provided in gst-python. These are mostly related to creating +`Python Elements`_. A few others remain that return GList* or return values in +their parameters. These have been wrapped as needed. Please file a bug_ if +you need one of the unwrapped functions. + +API changes: + +* ``gst_props_entry_get_type`` is accessed through + ``PropsEntry.get_props_type()``. This is due to the ``_get_type`` function + extention being normally used for ``GType`` access and is inaccessable + otherwise. + +* Special `Pipeline Iteration`_ support through the following functions: + + * ``add_iterate_bin(bin) -> id``: used to iterate a bin with a C idle loop + callback instead of a Python callback. + * ``remove_iterate_bin(id)``: used to remove the ``add_iterate_bin`` + idle loop callback id. + * ``iterate_bin_all(bin)``: releases locks, calls ``gst_bin_iterate`` + until it returns 0, reacquires locks and completes + +* `Python Elements`_ support through the following horribly inefficient + functions: + + * ``Buffer.get_data() -> string``: converts buffer data to a string and + returns it. + * ``Buffer.set_data(string)``: sets the buffer data from a string. + + +Examples +-------- + +The best documentation right now is the examples in +"``./examples/gstreamer/``". Read them. + + +Threads +------- + +Threading is a tricky subject for gst-python. There are a few lock you need to +be aware of: + +* GIL + + The CPython interpreter is single threaded. Code execution in the + interpreter is protected by a Global Interpreter Lock (GIL). This means that + C code can run in other threads in parallel but only one thread will be + running Python code at any one point. Most of this is handled internally by + means of locking and unlocking the GIL at appropriate times. Callback code + and other various code paths between Python and C *should* be setup to do + proper GIL handling. + + However, it is possible that you may encounter a situation where proper + locking is not done. This is most likely due to calling a wrapper function + that follows a sequence like this: + + - Python -> wrapper function + - wrapper function -> C GStreamer function + - C GStreamer function -> side effect code + - side effect code -> callback + - callback -> tries to acquire Python GIL but it's already locked + - deadlocked... + + This has been fixed for commonly called functions that have side effects + which are likely to re-enter the interpreter. It just involves lock/unlock + around the call to the C gst function. But doing it for every function could + have performance issues and, more importantly, is not an automated process. + + Please file a bug_ if you have problems related to this and need other + functions to be specially handled. + +* Gdk lock + + If you are using PyGTK you will have to deal with Gdk locking. Make sure + you're holding the Gdk lock while executing Gdk/Gtk calls. See PyGTK + documentation and FAQ list for more information. + + +Pipeline Iteration +------------------ + +There are a number of ways to iterate pipelines. ./examples/gstreamer/bps.py +is a small test program to measure the performance in buffers per second of +these various techniques. Please see the example for how to use these +techniques. + +* Bin.iterate() in Python from the gtk idle loop +* gst_bin_iterate() in C from gtk idle loop +* Bin.iterate() in a Python loop +* gst_bin_iterate() in a C loop + +The method you chose depends on your application. The idle loop methods are +slightly slower yet more flexible. Probably useful for interactive GUI +applications. + +The basic loop methods are faster but probably more use for non-interactive +applications. A variation on these loops would be to also check for a stop +condition which may provide performance increase and some level of control. + + +Python Elements +--------------- + +It is possible to write Python subclasses of GstElement. This support is very +primitive and likely to change. See "``./examples/gstreamer/rot13.py``" for an +example. + +Bugs +==== -documentation -------------- +*Please* submit gst-python bugs, patches, or suggestions to GNOME Bugzilla_, +Product: GStreamer, Component: gst-python. Thank you. -The examples are the best documentation for now. Read them. +.. _Bugzilla: http://bugzilla.gnome.org/ +.. _bug: `Bugs`_ @@ -1,17 +1,27 @@ -gst-python TODO -=============== +.. gst-python TODO +.. This file writen with docutils markup (http://docutils.sourceforge.net/) + +TODO +==== - handle more of the functions that need manual wrapping code - add check that pygtk built with --enable-thread - improve Python gstreamer.Element creation - - perhaps make drop _set_foo_function() calls in favor of object methods + + - perhaps drop _set_foo_function() calls in favor of object methods - sane buffer handling with buffer type or Numeric? + - docs + - API ref - manual - tutorial + - more examples - convert build system to distutils - wrap other GStreamer helper libs - add some standard widgets + - gtk video widget (similar to widget gst-player is using) + +- testsuite diff --git a/docs/HEAD.in b/docs/HEAD.in new file mode 100644 index 0000000..fb780c8 --- /dev/null +++ b/docs/HEAD.in @@ -0,0 +1,13 @@ +.. gst-python HEAD.in +.. This file writen with docutils markup (http://docutils.sourceforge.net/) + +========== +gst-python +========== + +:Author: David I. Lehn +:Contact: dlehn@users.sourceforge.net +:Web site: http://www.gstreamer.net/bindings/python/ +:Version: @VERSION@ + +.. contents:: diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..da04cda --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,27 @@ +EXTRA_DIST = HEAD.in docutils.conf gst-python.css + +DOCS = \ + $(srcdir)/HEAD \ + $(top_srcdir)/NEWS \ + $(top_srcdir)/README \ + $(top_srcdir)/TODO \ + $(top_srcdir)/AUTHORS + +gst-python.html: docutils.conf ${DOCS} + @if [ ! $$DOCUTILSHOME ]; then \ + echo "ERROR: Please set \$$DOCUTILSHOME"; \ + exit 1; \ + fi + @if [ ! -r $$DOCUTILSHOME/tools/html.py ]; then \ + echo "\$$DOCUTILSHOME/tools/html.py not found"; \ + exit 1; \ + fi + rm -f gst-python.txt + for doc in ${DOCS}; do \ + cat $$doc >> gst-python.txt; \ + printf "\n" >> gst-python.txt; \ + done + PYTHONPATH=$$PYTHONPATH:$$DOCUTILSHOME $$DOCUTILSHOME/tools/html.py gst-python.txt gst-python.html + lynx -dump -force_html gst-python.html > gst-python.out + +CLEANFILES = gst-python.txt gst-python.html diff --git a/docs/docutils.conf b/docs/docutils.conf new file mode 100644 index 0000000..2f455f9 --- /dev/null +++ b/docs/docutils.conf @@ -0,0 +1,9 @@ +[options] + +# These entries affect all processing: +source-link: 1 +datestamp: %Y-%m-%d %H:%M UTC +generator: 1 + +# These entries affect HTML output: +stylesheet-path: gst-python.css diff --git a/docs/gst-python.css b/docs/gst-python.css new file mode 100644 index 0000000..fe8dc8e --- /dev/null +++ b/docs/gst-python.css @@ -0,0 +1,191 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date$ +:version: $Revision$ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +.first { + margin-top: 0 } + +.last { + margin-bottom: 0 } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.line-block { + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.option-argument { + font-style: italic } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +th.docinfo-name, th.field-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + font-size: 100% } + +tt { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } |