git.sesse.net Git - vlc/blob - doc/developer2/playlist.xml

   1 <chapter><title>Playlist core</title>
   2
   3 <sect1><title>Concepts</title>
   4
   5 <sect2><title>Overview</title>
   6
   7 VLC's playlist now features a tree system, with a notion of several
   8 views. Each view comes with a new tree. Items can be shared between
   9 views. Items can become internal nodes.
  10
  11 </sect2>
  12
  13 <sect2><title>Views</title>
  14
  15 The predefined views are :
  16
  17 <itemizedlist>
  18
  19 <listitem><para>The "simple" view which only contains the "manually
  20 added" items (either added through command line, either through command
  21 line). It can contain a hierarchy.</para></listitem>
  22
  23 <listitem><para>The "category" view contains a "General" node that is
  24 exactly like the "simple" view. It can also contains several types of
  25 items (generally, "autodiscovered". Examples are:</para>
  26
  27 <itemizedlist>
  28
  29 <listitem><para>SAP items</para></listitem>
  30 <listitem><para>Audio CD if detected</para></listitem>
  31 <listitem><para>imported playlists</para></listitem>
  32
  33 </itemizedlist>
  34 </listitem>
  35
  36 <listitem><para>The "all items" flat view contains all items without any hierarchy</para></listitem>
  37
  38 <listitem><para>Sorted views (Sorted by author, with a node per author, ...)</para></listitem>
  39
  40 </itemizedlist>
  41
  42 </sect2>
  43
  44 <sect2><title>Who uses this ?</title>
  45
  46 <sect3><title>Services discovery modules</title>
  47
  48 A new type of modules has been created, the services_discovery modules.
  49 Their goal is to add items to the playlist (SAP listener, HAL (Hardware
  50 Abstraction Layer), ...).
  51
  52 </sect3>
  53
  54 </sect2>
  55
  56 </sect1>
  57
  58 <sect1><title>How does the playlist work</title>
  59
  60 <sect2><title>Process overview</title>
  61
  62 <para>On startup, a playlist thread is started. It starts an infinite
  63 loop, always searching for something to do.</para>
  64
  65 <itemizedlist>
  66
  67 <listitem><para>If a request is triggered by an action on the playlist,
  68 stop the current item and process the request</para></listitem>
  69
  70 <listitem><para>If the current item has finished, stop it and go to next
  71 item</para></listitem>
  72
  73 </itemizedlist>
  74
  75 </sect2>
  76
  77 <sect2><title>Data structures</title>
  78
  79 <sect3><title>View</title>
  80
  81 <para>Each view is identified by an identifier. It also contains a
  82 pointer to the root item.</para>
  83
  84 </sect3>
  85
  86 <sect3><title>Item</title>
  87
  88 <para>An item can be either a leaf node (which can be played) or an
  89 internal node of the tree (can not be played directly, but contains
  90 children).</para>
  91
  92 <para>You can know if an item is a leaf or internal node by looking
  93 at i_children. If i_children is -1, then it is a leaf node, else it
  94 contains the number of children, available in pp_children.</para>
  95
  96
  97 <para>As items can be common to several views, we need to remember
  98 for each the parent in each view. That's why each item includes the
  99 pp_parents array. Each one is an <code>item_parent_t</code> structure
 100 that contains the view identifier, and the parent _in this view_.</para>
 101
 102 <para>The <code>i_flags</code> is a bit array used to know whether an
 103 item is to be saved, whether the playlist can continue after playing
 104 this item (which is generally not the desired behaviour for SAP items,
 105 fe), whether it is enabled, and whether it must be deleted after being
 106 played.</para>
 107
 108 <para>The <code>i_serial</code> field is increased on each change of
 109 the children, if the item is an internal node. The goal is to allow
 110 interfaces to update in a clever way, by only rebuilding nodes that have
 111 changed.</para>
 112
 113 </sect3>
 114
 115 </sect2>
 116
 117 <sect2><title>Controlling the playlist</title>
 118
 119 <para>The playlist can be controlled using playlist_Control. It takes a
 120 query identifier, and a variable number of arguments.</para>
 121
 122 <para>When a control is made, the "request" field of the playlist is set
 123 to true, which causes the current item to be stopped. If needed, a new
 124 item is then selected.</para>
 125
 126 </sect2>
 127
 128 <sect2><title>Selecting an item</title>
 129
 130 <para>Different rules apply for selection of items, if a request
 131 has been made or if it is an "automatic" change, after an item has
 132 finished.</para>
 133
 134 <para>If there a request, the item is always selected if possible (if
 135 you selected a node, it will play the first available child), else, some
 136 more rules will apply (play-and-stop, random, repeat, ...).</para>
 137
 138 <para>All item selection is made in
 139 <code>src/playlist/playlist.c</code>, function NextItem.</para>
 140
 141 <para>The playlist object contains two fields dedicated to this, status
 142 and request.</para>
 143
 144 <para>This process uses tree walking functions in
 145 <code>src/playlist/view.c</code>.</para>
 146
 147 </sect2>
 148
 149 </sect1>
 150
 151 </chapter>