mirror of
https://github.com/mpv-player/mpv
synced 2024-12-24 15:52:25 +00:00
A first attempt to document the playtree system
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@4861 b3059339-0415-0410-9bf9-f77b7e298cf2
This commit is contained in:
parent
330d33256f
commit
f64f33876c
123
DOCS/tech/playtree
Normal file
123
DOCS/tech/playtree
Normal file
@ -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
|
Loading…
Reference in New Issue
Block a user