remove completely outdated random docs

Original commit message from CVS: remove completely outdated random docs
2024-11-30 05:31:15 +00:00 · 2005-11-17 11:25:34 +00:00 · 2005-11-17 11:25:34 +00:00 · 5a303611c2
commit 5a303611c2
parent 3278ca54a7
15 changed files with 0 additions and 636 deletions
--- a/docs/random/NOTES-0.1.1
+++ b/docs/random/NOTES-0.1.1
@ -1,36 +0,0 @@
 compile fixes:
  - BSD compatibility fixes (MAP_ANON)
  - libxml compile problems fix
  - compile fixes for non x86 architectures 
    (mpg123, mpeg_play, getbits, videoscale, ac3dec)
  - mpeg2enc asm comment fixes
 bug fixes:
  - videoscaler/colorconversion fixes
  - OSS audiosink bug fix
  - reworked the queue threading code
  - fixed the /etc/gstreamer permissions problem
  - various minor bug fixes
 changes:
  - state change modifications
  - _request pad implemented for muxer/mixer/aggregator
    elements. also _request_compatible additions.
  - massive ghostpad changes
  - EOS handling (not for gstmediaplay)
  - icecast send plugin using libshout
  - lots of GstObject changes (XML save, name, parent
    properties fixes)
  - preliminary XML namespaces.
  - added support for custom app tags in the XML save/load
    routines (preliminary support)
  - cothreads updates for ALPHA/ARM
  - asyncdisksrc is gone in favor of a better disksrc
  - getregion rework
  - videoscaler/colorconversion updates
  - manual/docs updates
--- a/docs/random/NOTES-0.2.0
+++ b/docs/random/NOTES-0.2.0
@ -1,78 +0,0 @@
 Version 0.2.0
 -------------
 compile fixes:
  - added a gstreamer.m4 script.
  - more compatibility fixes for various xml libs.
  - more BSD patches.
  - gstversion.h added.
  - numerous configure changes
  - compatibility with autoconf 2.50
 bug fixes:
  - allow quoted and escaped args in gstparse.c
  - preliminary work on proper refcounting
  - numerous bugfixes in the plugins.
 changes:
  - better CPU detection 
  - dynamic autopluggers with a new more powerful API.
  - sparc cothreads.
  - reworked arg setting (gstparse.c and gstelement.c xml handling)
  - testsuite directory added
  - incremental scheduling is now implemented.
      - dynamic adding and removing of elements in a runnning 
        pipeline.
      - proper synchronisation and thread interlock.
  - caps negotiation
     - allow elements to exchange and agree on a media type.
     - get rid of the metadata.
  - man pages added for command line utils.
  - more documentation updates
  - colourful debug system
  - new plugin initialisation mechanism so that the core can refuse
    to load plugins build with an incompatible version number.
  - added bash comand line completion for gstreamer-launch
  - pipefilter is now decoupled as it should be
  - added gnomevfssrc as the prefered element in gstplay
  - PAUSED and PLAYING state are now swapped.
  - elements cannot have identical names when added to a bin.
  - lots of plugin updates.
  - reworked AVI decoder.
 plugins:
  - xmms input, effect
  - mpeg2dec based on libmpeg2
  - alsa sink and src.
  - rtp sink
  - FLX decoder
  - multidisksrc
  - a new X-only videosink
  - stero2mono and mono2stereo
  - mulaw encoder/decoder
  - colorspace converter
  - artsdsink
  - alaw encoder/decoder
  - mad mp3 decoder
  - passthrough and script to create a plugin boilerplate
  - volenv (a volume envelope filter)
  - adder (an audio mixer)
  - arts plugin
  - 1394src (a firewire source)
  - DV decoder.
  - aasink
  - intfloat and floatint converter
  - autoplugcache
  - gstoss to import audio from legacy apps by hijacking /dev/dsp
  - lav encoder (for interoperability with mjpegtools)
  - gnomevfssrc (read data from gnomevfs) and gnomevfssink
  - sdlvideosink (display video using SDL)
  - quicktime decoder based on openquicktime.
  - audiofile src and sink.
  - level (level detection plugin)
  - gsm decoder/encoder (based on libgsm)
