mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-03-28 20:05:38 +00:00
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
This commit is contained in:
David I. Lehn
parent
ddc2769c2d
commit
bb16c73875
15 changed files with 503 additions and 500 deletions
40
AUTHORS
40
AUTHORS
|
|
@ -1,39 +1 @@
|
|||
.. 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.
|
||||
|
|
|
|||
10
ChangeLog
10
ChangeLog
|
|
@ -1,3 +1,13 @@
|
|||
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
|
||||
|
|
|
|||
11
NEWS
11
NEWS
|
|
@ -1,10 +1 @@
|
|||
.. 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.
|
||||
|
|
|
|||
187
README
187
README
|
|
@ -1,186 +1 @@
|
|||
.. 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.
|
||||
|
|
|
|||
28
TODO
28
TODO
|
|
@ -1,27 +1 @@
|
|||
.. 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
|
||||
])
|
||||
|
|
|
|||
3
docs/.gitignore
vendored
Normal file
3
docs/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
gst-python.html
|
||||
gst-python.txt
|
||||
gst-python.pdf
|
||||
13
docs/HEAD.in
13
docs/HEAD.in
|
|
@ -1,13 +0,0 @@
|
|||
.. 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::
|
||||
|
|
@ -1,27 +1,21 @@
|
|||
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)
|
||||
|
|
|
|||
7
docs/common.xsl
Normal file
7
docs/common.xsl
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
<?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>
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
[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
|
||||
|
|
@ -1,191 +0,0 @@
|
|||
/*
|
||||
: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 }
|
||||
435
docs/gst-python.xml
Normal file
435
docs/gst-python.xml
Normal file
|
|
@ -0,0 +1,435 @@
|
|||
<?xml version='1.0'?>
|
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<article id="gst-python">
|
||||
<articleinfo>
|
||||
<publisher><publishername>The GStreamer Development Team</publishername></publisher>
|
||||
<pubdate>June ??, 2003</pubdate>
|
||||
<copyright><year>2003</year><holder>David I. Lehn</holder></copyright>
|
||||
<title><application>gst-python</application>: A Python Interface to GStreamer</title>
|
||||
<titleabbrev>gst-python</titleabbrev>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>David</firstname>
|
||||
<othername role="mi">I.</othername>
|
||||
<surname>Lehn</surname>
|
||||
<email>dlehn@users.sourceforge.net</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<abstract>
|
||||
<para>Introductory information for the GStreamer Python bindings.</para>
|
||||
<para><ulink url="http://www.gstreamer.net/bindings/python/"/></para>
|
||||
</abstract>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>0.1.0</revnumber>
|
||||
<date>2003-06-??</date>
|
||||
<authorinitials>dil</authorinitials>
|
||||
<revremark>Initial version.</revremark>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</articleinfo>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="about">
|
||||
<title>About</title>
|
||||
<para>
|
||||
|
||||
<application>gst-python</application>: the <ulink url="http://www.python.org/">Python</ulink> bindings for the <ulink url="http://www.gstreamer.net/">GStreamer</ulink> project. These bindings provide access to almost all of the GStreamer C API through an object oriented Python API.
|
||||
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="news">
|
||||
<title>News</title>
|
||||
<para>
|
||||
<informaltable frame="all">
|
||||
<tgroup cols="3">
|
||||
<colspec align="center"/>
|
||||
<colspec align="center"/>
|
||||
<colspec align="left"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Date</entry>
|
||||
<entry>Version</entry>
|
||||
<entry>Notes</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>2003-06-xx</entry>
|
||||
<entry>0.1.0</entry>
|
||||
<entry>first release</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="installation">
|
||||
<title>Installation</title>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="requirements">
|
||||
<title>Requirements</title>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Python 2.2 (<ulink url="http://www.python.org/"/>)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
GStreamer 0.6.x (<emphasis>except</emphasis> 0.6.1) (<ulink url="http://www.gstreamer.net/"/>)
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
PyGTK 1.99.14 (<ulink url="http://www.daa.com.au/~james/pygtk/"/>)
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="building">
|
||||
<title>Building and Installation</title>
|
||||
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
$ ./configure && make
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="using">
|
||||
<title>Using</title>
|
||||
<para>
|
||||
You either need to install the package or add the root directory to your
|
||||
Python path:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
$ export PYTHONPATH=$PYTHONPATH:`pwd`
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Try running examples:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<screen>
|
||||
$ cd examples/gstreamer/
|
||||
$ python cp.py <input file> <output file>
|
||||
$ cmp <input file> <output file>
|
||||
$ python vorbisplay.py <an Ogg Vorbis file>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="programming">
|
||||
<title>Programming</title>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="general-api">
|
||||
<title>General API</title>
|
||||
<para>
|
||||
|
||||
The gst-python bindings are directly generated from the GStreamer headers. Look at the GStreamer documentation at <ulink url="http://www.gstreamer.net/docs/"/> for general API and programming issues. In most cases the GStreamer classes and boxed types map directly to Python classes. The function-based GObject methods also map onto Python methods.
|
||||
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="divergence-from-c-api">
|
||||
<title>Divergence From C API</title>
|
||||
|
||||
<para>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 <xref linkend="python-elements" endterm="python-elements.title"/>. A
|
||||
few others remain that return GList* or return values in their parameters.
|
||||
These have been wrapped as needed. Please file a <link
|
||||
linkend="bugs">bug</link> if you need one of the unwrapped functions.</para>
|
||||
|
||||
<para>API changes:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem><para><function>gst_props_entry_get_type</function> is accessed
|
||||
through <function>PropsEntry.get_props_type</function>(). This is due to the
|
||||
<function>_get_type</function> function extention being normally used for
|
||||
<function>GType</function> access and is inaccessable
|
||||
otherwise.</para></listitem>
|
||||
|
||||
<listitem><para>Special <link linkend="pipeline-iteration">pipeline
|
||||
iteration</link> support through the following functions:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem><para><function>add_iterate_bin</function>(<parameter
|
||||
class="function">bin</parameter>) -> <returnvalue>id</returnvalue>: used
|
||||
to iterate a bin with a C idle loop callback instead of a Python
|
||||
callback.</para></listitem>
|
||||
|
||||
<listitem><para><function>remove_iterate_bin</function>(<parameter
|
||||
class="function">id</parameter>): used to remove the
|
||||
<function>add_iterate_bin</function> idle loop callback
|
||||
id.</para></listitem>
|
||||
|
||||
<listitem><para><function>iterate_bin_all</function>(<parameter
|
||||
class="function">bin</parameter>): releases locks, calls
|
||||
<function>gst_bin_iterate</function> until it returns 0, reacquires locks
|
||||
and completes</para></listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem><para><link linkend="python-elements">Python Elements</link> support through the following currently horribly inefficient functions:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem><para><function>Buffer.get_data</function>() ->
|
||||
<returnvalue>string</returnvalue>: converts buffer data to a string and
|
||||
returns it.</para></listitem>
|
||||
|
||||
<listitem><para><function>Buffer.set_data</function>(<parameter
|
||||
class="function">string</parameter>): sets the buffer data from a
|
||||
string.</para></listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="examples">
|
||||
<title>Examples</title>
|
||||
|
||||
<para>The best documentation right now are the examples in <filename
|
||||
class="directory">./examples/gstreamer/</filename>. Read them.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="threads">
|
||||
<title>Threads</title>
|
||||
|
||||
<para>Threading is a tricky subject for gst-python. There are a few lock you
|
||||
need to be aware of:</para>
|
||||
|
||||
<section id="gil">
|
||||
<title>GIL</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>Python calls wrapper function</para></listitem>
|
||||
<listitem><para>wrapper function calls C GStreamer function</para></listitem>
|
||||
<listitem><para>C GStreamer function calls side effect code</para></listitem>
|
||||
<listitem><para>side effect code calls callback</para></listitem>
|
||||
<listitem><para>callback tries to acquire Python GIL but it's already locked</para></listitem>
|
||||
<listitem><para>deadlocked...</para></listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>Please file a <link linkend="bugs">bug</link> if you have problems
|
||||
related to this and need other functions to be specially handled.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="gdk-lock">
|
||||
<title>Gdk Lock</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="pipeline-iteration">
|
||||
<title>Pipeline Iteration</title>
|
||||
|
||||
<para>There are a number of ways to iterate pipelines.
|
||||
<filename>./examples/gstreamer/bps.py</filename> 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.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para><function>Bin.iterate</function>() in Python from the gtk idle loop</para></listitem>
|
||||
<listitem><para><function>gst_bin_iterate</function>() in C from gtk idle loop</para></listitem>
|
||||
<listitem><para><function>Bin.iterate</function>() in a Python loop</para></listitem>
|
||||
<listitem><para><function>gst_bin_iterate</function>() in a C loop</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The method you chose depends on your application. The idle loop methods
|
||||
are slightly slower yet more flexible. Probably useful for interactive GUI
|
||||
applications.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="python-elements">
|
||||
<title id="python-elements.title">Python Elements</title>
|
||||
|
||||
<para> It is possible to write Python subclasses of GstElement. This support
|
||||
is very primitive and likely to change. See
|
||||
<filename>./examples/gstreamer/rot13.py</filename> for an example.</para>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="bugs">
|
||||
<title>Bugs</title>
|
||||
<para>
|
||||
<emphasis>Please</emphasis> submit gst-python bugs, patches, or suggestions to GNOME Bugzilla (<ulink url="http://bugzilla.gnome.org/"/>). Product: GStreamer, Component: gst-python. Or alternatively send a message to the gstreamer-devel list or the maintainer. Thank you.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="todo">
|
||||
<title>TODO</title>
|
||||
<itemizedlist>
|
||||
<listitem><para>handle more of the functions that need manual wrapping code</para></listitem>
|
||||
<listitem><para>add check that pygtk built with <parameter class="command">--enable-thread</parameter></para></listitem>
|
||||
<listitem><para>improve Python gstreamer.Element creation</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>perhaps drop <function>_set_foo_function</function>() calls in favor of object methods</para></listitem>
|
||||
<listitem><para>sane buffer handling with buffer type or Numeric?</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>docs</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>API ref</para></listitem>
|
||||
<listitem><para>manual</para></listitem>
|
||||
<listitem><para>tutorial</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>more examples</para></listitem>
|
||||
<listitem><para>convert build system to distutils</para></listitem>
|
||||
<listitem><para>wrap other GStreamer helper libs</para></listitem>
|
||||
<listitem><para>add some standard widgets</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>gtk video widget (similar to widget gst-player is using)</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>testsuite</para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
<section id="authors">
|
||||
<title>Authors</title>
|
||||
|
||||
<para>
|
||||
Please feel free to contact the developers. They hang out on IRC (<ulink url="http://gstreamer.net/dev/"/>) and the mailing lists (<ulink url="http://gstreamer.net/contact/lists.php"/>).
|
||||
</para>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="maintainer">
|
||||
<title>Maintainer</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>David I. Lehn <email>dlehn at users.sourceforge.net</email></para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="contributions">
|
||||
<title>Contributions</title>
|
||||
<para>
|
||||
Patches, suggestions, and other help:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Kenichi Sato <email>ksato at users.sourceforge.net</email></para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
Much of the framework for gst-python stolen from gtk and gconf bindings by:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>James Henstridge <email>james at daa.com.au</email></para></listitem>
|
||||
<listitem><para>Johan Dahlin <email>jdahlin at telia.com</email></para></listitem>
|
||||
<listitem><para>Matt Wilson <email>msw at redhat.com</email></para></listitem>
|
||||
<listitem><para>and many more...</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
<section id="gstreamer-team">
|
||||
<title>GStreamer Team</title>
|
||||
<para>
|
||||
And of course, none of this would be possible without the extreme hacker mojo
|
||||
of the whole GStreamer crew!
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<!--=================-->
|
||||
|
||||
</section>
|
||||
|
||||
<!--=====================================================================-->
|
||||
|
||||
</article>
|
||||
8
docs/html.xsl
Normal file
8
docs/html.xsl
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
<?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>
|
||||
18
docs/pdf.xsl
Normal file
18
docs/pdf.xsl
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
<?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>
|
||||
Loading…
Reference in a new issue