Commit bb16c738 authored by David I. Lehn's avatar David I. Lehn

kill docutils based docs (easy come, easy go) docbook based docs

Original commit message from CVS:
kill docutils based docs (easy come, easy go)
docbook based docs
parent ddc2769c
.. gst-python AUTHORS
.. This file writen with docutils markup (http://docutils.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...
GStreamer
---------
And of course, none of this would be possible without the extreme hacker mojo
of the whole GStreamer crew!
The gst-python AUTHORS list is maintained at docs/gst-python.xml#authors.
2003-06-26 David I. Lehn <dlehn@users.sourceforge.net>
* configure.ac, AUTHORS, NEWS, README, TODO, docs/Makefile.am,
docs/HEAD.in docs/docutils.conf, docs/gst-python.css:
kill docutils based docs (easy come, easy go)
* AUTHORS, NEWS, README, TODO, docs/Makefile.am, docs/gst-python.xml,
docs/common.xsl, docs/html.xsl, docs/pdf.xsl, docs/gst-python.css:
docbook based docs
2003-06-25 David I. Lehn <dlehn@users.sourceforge.net>
* gstreamer/Makefile.am: fix up line continuations
......
.. gst-python NEWS
.. This file writen with docutils markup (http://docutils.sourceforge.net/)
News
====
2003-06-xx - 0.1.0 released
---------------------------
* first release
The gst-python NEWS is maintained at docs/gst-python.xml#news.
.. gst-python README
.. This file writen with docutils markup (http://docutils.sourceforge.net/)
About
=====
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.
.. _Python: http://www.python.org/
.. _GStreamer: http://www.gstreamer.net/
Requirements
============
* Python_ 2.2
* GStreamer_ 0.6.0
* PyGTK_ 1.99.14
.. _PyGTK: http://www.daa.com.au/~james/pygtk/
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::
$ export PYTHONPATH=$PYTHONPATH:`pwd`
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
====
*Please* submit gst-python bugs, patches, or suggestions to GNOME Bugzilla_,
Product: GStreamer, Component: gst-python. Thank you.
.. _Bugzilla: http://bugzilla.gnome.org/
.. _bug: `Bugs`_
The gst-python README is maintained in doc/gst-python.xml.
.. 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 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
The gst-python TODO list is maintained at docs/gst-python.xml#todo.
......@@ -119,6 +119,5 @@ AC_OUTPUT([
examples/Makefile
examples/gstreamer/Makefile
docs/Makefile
docs/HEAD
gst-python.spec
])
gst-python.html
gst-python.txt
gst-python.pdf
.. 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::
EXTRA_DIST = HEAD.in docutils.conf gst-python.css
XMLFILES = gst-python.xml
XSLFILES = common.xsl html.xsl
CSSFILES = gst-python.css
DOCS = \
$(srcdir)/HEAD \
$(top_srcdir)/NEWS \
$(top_srcdir)/README \
$(top_srcdir)/TODO \
$(top_srcdir)/AUTHORS
DOCS = gst-python.txt gst-python.html
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
all: $(DOCS)
CLEANFILES = gst-python.txt gst-python.html
gst-python.txt: gst-python.xml
xmlto txt $<
# cp gst-python.txt $(top_builddir)/../README
gst-python.html: gst-python.xml common.xsl html.xsl
xmlto -m common.xsl -m html.xsl xhtml-nochunks $<
gst-python.pdf: gst-python.xml common.xsl pdf.xsl
xmlto -m common.xsl -m pdf.xsl pdf $<
CLEANFILES = $(DOCS)
EXTRA_DIST = $(XMLFILES) $(XSLFILES) $(CSSFILES)
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<xsl:param name="use.id.as.filename" select="1"/>
</xsl:stylesheet>
[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
/*
: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 }
This diff is collapsed.
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:param name="html.stylesheet" select="'gst-python.css'"/>
<xsl:param name="linenumbering.extension" select="1"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:param name="body.margin.top">0.5in</xsl:param>
<xsl:template name="is.graphic.extension">
<xsl:param name="ext"></xsl:param>
<xsl:if test="$ext = 'png'
or $ext = 'pdf'
or $ext = 'jpeg'
or $ext = 'gif'
or $ext = 'tif'
or $ext = 'tiff'
or $ext = 'bmp'">1</xsl:if>
</xsl:template>
</xsl:stylesheet>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment