mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-23 02:01:12 +00:00
3f5a8814d5
Original commit message from CVS: 2004-02-24 Andy Wingo <wingo@pobox.com> * gst/gstelement.c (gst_element_dispose): Protect against multiple invocations. * gst/schedulers/gstoptimalscheduler.c I added a mess of prototypes at the top of the file by way of documentation. Some of the operations on chains and groups were re-organized. (create_group): Added a type argument so if the group is enabled, the setup_group_scheduler knows what to do. (group_elements): Added a type argument here, too, to be passed on to create_group. (group_element_set_enabled): If an unlinked PLAYING element is added to a bin, we have to create a new group to hold the element, and this function will be called before the group is added to the chain. Thus we have a valid case for group->chain==NULL. Instead of calling chain_group_set_enabled, just set the flag on the group (the chain's status will be set when the group is added to it). (gst_opt_scheduler_state_transition, chain_group_set_enabled): Setup the group scheduler when the group is enabled, not specifically when an element goes PAUSED->PLAYING. This means PLAYING elements can be added, linked, and scheduled into a PLAYING pipeline, as was intended. (add_to_group): Don't ref the group twice. I don't know when this double-ref got in here. Removing it has the potential to cause segfaults if other parts of the scheduler are buggy. If you find that the scheduler is segfaulting for you, put in an extra ref here and see if that hacks over the underlying issue. Of course, then find out what code is unreffing a group it doesn't own... (create_group): Make the extra refcount floating, and remove it after adding the element. This means that... (unref_group): Destroy when the refcount reaches 0, not 1, like every other refcounted object in the known universe. (remove_from_group): When a group becomes empty, set it to be not active, and remove it from its chain. Don't unref it again, there's no floating reference any more. (destroy_group): We have to remove the group from the chain in remove_from_group (rather than here) to break refcounting cycles (the chain always has a ref on the group). So assert that group->chain==NULL. (ref_group_by_count): Removed, it was commented out anyway. (merge_chains): Use the remove_from_chain and add_to_chain primitives to do the reparenting, instead of rolling our own implementation. (add_to_chain): The first non-disabled group in the chain's group list will be the entry point for the chain. Because buffers can accumulate in loop elements' peer bufpens, we preferentially schedule loop groups before get groups to avoid unnecessary execution of get-based groups when the bufpens are already full. (gst_opt_scheduler_schedule_run_queue): Debug fixes. (get_group_schedule_function): Ditto. (loop_group_schedule_function): Ditto. (gst_opt_scheduler_loop_wrapper): Ditto. (gst_opt_scheduler_iterate): Ditto. I understand the opt scheduler now, yippee! * gst/gstpad.c: All throughout, added FIXMEs to look at for 0.9. (gst_pad_get_name, gst_pad_set_chain_function) (gst_pad_set_get_function, gst_pad_set_event_function) (gst_pad_set_event_mask_function, gst_pad_get_event_masks) (gst_pad_get_event_masks_default, gst_pad_set_convert_function) (gst_pad_set_query_function, gst_pad_get_query_types) (gst_pad_get_query_types_default) (gst_pad_set_internal_link_function) (gst_pad_set_formats_function, gst_pad_set_link_function) (gst_pad_set_fixate_function, gst_pad_set_getcaps_function) (gst_pad_set_bufferalloc_function, gst_pad_unlink) (gst_pad_renegotiate, gst_pad_set_parent, gst_pad_get_parent) (gst_pad_add_ghost_pad, gst_pad_proxy_getcaps) (gst_pad_proxy_pad_link, gst_pad_proxy_fixate) (gst_pad_get_pad_template_caps, gst_pad_check_compatibility) (gst_pad_get_peer, gst_pad_get_allowed_caps) (gst_pad_alloc_buffer, gst_pad_push, gst_pad_pull) (gst_pad_selectv, gst_pad_select, gst_pad_template_get_caps) (gst_pad_event_default_dispatch, gst_pad_event_default) (gst_pad_dispatcher, gst_pad_send_event, gst_pad_convert_default) (gst_pad_convert, gst_pad_query_default, gst_pad_query) (gst_pad_get_formats_default, gst_pad_get_formats): Better argument checks, and some doc fixes. (gst_pad_custom_new_from_template): Um, does anyone use these functions? Actually make a custom pad instead of a normal one. (gst_pad_try_set_caps): Transpose some checks. (gst_pad_try_set_caps_nonfixed): Same, and use a macro to check if the pad is in negotiation. (gst_pad_try_relink_filtered): Use pad_link_prepare. * gst/gstelement.c: Remove prototypes also defined in gstclock.h. * gst/gstelement.h: * gst/gstclock.h: Un-deprecate the old clocking API, as discussed on the list. |
||
|---|---|---|
| .. | ||
| code-reviews | ||
| design | ||
| faq | ||
| gst | ||
| libs | ||
| manual | ||
| plugins | ||
| pwg | ||
| random | ||
| slides | ||
| xsl | ||
| .gitignore | ||
| htmlinstall.mak | ||
| image-eps | ||
| image-pdf | ||
| image-png | ||
| Makefile.am | ||
| manuals.mak | ||
| README | ||
| upload.mak | ||
| version.entities.in | ||
GStreamer documentation notes
IMPORTANT
=========
Please make sure you've read and understood everything in this file
before you try changing documentation.
OVERVIEW
========
GStreamer has two sets of documentation that we maintain:
* API references, using gtk-doc (gstreamer, gstreamer-libs)
* "books", using DocBook/XML (faq, manual, pwg)
DOCBOOK NOTES
=============
OK, I've grown so tired of having to coax the docs to build every time I
get round to it that I've decided to note down some of the things that
are important to know.
OVERVIEW
--------
* Our documentation should all be Docbook/XML. No SGML.
* The source for the documentation is:
- one or more .xml files, with the main one being gstreamer-(whatever).xml
- image files
- in .fig
- in .png (and maybe others)
* We want to generate docs in HTML, PS and PDF
* We want to use xmlto to generate these
CONVENTIONS
-----------
We stick to some simple conventions for writing docbook documentation.
* id names:
- all id's start with chapter-, part-, section-, or misc-
- verify this is the case by looking at the generated file names in html/
- sections should also include the chapter name;
for example in a chapter called chapter-example, a section would be
called section-example-hello-world
HOW IMAGES ARE HANDLED
----------------------
* the format of images used is:
- PNG for html
- EPS for ps
- PDF for pdf
* images may need to be converted from their source format to the end format
* a file called image.entities is generated that provides two entities:
ℑ and &IMAGE;
ℑ is the file extension (png, ps, pdf)
* all generated images will be put in images/
HOW THE BUILD WORKS FOR EACH FORMAT
-----------------------------------
* HTML:
- xmlto html gstreamer-whatever.xml should produce the html docs.
- We do this in the html subdir of the doc builddir.
- images are copied to (builddir)/html/images
- PNGS should be set to all of the png's referenced for html, both
already there and auto-generated
* PS :
- images are converted to .ps files in EPS format. Generated images are
put in images/
- xmlto ps gstreamer-whatever.xml generates the ps file
* PDF :
There are two ways:
- ps2pdf is the easiest
- we specify ps, PS as the image type, but using xmlto the build will fail
because it uses ps2pdf internally and it fails to generate the images
By hand-generating .pdf images before xmlto we can make the build succeed.
(This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
doing the right thing)
xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
FAQ, so for now we use ps2pdf)
HOW THE BUILD SYSTEM IS SET UP
------------------------------
* make all should build html, ps, and pdf
* html is built in a subdir, with the png/ps images copied there
* ps and pdf are built in the current dir, in one file
GTK-DOC NOTES
=============
* files under CVS control:
- Makefile.am
- gstreamer-sections.txt, gstreamer.types.in, gstreamer-docs.sgml
- tmpl/
(FIXME: describe what each of these files do)
* what to do when adding a new piece of API:
- add both an entity and use the entity in gstreamer-docs.sgml
- add a new section to gstreamer-sections.txt
- add all documented symbols to gstreamer-sections.txt in the proper section
- signals: document them properly in tmpl/.sgml
* checklist:
- make sure -sections.txt has a <TITLE> set for each <FILE>
* what happens during a gtk-doc build ?
- headers are scanned based on $(MODULE).types
$(MODULE)-scan is created
gtkdoc-scan is called with a sourcedir and a module name,
where the module name is $(MODULE)
$(MODULE)-sections.txt is created if it doesn't exist yet (it should),
as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
and .args, .hierarchy and .signals files are created
gtkdoc-scan is called
(FIXME: why is there gstreamer.types.in and gst-plugins.types.in ?)
* Possible errors and how to fix them
- Warning: multiple "IDs" for constraint linkend: gst-tag-register.
- check if gst_tag_register is listed more than once in -sections.txt
WBSITE DOCUMENTATION
====================
Updating the online documentation is pretty simple.
Make sure that you
a) have a working freedesktop.org account
b) $HOME/.ssh/config set up so that it has the right User for the Host
(for example, I have:
Host freedesktop.org
User thomasvs
c) verify this works by doing ssh freedesktop.org and being logged in without
a password prompt
d) have verified your changes build documentation locally.
Then, after updating any of the docs, run "make upload" from that directory.
Or, run "make upload" from this (docs) directory.
RANDOM THINGS I'VE LEARNED
==========================
* for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
so the source xml could find the built entity file.
But xmlto --searchpath is (right now) for TeX input, not xml input.
xsltproc has a --path option (that xmlto doesn't use yet), but it
resolves single files to $(specified_path)/$(srcdir)/$(file)
For now, we need to hack around it by copying xml to the build dir.