--- a/docs/random/TODO-post-0.1.0
+++ b/docs/random/TODO-post-0.1.0
@ -1,57 +0,0 @@
 - Restructure CVS
  - Move gstreamer/ to gstreamer-0.1.0/
  - Re-import entire project into gstreamer/
 - Convert to GObject
 - Get editor working better
  - object hierarchy rewrite?
 - make autoplugging algorithms pluggable
  - create a dynamic autoplugger
 - make scheduling algorithms pluggable
  - try some really hard cases
 - add help functions to traverse the hierarchy
  - gst_bin_traverse_with_func(GstBin *bin, funcptr)
 - bufferpool passing
 - general
  - thread-safety
 - EOS handling
 - QoS handling
 - clock sync
 - test suite
  - test cases
  - regression tests
 - XML stuff
  - save signals
  - xml namespaces
 - caps/props
  - APIs
  - caps negociation
  - props weighting
  - metadata
 - docs
  - manuals
  - plugin-writers-guide
  - design guide
  - performance guide
 - bindings
  - perl
  - guile
  - BONOBO
  - corba
  - ...
 - after that we'll do more plugins :-)
--- a/docs/random/arch
+++ b/docs/random/arch
@ -1,81 +0,0 @@
 OUTDATED
 --------
 GstElementFactory:
 Base class for all elementfactories.  Is a single-instance (per program)
 object that creates objects of the associated GstElement derivative.
 GstPlugin:
 Defines a given plugin.  Records plugin name, function pointers, details,
 etc.  Includes a list of GstElementFactories that are associated with
 this plugin.
 GstBuffer
 GstPad
 GstObject
 	GstSrc
 		GstDiskSrc
 		GstHTTPSrc
 		*
 	GstAsyncSrc
 		GstAsyncDiskSrc
 		*
 	GstFilter
 		GstVideoFilter
 			GstVideoMPEG
 			*
 		GstAudioFilter
 			GstAudioMPEG
 			*
 		*
 	GstSink
 		GstAudioSink
 			GstAudioOSSSink
 			GstAudioALSASink
 			GstAudioESDSink
 			*
 		GstVideoSink
 			GstVideoGDKRGBSink
 			GstVideoXvSink
 			*
 		*
 	*
 	GstBin
 		GstPipeline
 		GstThread
 GstConnection
 	GstQueue
 	GstNetwork
 	GstSHM
 GstObject:
 Base class for all streamer objects (duh), defines some basic stuff like a
 pointer to the master pipeline for the object.
 GstBin:
 Contains a bunch of GstObjects.
 GstPipeline:
 A bin that can be used raw in an application.  The object that gets
 embedded into applications.  Can contain any set of GstObjects.  Nothing
 but a convenience object for the moment, will eventually be *the* object
 dealt with externally.
 GstThread:
 A bin that will become a thread if possible when the pipeline is started
 up.  Can contain any set of GstObjects except another GstThread.  All
 starting points and/or clocked events must be registered with this object,
 to be dealt with in the separate thread.
--- a/docs/random/coroutines
+++ b/docs/random/coroutines
@ -1,5 +0,0 @@
 In a cothread-based container, all elements are run as cothreads.
 Chain-function based elements are wrapped by a generic element-class
 function that just calls the chain function repeatedly after pulling a
 buffer for it.  (in reality, chain functions are only usable in the
 single-input case)
--- a/docs/random/design
+++ b/docs/random/design
@ -1,12 +0,0 @@
 The fundamental component of GStreamer is the "element", an object that
 sources and/or sinks data.  Elements are connected to each other via
 "pads", which are extremely light-weight generic connections.  Elements
 can be contained inside "bins", which themselves are elements.
 A pipeline consists of any number of elements, connected to each other one
 after another.  A source would connect to one end of a decoder, which in
 turn would be connected (on the other end) to a sink, such as a sound
 card.  Other elements can be located anywhere in the pipeline, including
 tees and transcoders.
