From f64f33876c955e4c81df417692175f194439a81b Mon Sep 17 00:00:00 2001 From: albeu Date: Mon, 25 Feb 2002 13:59:39 +0000 Subject: A first attempt to document the playtree system git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@4861 b3059339-0415-0410-9bf9-f77b7e298cf2 --- DOCS/tech/playtree | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 DOCS/tech/playtree (limited to 'DOCS/tech') 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 -- cgit v1.2.3