annotate DOCS/tech/playtree @ 23736:b807809ef9f8

Remove unnecessary #ifdef around the whole file.
author diego
date Mon, 09 Jul 2007 20:40:47 +0000
parents f3d7a1b58a82
children 49a433e2e78f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
1
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
2 How work the playtree ?
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
3
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
4 Good question, I try to explain but note that it's the first doc
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
5 I write :)
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
6
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
7 First there is two things. The playtree itself and the iterator.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
8 The playtree represent the data and the iterator is used by
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
9 mplayer to go from entry to entry.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
10
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
11 First the play_tree struct :
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
12
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
13
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
14 struct play_tree {
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
15 play_tree_t* parent;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
16 play_tree_t* child;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
17 play_tree_t* next;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
18 play_tree_t* prev;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
19
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
20 play_tree_param_t* params;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
21 int loop;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
22 char** files;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
23 int entry_type;
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
24 };
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
25
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
26 The play_tree_t* hold the links in the 4 directions, the params hold
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
27 all parameters of this entry, loop is obvious (loop < 0 mean infint loop),
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
28 files hold all the files of this entry and entry_type obviously tell the
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
29 type of this entry (Node, file, dvd, vcd ot tv).
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
30
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
31 An entry can hold more than one file, why ?
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
32
11047
f160b005e251 spelling fixes
diego
parents: 4860
diff changeset
33 Because an entry can be a network stream and usually you have more than
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
34 one server. But all send the same thing, so it's only on entry with sevral
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
35 sources.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
36
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
37 Then how do I use this stuff ?
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
38
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
39 First you create an entry using the play_tree_new func. This create the struct
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
40 and fill it with defaults values.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
41 Then this can become a node or a leaf. It will become a node as soon as you link it
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
42 to another one using either play_tree_set_child or play_tree_set_parent.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
43 Or it will become a leaf as soon as you use play_tree_add_file on it.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
44 If an entry contain at least one file it can't become an node (an assert will be
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
45 raised) and if en entry has a child you can't add file to (here also an assert will
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
46 be raised).
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
47 Then to create a list of entry you should use play_tree_append_entry,
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
48 play_tree_prepend_entry or play_tree_insert_entry.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
49 In all this function you can use any entry of the the list as first argument,
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
50 no need that it's the first one. The same apply when you set the child of a node,
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
51 the child argument can be any entry in a list.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
52 To remove an entry from the tree use play_tree_remove. If the second arg (free_it)
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
53 is true it will also free it, if the entry should be freed and the third
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
54 arg is true it will also free the childs.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
55
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
56 When your tree is ready you can then use play_tree_cleanup to remove all unuseful
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
57 entries.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
58
11271
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
59 If you want to load a playlist you can use parse_playtree which take a stream_t
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
60 as argument or parse_playlist_file which take a filename as argument.
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
61 Both function will return NULL in case of failure or a new (cleaned) tree that
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
62 you can add somewhere in your tree.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
63
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
64 How do I add DVD, VCD or TV entry to the tree ?
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
65
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
66 You should use some virtual URL as filename like :
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
67 dvd://x where x is the title number.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
68 vcd://x where x is the track number
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
69 tv://x where x is the channel
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
70
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
71
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
72 My playtree is ready now, what with this play_tree_iter ?
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
73
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
74 This is an iterator used to go trough the tree. It handle itself
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
75 loop of list and setting mplayer config according to the params
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
76 of each entry.
11271
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
77 It's created with play_tree_iter_new which take as argument a play_tree_t
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
78 and an m_config_t which is then used to set/unset the params of each entry.
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
79 After creation the iter point to nothing, you should init with a first step.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
80 To go to another entry in the list you should use play_tree_iter_step. The
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
81 second argument is the direction of the step : positive value go frontward,
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
82 negative go backward and 0 don't move. The third tell if must care of
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
83 node or not. If it's true, the iterator will stop on nodes, otherwise it go
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
84 to the next valid entry.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
85 This function return different values :
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
86 PLAY_TREE_ITER_ERROR : obvious
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
87 PLAY_TREE_ITER_ENTRY : we are now on an entry
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
88 PLAY_TREE_ITER_NODE : we are now on a node
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
89 PLAY_TREE_ITER_END : we are now at end
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
90 (( Note : I must add a PLAY_TREE_ITER_BEGINING for the begining. Don't know
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
91 what it will return in a such case. PLAY_TREE_ITER_ERROR ? ))
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
92
11271
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
93 There is also play_tree_iter_up_step which can be used to break a loop or skip
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
94 the current list. The argument are the same than play_tree_iter_step. The
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
95 difference is that it go back to parent of the current list, and then step according
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
96 to the arguments.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
97
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
98 Then when your iter returned PLAY_TREE_ITER_ENTRY you can use
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
99 play_tree_iter_get_file to get the file. If you call it more than one time
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
100 it will return the next file for this entry or loop trough the list if no more
11047
f160b005e251 spelling fixes
diego
parents: 4860
diff changeset
101 file are available. You can now how many files are available using
11271
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
102 iter->num_files and which one it returned using iter->file.
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
103 In case the entry is a DVD, VCD or TV channel the returned string is not a filename
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
104 but "DVD title x", "VCD track x" or "TV channel x".
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
105 To distinc those case from a normal file you can check iter->tree->entry_type.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
106 It will contain one of PLAY_TREE_ENTRY_DVD, PLAY_TREE_ENTRY_VCD,
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
107 PLAY_TREE_ENTRY_TV or PLAY_TREE_ENTRY_FILE.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
108
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
109 If you need to make some check with the iter, such as will next entry be valid, etc
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
110 You must create a clone with play_tree_iter_new_copy. This iter will not affect
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
111 the config, so you can do all you want with it.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
112
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
113 Then when you have finish with the iter free it with play_tree_iter_free.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
114
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
115
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
116 Ok, that's all for now. To have some exemples look into mplayer.c ;)
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
117 First just after config parsing, the iterator is created there. Also
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
118 after stream opening, in case the stream is a playlist it replace the
11271
252fb0cf331a spelling fixes, mostly by <ismail.donmez@boun.edu.tr>
diego
parents: 11047
diff changeset
119 entry which contained the playlist by the result of the parsing.
22316
f3d7a1b58a82 cosmetics: Fix some common typos, appropiate --> appropRiate,
diego
parents: 11271
diff changeset
120 In the event handling it check if a step can be done, etc. And finnaly
4860
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
121 at the end it go the next entry.
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
122
bfe0c6e9359c A first attempt to document the playtree system
albeu
parents:
diff changeset
123 Suggestion, flames, etc about this doc must go to albeu@free.fr