--- a/docs/random/factoryinfo
+++ b/docs/random/factoryinfo
@ -1,7 +0,0 @@
 short name
 class
 long name
 descripion
 author
 version
 copyright
--- a/docs/random/gboolean
+++ b/docs/random/gboolean
@ -1,4 +0,0 @@
 NOTE TO SELF:
 there are a lot of routines here that should be returning gboolean's for
 status, rather than just plain failing.
--- a/docs/random/padarch
+++ b/docs/random/padarch
@ -1,14 +0,0 @@
 --src----------------------------	--sink----------------------------
 				|	|
 		--srcpad--------|	|--sinkpad-------
 		| pad_push()	.	.		|
 push()		|  ->chain	.	.  ->chain	| ->	chain()
 		|		.	.		|
 		----------------|	|----------------
 				|	|
 chain() is the function provided by sink element
 sinkpad->chain is a pointer to that function
 srcpad->chain should be a copy of that pointer
 pad_push() calls the function pointer srcpad->chain
 push() is the function provided by the src element
--- a/docs/random/sequence
+++ b/docs/random/sequence
@ -1,15 +0,0 @@
 Here's a possible (huge, large, complete?) sequence of execution for an
 invocation of [GIST] playing a media stream.  I'll start with a mp3 audio
 stream, but eventually this should be a mpeg a/v stream off the net with
 rolling capture (think ReplayTV/Tivo), pausing, rewinding, etc.  This
 could easily be hundreds of lines by the time I'm done...
 This may look a lot like C in places, simply because that's the most
 efficient way of representing a given action.
 gst_init();
 pipeline = gst_pipeline_new();
 	state = 
 src = gst_disksrc_new("src","song.mp3");
--- a/docs/random/state-transitions
+++ b/docs/random/state-transitions
@ -1,45 +0,0 @@
 So, the method of having a _start() and _stop() function for each element
 just doesn't scale.  In the case of pipeline/thread model with a PLAYING
 state bit, I have no way of passing a state change all the way down the
 graph, i.e. a thread sitting inside a supplied bin.
 Proposal is to have a single state-change class function, which gets
 passed a single argument (no more 'state' going along with RUNNING).  This
 function can be overridden by each element as necessary, but must chain to
 the parent_class version of it.  It does its work, just like [st]et_arg,
 in a case.  It checks for STATE and ~STATE, and does the appropriate
 steps. All the _start() and _stop() functions get moved into this one, in
 the GST_STATE_RUNNING and ~GST_STATE_RUNNING cases.
 This allows bins to and derivations thereof to simply pass through any
 state they don't understand.  Meta-elements will also pass through.
 There may need to be some mechanism that provides for setting state on
 only a certain type.  This can be provided as an alternate path supplied
 by bins.  The bin is the one that would do the work in any case.  Simply
 provide class function for bins that does the selective stuff, and a main
 _bin_ function that calls this class function.  The supplied class
 function for each bin would simply check against the given GtkType before
 setting its state.  Derivations of GstBin would always get it.
 Success chaining (gbooleans) starts to get a little hairier...
 Functions:
 gst_element_set_state(element,state) is called by the application to set
 the state for an element (or bin).
 elementclass->change_state() is the class function that actually does the
 setting of the state for this element.  Any subclass implementation will
 chain to the parent_class's version.
 gst_element_change_state(element,state) is the Element class's
 implementation of the change_state() function.  It simply sets the state.
 gst_bin_set_state_type(element,state,type) is a specialized function for
 bins only that sets the type only on elements of that type.
 binclass->change_state_type() is the class function that does the
 selective 
