A first attempt to document the playtree system

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@4861 b3059339-0415-0410-9bf9-f77b7e298cf2

1 files changed, 123 insertions, 0 deletions

diff --git a/DOCS/tech/playtree b/DOCS/tech/playtree
new file mode 100644
index 0000000000..ad0a683ae6
--- /dev/null
+++ b/DOCS/tech/playtree
@@ -0,0 +1,123 @@
+
+How work the playtree ? 
+
+Good question, I try to explain but note that it's the first doc
+I write :)
+
+First there is two things. The playtree itself and the iterator.
+The playtree represent the data and the iterator is used by
+mplayer to go from entry to entry.
+
+First the play_tree struct :
+
+
+struct play_tree {
+  play_tree_t* parent;
+  play_tree_t* child;
+  play_tree_t* next;
+  play_tree_t* prev;
+
+  play_tree_param_t* params;
+  int loop;
+  char** files;
+  int entry_type;
+};
+
+The play_tree_t* hold the links in the 4 directions, the params hold
+all parameters of this entry, loop is obvious (loop < 0 mean infint loop),
+files hold all the files of this entry and entry_type obviously tell the 
+type of this entry (Node, file, dvd, vcd ot tv).
+
+An entry can hold more than one file, why ?
+
+Because an entry can be a network stream and usally you have more than
+one server. But all send the same thing, so it's only on entry with sevral
+sources.
+
+Then how do I use this stuff ?
+
+First you create an entry using the play_tree_new func. This create the struct
+and fill it with defaults values.
+Then this can become a node or a leaf. It will become a node as soon as you link it
+to another one using either play_tree_set_child or play_tree_set_parent.
+Or it will become a leaf as soon as you use play_tree_add_file on it.
+If an entry contain at least one file it can't become an node (an assert will be
+raised) and if en entry has a child you can't add file to (here also an assert will
+be raised).
+Then to create a list of entry you should use play_tree_append_entry,
+play_tree_prepend_entry or play_tree_insert_entry.
+In all this function you can use any entry of the the list as first argument,
+no need that it's the first one. The same apply when you set the child of a node, 
+the child argument can be any entry in a list.
+To remove an entry from the tree use play_tree_remove. If the second arg (free_it)
+is true it will also free it, if the entry should be freed and the third
+arg is true it will also free the childs.
+
+When your tree is ready you can then use play_tree_cleanup to remove all unuseful
+entries.
+
+If you want to load a playlist you can use parse_playtree wich take a stream_t
+as argument or parse_playlist_file wich take a filename as argument.
+Both function will return NULL in case of failure or a new (cleaned) tree that
+you can add somewhere in your tree.
+
+How do I add DVD, VCD or TV entry to the tree ?
+
+You should use some virtual URL as filename like :
+     dvd://x where x is the title number.
+     vcd://x where x is the track number
+     tv://x where x is the channel
+
+
+My playtree is ready now, what with this play_tree_iter ?
+
+This is an iterator used to go trough the tree. It handle itself
+loop of list and setting mplayer config according to the params
+of each entry.
+It's created with play_tree_iter_new wich take as argument a play_tree_t
+and an m_config_t wich is then used to set/unset the params of each entry.
+After creation the iter point to nothing, you should init with a first step.
+To go to another entry in the list you should use play_tree_iter_step. The
+second argument is the direction of the step : positive value go frontward,
+negative go backward and 0 don't move. The third tell if must care of
+node or not. If it's true, the iterator will stop on nodes, otherwise it go
+to the next valid entry.
+This function return different values :
+PLAY_TREE_ITER_ERROR  : obvious
+PLAY_TREE_ITER_ENTRY : we are now on an entry
+PLAY_TREE_ITER_NODE  : we are now on a node
+PLAY_TREE_ITER_END : we are now at end
+(( Note : I must add a PLAY_TREE_ITER_BEGINING for the begining. Don't know
+what it will return in a such case.  PLAY_TREE_ITER_ERROR ? ))
+
+There is also play_tree_iter_up_step wich can be used to break a loop or skip
+the current list. The argument are the same than play_tree_iter_step. The
+difference is that it go back to parent of the current list, and then step according
+to the arguments.
+
+Then when your iter returned PLAY_TREE_ITER_ENTRY you can use
+play_tree_iter_get_file to get the file. If you call it more than one time
+it will return the next file for this entry or loop trough the list if no more
+file are avaible. You can now how many files are avaible using iter->num_files
+and wich one it returned using iter->file.
+In case the entry is a DVD, VCD or TV channel the returned string is not a filename
+but "DVD title x", "VCD track x" or "TV channel x".
+To distinc those case from a normal file you can check iter->tree->entry_type.
+It will contain one of PLAY_TREE_ENTRY_DVD, PLAY_TREE_ENTRY_VCD, 
+PLAY_TREE_ENTRY_TV or PLAY_TREE_ENTRY_FILE.
+
+If you need to make some check with the iter, such as will next entry be valid, etc
+You must create a clone with play_tree_iter_new_copy. This iter will not affect
+the config, so you can do all you want with it.
+
+Then when you have finish with the iter free it with play_tree_iter_free.
+
+
+Ok, that's all for now. To have some exemples look into mplayer.c ;)
+First just after config parsing, the iterator is created there. Also
+after stream opening, in case the stream is a playlist it replace the
+entry wich contained the playlist by the result of the parsing.
+In the event handeling it check if a step can be done, etc. And finnaly
+at the end it go the next entry.
+
+Suggestion, flames, etc about this doc must go to albeu@free.fr