2001-01-20 20:08:59 +00:00
|
|
|
Documentation conventions
|
|
|
|
|
=========================
|
|
|
|
|
|
|
|
|
|
Due to the potential for exponential growth, several abbreviating conventions will be used throughout this
|
|
|
|
|
documentation. These conventions have grown primarily from extremely in-depth discussions of the architecure in IRC.
|
|
|
|
|
This has verified the safety of these conventions, if used properly. There are no known namespace conflicts as long as
|
|
|
|
|
context is rigorously observed.
|
|
|
|
|
|
|
|
|
|
Object classes
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
Since everything starts with Gst, we will generally refer to objects by the shorter name, i.e. Element or Pad. These
|
|
|
|
|
names will always have their first letter capitalized.
|
|
|
|
|
|
|
|
|
|
Function names
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
Within the context of a given object, functions defined in that object's header and/or source file will have their
|
2004-12-13 19:23:04 +00:00
|
|
|
object-specific prefix stripped. For instance, gst_element_add_pad() would be referred to as simply _add_pad(). Note
|
2001-01-20 20:08:59 +00:00
|
|
|
that the trailing parentheses should always be present, but sometimes may not be. A prefixing underscore (_) will
|
|
|
|
|
always tell you it's a function, however, regardless of the presence or absence of the trailing parentheses.
|
|
|
|
|
|
|
|
|
|
#defines and enums
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
Values and macros defined as enums and preprocessor macros will be referred to in all capitals, as per their
|
|
|
|
|
definition. This includes object flags and element states, as well as general enums. Examples are the states NULL,
|
2004-12-09 17:25:00 +00:00
|
|
|
READY, PLAYING, and PAUSED; the element flags LOCKED_STATE , and state return values SUCCESS, FAILURE, and
|
2001-01-20 20:08:59 +00:00
|
|
|
ASYNC. Where there is a prefix, as in the element flags, this is usually dropped, and implied. Not however that
|
|
|
|
|
element flags should be cross-checked with the header, as there are currently two conventions in use: with and without
|
|
|
|
|
_FLAGS_ in the middle.
|
2004-12-09 17:25:00 +00:00
|
|
|
|
|
|
|
|
FIXME: check flags for consistency.
|
More MT fixes, added design document describing refcounting policies used in GStreamer and locking involved.
Original commit message from CVS:
* docs/design/part-MT-refcounting.txt:
* docs/design/part-conventions.txt:
* gst/gstbin.c: (gst_bin_set_index), (gst_bin_set_clock),
(gst_bin_add_func), (gst_bin_remove_func),
(gst_bin_iterate_elements), (gst_bin_change_state),
(gst_bin_dispose), (gst_bin_get_by_name_recurse_up):
* gst/gstcaps.c:
* gst/gstelement.c: (gst_element_add_pad),
(gst_element_remove_pad), (pad_compare_name),
(gst_element_get_static_pad), (gst_element_get_request_pad),
(gst_element_get_pad), (gst_element_iterate_pads),
(gst_element_class_get_pad_template_list),
(gst_element_class_get_pad_template), (gst_element_get_random_pad),
(gst_element_get_event_masks), (gst_element_send_event),
(gst_element_seek), (gst_element_get_query_types),
(gst_element_query), (gst_element_get_formats),
(gst_element_convert), (gst_element_post_message),
(gst_element_set_locked_state), (gst_element_get_state),
(gst_element_set_state), (gst_element_pads_activate),
(gst_element_dispose), (gst_element_set_manager_func),
(gst_element_get_manager):
* gst/gstelement.h:
* gst/gstiterator.c: (gst_iterator_new), (gst_list_iterator_next),
(gst_list_iterator_resync), (gst_list_iterator_free),
(gst_iterator_new_list):
* gst/gstiterator.h:
* gst/gstmessage.c: (_gst_message_copy):
* gst/gstobject.c: (gst_object_class_init), (gst_object_init),
(gst_object_ref), (gst_object_unref), (gst_object_sink),
(gst_object_replace), (gst_object_dispose),
(gst_object_dispatch_properties_changed), (gst_object_set_name),
(gst_object_set_parent), (gst_object_get_parent),
(gst_object_unparent), (gst_object_check_uniqueness),
(gst_object_get_path_string):
* gst/gstobject.h:
* gst/gstpad.c: (gst_pad_dispose), (gst_pad_set_active),
(gst_pad_is_active), (gst_pad_set_blocked_async),
(gst_pad_is_blocked), (gst_pad_unlink), (gst_pad_is_linked),
(gst_pad_link_prepare_filtered), (gst_pad_link_filtered),
(gst_pad_get_real_parent), (gst_pad_relink_filtered),
(gst_pad_get_peer), (gst_pad_realize), (gst_pad_get_allowed_caps),
(gst_pad_alloc_buffer), (gst_pad_push), (gst_pad_pull),
(gst_pad_pull_range), (gst_pad_push_event):
* gst/gstpad.h:
* gst/gstpipeline.c: (gst_pipeline_init), (gst_pipeline_dispose),
(is_eos), (pipeline_bus_handler):
* gst/gstutils.c: (gst_element_get_compatible_pad_filtered),
(gst_element_link_pads_filtered), (gst_element_unlink):
* gst/parse/grammar.y:
* tools/gst-compprep.c: (main):
* tools/gst-inspect.c: (print_pad_info):
* tools/gst-launch.c: (main):
* tools/gst-xmlinspect.c: (print_element_info):
More MT fixes, added design document describing refcounting
policies used in GStreamer and locking involved.
Fixed unsafe ghostpad dereffing.
Removed old unsafe methods.
2004-12-13 11:33:55 +00:00
|
|
|
|
|
|
|
|
Drawing conventions
|
|
|
|
|
===================
|
|
|
|
|
|
|
|
|
|
When drawing pictures the folowing conventions apply:
|
|
|
|
|
|
|
|
|
|
objects
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
Objects are drawn with a box like
|
|
|
|
|
+------+
|
|
|
|
|
| |
|
|
|
|
|
+------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
pointers
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
a pointer to an object.
|
|
|
|
|
+-----+
|
|
|
|
|
*--->| |
|
|
|
|
|
+-----+
|
|
|
|
|
|
|
|
|
|
an invalid pointer, this is a pointer that should not be used.
|
|
|
|
|
|
|
|
|
|
*-//->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
elements
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
+----------+
|
|
|
|
|
| name |
|
|
|
|
|
sink src
|
|
|
|
|
+----------+
|
|
|
|
|
|
|
|
|
|
pad links
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
-----+ +---
|
|
|
|
|
| |
|
|
|
|
|
src--sink
|
|
|
|
|
-----+ +---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