--- a/docs/random/states
+++ b/docs/random/states
@ -1,75 +0,0 @@
 OUTDATED
 --------
 GST State Bits and Transition Rules (graph to follow)
 -----------------------------------
 These are the 'new' state bits and what they mean.
 What the state bits are:
 GST_STATE_COMPLETE: if the element has enough data, but is not in any kind
 	of running or explicitely stopped state.  ready to be used.
 GST_STATE_RUNNING: this is the normal state of the pipeline, where data
 	goes all the way through the pipeline normally.
 GST_STATE_DISCOVERY: anything the element does in this state must be reset
 	after discovery.  any data read from sync source must be cached.
 GST_STATE_PREROLL: not a lot different from PLAYING, except sinks don't
 	render what they're getting.  useful for elements that require
 	data to get in sync, such as an MPEG video decoder that needs
 	IBBPBB before starting at the next P.
 Basic transition rules:
 Completeness is based on the element having enough information to actually
 do something.  GST_STATE_COMPLETE is required for any other state to be
 valid, though the only invariant is that you can't be RUNNING unless
 you're COMPLETE.  In fact, AFAICT, that's the *only* invariant.
 The element is entirely in control of this bit at all times.  There is no
 way to externally change this bit except by changing the state of the
 element in such a way as to effect a change.
 |= GST_STATE_COMPLETE
 	setting whatever the last bit of info the element was looking for
 	(gst_object_set)
 &= ~GST_STATE_COMPLETE
 	changing anything that invalidates the complete state of the element
 Whether the element is running or not, on the other hand, is almost
 entirely out of the hands of the individual element.  This is generally
 turned on by way of gst_element_run() as called by the parent (ultimately
 by the Pipeline), which happens to optionally call a function private to
 the element to prepare it.  As per docs/random/gboolean, very likely this
 function should return a TRUE/FALSE.
 Generally, I think if there is no such function, the generic element code
 should go ahead and set the state, and trigger the state_changed signal,
 returning TRUE.  If there is a function, call it.  If it returns TRUE,
 fire off the signal (since the signal is actually an Element signal
 anyway, why eat another function call?).  Return the result regardless.
 |= GST_STATE_RUNNING
 	starting up the pipeline with gst_pipeline_start
 ~= ~GST_STATE_RUNNING
 	stopping the pipeline with gst_pipeline_stop, or some error state
 gst_pipeline_start() simply calls the gst_element_start() function on each
 of the elements in it.  This sets the RUNNING bit of each element, and for
 GstBin's it loops through that list.  gst_pipeline_start() is just a
 special case version of gst_bin_start().  All start() functions are
 GstElementClass functions, meaning you can start any element the same way.
 The pipeline can be stopped the same way, but more likely the pipeline
 will be stopped due to some stoppage condition, such as EOF on the source
 file, or the parser being told to stop the stream.  In the EOF case, it
 would turn its RUNNING bit off, then call the stop() class function on its
 parent.  This would trigger an up-hill, breath-first traversal of the
 whole graph.  Alternately, if each element lists its uber-parent (the
 Pipeline) it can simply inform the pipeline directly, causing a
 depth-first traversal just like the start() case.
