src/playlist/randomizer.h

   1 /*****************************************************************************
   2  * randomizer.h
   3  *****************************************************************************
   4  * Copyright (C) 2018 VLC authors and VideoLAN
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation; either version 2.1 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  19  *****************************************************************************/
  20
  21 #ifndef RANDOMIZER_H
  22 #define RANDOMIZER_H
  23
  24 #include <vlc_common.h>
  25 #include <vlc_vector.h>
  26
  27 typedef struct vlc_playlist_item vlc_playlist_item_t;
  28
  29 /**
  30  * \defgroup playlist_randomizer Playlist randomizer helper
  31  * \ingroup playlist
  32  *  @{ */
  33
  34 /**
  35  * Playlist helper to manage random playback.
  36  *
  37  * See randomizer.c for implementation details.
  38  */
  39 struct randomizer {
  40     struct VLC_VECTOR(vlc_playlist_item_t *) items;
  41     unsigned short xsubi[3]; /* random state */
  42     bool loop;
  43     size_t head;
  44     size_t next;
  45     size_t history;
  46 };
  47
  48 /**
  49  * Initialize an empty randomizer.
  50  */
  51 void
  52 randomizer_Init(struct randomizer *randomizer);
  53
  54 /**
  55  * Destroy a randomizer.
  56  */
  57 void
  58 randomizer_Destroy(struct randomizer *randomizer);
  59
  60 /**
  61  * Enable or disable "loop" mode.
  62  *
  63  * This affects the behavior of prev/next.
  64  */
  65 void
  66 randomizer_SetLoop(struct randomizer *randomizer, bool loop);
  67
  68 /**
  69  * Return the number of items in the randomizer.
  70  */
  71 bool
  72 randomizer_Count(struct randomizer *randomizer);
  73
  74 /**
  75  * Start a new random cycle.
  76  *
  77  * The "history" is lost, and "next" can be called _n_ times if the randomizer
  78  * contains _n_ items (when loop is disabled).
  79  */
  80 void
  81 randomizer_Reshuffle(struct randomizer *randomizer);
  82
  83 /**
  84  * Indicate whether there is a previous item.
  85  */
  86 bool
  87 randomizer_HasPrev(struct randomizer *randomizer);
  88
  89 /**
  90  * Indicate whether there is a next item.
  91  */
  92 bool
  93 randomizer_HasNext(struct randomizer *randomizer);
  94
  95 /**
  96  * Peek the previous item (without changing the current one).
  97  */
  98 vlc_playlist_item_t *
  99 randomizer_PeekPrev(struct randomizer *randomizer);
 100
 101 /**
 102  * Peek the next item (without changing the current one).
 103  */
 104 vlc_playlist_item_t *
 105 randomizer_PeekNext(struct randomizer *randomizer);
 106
 107 /**
 108  * Go back to the previous item.
 109  */
 110 vlc_playlist_item_t *
 111 randomizer_Prev(struct randomizer *randomizer);
 112
 113 /**
 114  * Go back to the next item.
 115  */
 116 vlc_playlist_item_t *
 117 randomizer_Next(struct randomizer *randomizer);
 118
 119 /**
 120  * Force the selection of a specific item.
 121  *
 122  * This function should be called when the user requested to play a specific
 123  * item in the playlist.
 124  */
 125 void
 126 randomizer_Select(struct randomizer *randomizer,
 127                   const vlc_playlist_item_t *item);
 128
 129 /**
 130  * Add items to the randomizer.
 131  *
 132  * This function should be called when items are added to the playlist.
 133  */
 134 bool
 135 randomizer_Add(struct randomizer *randomizer, vlc_playlist_item_t *items[],
 136                size_t count);
 137
 138 /**
 139  * Remove items from the randomizer.
 140  *
 141  * This function should be called when items are removed from the playlist.
 142  */
 143 void
 144 randomizer_Remove(struct randomizer *randomizer,
 145                   vlc_playlist_item_t *const items[], size_t count);
 146
 147 /**
 148  * Clear the randomizer.
 149  */
 150 void
 151 randomizer_Clear(struct randomizer *randomizer);
 152
 153 /** @} */
 154
 155 #endif