--- a/docs/random/states.new
+++ b/docs/random/states.new
@ -1,82 +0,0 @@
 OUTDATED
 --------
 Since the plan generation only happens as a result of the state mechanism,
 I'll describe that first.
 It's supposed to be recursive, such that setting the state on a Bin
 recursively sets all the children.  However, this needs to be rethought
 somewhat, in light of some recent ideas on the actual definition of some
 of the states.
 The mechanism is thus: When you call gst_element_set_state(element,state),
 it calls the change_state() class method.  The basic Element-provided
 version just sets or unsets the state.  A more complex element like the
 audiosink will switch on the state and do certain things like open or
 close the sound card on transition to/from various states.  The success or
 failure of these actions can determine whether or not the state gets
 [un]set as requested.
 GtkObject signals enter in here, as whenever a state is successfully
 changed, the STATE_CHANGE signal is fired, which gives higher-level code
 the ability to do something based on the change.
 The Bin's change_state function walks through all its children and sets
 their state.  This is where things get interesting, and where things are
 going to need to be changed.
 The issue is what the states are and mean.  Currently the states are as
 follows (from gstelement.h):
 typedef enum {
  GST_STATE_COMPLETE    = (1 << 0), 
  GST_STATE_RUNNING     = (1 << 1),
  GST_STATE_DISCOVERY   = (1 << 2),
  GST_STATE_PREROLL     = (1 << 3),
  GST_STATE_PLAYING     = (1 << 4),
  GST_STATE_PAUSED      = (1 << 5),
  GST_STATE_MAX         = (1 << 15),
 } GstElementState;
 COMPLETE means all the necesary information is available to run, i.e. the
 filename for the disksrc, etc.  RUNNING means that it's actually doing
 something, but that's fuzzy.  PLAYING means there really is data flowing
 through the graph, where PAUSED temporary stops the flow.  PLAYING &&
 PAUSED is the same idea as !PLAYING, but there are probably going to be
 many cases where there really is a distinction.
 DISCOVERY is intended for the autoconnect case, in those instances where
 the only way to determine the input or output type of some pad is for an
 element to actually process some data.  The idea in that case is that the
 source element would be responsible for sending the data non-destructively
 (in the case of a network client, it would have to save it all up, unless
 it has seek capabilities over the network), and all downstream elements
 process it in such a way as to not hose their own state.  Or rather, when
 they cease to do discovery, they completely wipe their state as if nothing
 ever happened.
 PREROLL is a local state, used for things like sending the first half of
 an MPEG GOP through the decoder in order to start playback at a frame
 somewhere in the middle of said GOP.  Not sure how that will work, 
 exactly.
 The issue is that these states aren't layered, and it most certainly isn't
 the case that a container isn't able to be of a certain state unless all
 of its children are.  I guess I should explain the idea of reconfigurable
 pipelines:
 Build an MP3 player, give it the ability to use audio effects plugins.
 Since you don't want to have to start the stream over again (especially if
 it's a network stream) every time you change the effect.  This means you
 need to be able to freeze the pipeline in place to change it, without
 taking too much time.
 This matters when you consider that certain state changes should render
 various state bits invalid.  In the FROZEN state these won't happen,
 because the assumption is that they're temporary.
 If you haven't noticed by now, the state system isn't entirely
 self-consistent yet.  It needs work, and it needs discussion.
--- a/docs/random/states.old
+++ b/docs/random/states.old
@ -1,83 +0,0 @@
 OUTDATED
 --------
 GST States and Transition Rules (graph to follow)
 -------------------------------
 This should be a map of possible state transitions and what triggers them.
 What the states are:
 GST_STATE_NEW: a new element has this, if it has nothing set except name.
 GST_STATE_INCOMPLETE: any element that has some, but not enough
 	information to function is in this state.
 GST_STATE_COMPLETE: if the element has enough data, but is not in any kind
 	of running or explicitely stopped state.  ready to be used.
 GST_STATE_DISCOVERY: anything the element does in this state must be reset
 	after discovery.  any data read from sync source must be cached.
 GST_STATE_PREROLL: not a lot different from PLAYING, except sinks don't
 	render what they're getting.  useful for elements that require
 	data to get in sync, such as an MPEG video decoder that needs
 	IBBPBB before starting at the next P.
 GST_STATE_RUNNING: this is the normal state of the pipeline, where data
 	goes all the way through the pipeline normally.
 GST_STATE_STOPPED: an explicit stop state, different from COMPLETE in that
 	the state doesn't get reset.
 NULL -> GST_STATE_NEW
 	creating an element (gst_*_new*)
 GST_STATE_NEW -> GST_STATE_INCOMPLETE
 	setting anything in the element that isn't sufficient to bring it
 	to a useful state (gst_object_set)
 GST_STATE_INCOMPLETE -> GST_STATE_COMPLETE
 	setting whatever the last bit of info the element was looking for
 	(gst_object_set)
 GST_STATE_COMPLETE -> GST_STATE_INCOMPLETE
 	changing anything that invalidates the complete state of the element
 GST_STATE_COMPLETE -> GST_STATE_DISCOVERY
 	setting the state to DISCOVERY
 	[ used for autoplug ]
 GST_STATE_DISCOVERY -> GST_STATE_COMPLETE
 	setting the state !DISCOVERY
 	[ used when autoplug is over ]
 GST_STATE_DISCOVERY -> GST_STATE_PREROLL
 	setting the state to PREROLL
 	[ you can go straight to preroll from discovery if you want ]
 GST_STATE_DISCOVERY -> GST_STATE_RUNNING
 	setting the state to RUNNING
 	[ you can even go straight to running from preroll ]
 GST_STATE_DISCOVERY -> GST_STATE_STOPPED
 	setting the state to STOPPED
 	[ normally you'd go from discovery to stopped when you load a src ]
 GST_STATE_PREROLL -> GST_STATE_RUNNING
 	setting the state to RUNNING
 	[ preroll generally leads straight to running, as in above ]
 GST_STATE_PREROLL -> GST_STATE_STOPPED
 	setting the state to STOPPED
 	[ it is possible to go to stopped, i.e load file@time ]
 GST_STATE_RUNNING -> GST_STATE_PREROLL
 	setting the state to PREROLL
 	[ unsure if you'd need this state, you'd go to stopped first ]
 GST_STATE_RUNNING -> GST_STATE_STOPPED
 	setting the state to STOPPED
 	[ pause. ]
 GST_STATE_STOPPED -> GST_STATE_PREROLL
 	setting the state to PREROLL
 	[ if you seek to intermediate time while stopped, you'd preroll to
 	  prepare to start running again immediately ]
 GST_STATE_STOPPED -> GST_STATE_RUNNING
 	setting the state to RUNNING
--- a/docs/random/walkthrough
+++ b/docs/random/walkthrough
@ -1,42 +0,0 @@
 OUTDATED
 --------
 You might start by creating a source element and put it into a pipeline.
 At this point both element's state would be GST_STATE_NEW, since they
 don't have enough state to actually run yet.  At this point you can set
 the filename of the source, and possibly bytesperread and other things.
 Then you'd want to discover the data type of the file you're sourcing.
 This will typically be handled by the pipeline itself by calling
 gst_pipeline_autoplug(), or gst_pipeline_find_pad_type(), or somesuch. The
 pipeline would first set its state to GST_STATE_DISCOVERY.  A gstfindtype
 sink would be added to the pipeline and connected to the source.  Its
 HAVE_TYPE signal would be connected to a private pipeline function.
 The pipeline would then set the the src state to GST_STATE_DISCOVERY, and
 call the src's push() function until a the type is set by the function
 connected to the gstfindtype element's signal.  At this point the pipeline
 would disconnect the gstfindtype element from the src, set the type of the
 pad to the type returned by the gstfindtype element.  At disconnection of
 the find element, the src's state automatically reverts to NEW.
 (The trick with the sources when they do DISCOVERY is that synchronous
 sources can't go back and read data again.  So perhaps I should set up a
 wrapper function for the push() function that uses either a sync or
 async function as provided by the src instance to provide DISCOVERY and
 normal operations.  It would use a [GstBufferCache] to read ahead into
 memory if necessary, creating baby buffers as necessary to answer the
 needs of each DISCOVERY sequence.)
 If you called find_pad_type(), it would return right about now, with the
 ID of the type it found.  At the same time, if you have connected a signal
 to the pad's SET_TYPE signal, it would fire right as the type is set by
 the find_pad_type() function.  This would allow your application to do its
 own selection of filters to connect to the pad.
 If you called autoplug(), the pipeline would make a selection of element
 to connect.  The element would be created (state=NEW), added to the
 pipeline, and the appropriate sink pad connected to the src in question.
 (Note that multi-sink elements won't be supported unless there's a really
 good and obvious way to do so)  The whole process would repeat until the
 recently added element no longer has a src pad.