chiark - git - mdw - jog/blob - au.h

   1 /* -*-c-*-
   2  *
   3  * $Id: au.h,v 1.2 2002/02/02 22:43:50 mdw Exp $
   4  *
   5  * Audio handling
   6  *
   7  * (c) 2002 Mark Wooding
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Jog: Programming for a jogging machine.
  13  *
  14  * Jog is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * Jog is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with Jog; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: au.h,v $
  32  * Revision 1.2  2002/02/02 22:43:50  mdw
  33  * Provide a decent interface for finding out about the audio cache and
  34  * configuring its capacity.
  35  *
  36  * Revision 1.1  2002/02/02 19:16:28  mdw
  37  * New audio subsystem.
  38  *
  39  */
  40
  41 #ifndef AU_H
  42 #define AU_H
  43
  44 #ifdef __cplusplus
  45   extern "C" {
  46 #endif
  47
  48 /*----- Header files ------------------------------------------------------*/
  49
  50 #include <stddef.h>
  51
  52 #include <mLib/bits.h>
  53 #include <mLib/sym.h>
  54
  55 /*----- Data structures ---------------------------------------------------*/
  56
  57 /* --- An audio sample --- *
  58  *
  59  * We maintain a cache of sample data, keyed by textual tags.  An entry in
  60  * the cache may indicate one of three states:
  61  *
  62  *   * a tag for a sample which doesn't exist (negative answer);
  63  *
  64  *   * a sample whose data is currently resident; or
  65  *
  66  *   * sample with nonresident data.
  67  *
  68  * A negative answer is indicated by the @AUF_NOMATCH@ flag.  If an entry has
  69  * resident data, the @a@ pointer is non-null.
  70  */
  71
  72 typedef struct au_sample {
  73   sym_base s;                           /* Base structure for name lookup */
  74   unsigned f;                           /* Flags for this entry */
  75   struct au_data *a;                    /* Sample data, if present */
  76 } au_sample;
  77
  78 #define AUF_NOMATCH 1u                  /* Cached non-match for this tag */
  79
  80 /* --- Audio data --- *
  81  *
  82  * The actual sample data, in an internal representation chosen by the
  83  * system-specific layer.
  84  *
  85  * The sample data can be in one of two states: in-use or spare.  Sample data
  86  * is considered to be in-use if the @ref@ field is nonzero.  Spare sample
  87  * data is left in-memory for efficiency's sake, but will be discarded
  88  * (least-recently-used first) when the total size of sample data (as
  89  * measured by the @sz@ fields) exceeds @AU_CACHEMAX@.
  90  */
  91
  92 typedef struct au_data {
  93   struct au_data *next, *prev;          /* Other samples in this list */
  94   unsigned ref;                         /* Reference count for sample data */
  95   struct au_sample *s;                  /* Parent sample node */
  96   octet *p;                             /* Pointer to sample file data */
  97   size_t sz;                            /* Size of sample file data */
  98 } au_data;
  99
 100 /* --- Audio cache information --- */
 101
 102 typedef struct au_cacheinfo {
 103   size_t sz_max;                        /* Maximum allowed cache size */
 104   size_t sz_total;                      /* Total size used by samples */
 105   size_t sz_spare;                      /* Size used by `spare' samples */
 106   size_t sz_queue;                      /* Size used by queued samples */
 107   unsigned n_total;                     /* Total number of cached samples */
 108   unsigned n_spare;                     /* Number of `spare' samples */
 109   unsigned n_queue;                     /* Number of queued samples */
 110   unsigned long hits;                   /* Number of cache hits */
 111   unsigned long misses;                 /* Number of cache misses */
 112 } au_cacheinfo;
 113
 114 #define AU_CACHEMAX 0x01000000          /* Default cache maximum size */
 115
 116 /*----- Functions provided ------------------------------------------------*/
 117
 118 /* --- @au_init@ --- *
 119  *
 120  * Arguments:   @const char *dir@ = samples directory, or null
 121  *              @size_t max@ = maximum cache size
 122  *
 123  * Returns:     ---
 124  *
 125  * Use:         Initializes the audio subsystem.
 126  */
 127
 128 extern void au_init(const char */*dir*/, size_t /*max*/);
 129
 130 /* --- @au_shutdown@ --- *
 131  *
 132  * Arguments:   ---
 133  *
 134  * Returns:     ---
 135  *
 136  * Use:         Shuts down the audio subsystem.
 137  */
 138
 139 extern void au_shutdown(void);
 140
 141 /* --- @au_getcacheinfo@ --- *
 142  *
 143  * Arguments:   @au_cacheinfo *c@ = where to put the information
 144  *
 145  * Returns:     ---
 146  *
 147  * Use:         Extracts audio cache information.
 148  */
 149
 150 extern void au_getcacheinfo(au_cacheinfo */*c*/);
 151
 152 /* --- @au_setcachelimit@ --- *
 153  *
 154  * Arguments:   @size_t max@ = new cache limit
 155  *
 156  * Returns:     ---
 157  *
 158  * Use:         Reconfigures the maximum cache size.  This probably isn't
 159  *              very useful, but it was easy...
 160  */
 161
 162 extern void au_setcachelimit(size_t /*max*/);
 163
 164 /* --- @au_find@ --- *
 165  *
 166  * Arguments:   @const char *tag@ = sample tag string
 167  *
 168  * Returns:     A pointer to the sample corresponding to the tag, or null if
 169  *              the sample wasn't found.
 170  *
 171  * Use:         Looks up a sample by its name.
 172  */
 173
 174 extern au_sample *au_find(const char */*tag*/);
 175
 176 /* --- @au_fetch@ --- *
 177  *
 178  * Arguments:   @au_sample *s@ = sample pointer
 179  *
 180  * Returns:     A pointer to the audio data for the sample.
 181  *
 182  * Use:         Fetches a sample, and decodes it, if necessary.  The decoded
 183  *              sample data is left with an outstanding reference to it, so
 184  *              it won't be freed.  This is used internally by @au_queue@,
 185  *              before passing the fetched sample data to the system-specific
 186  *              layer for playback.  It can also be used to lock sample data
 187  *              in memory (e.g., for the `abort' error message), or (by
 188  *              freeing it immediately afterwards) to prefetch a sample which
 189  *              will be used soon, to reduce the latency before the sample is
 190  *              heard.
 191  */
 192
 193 extern au_data *au_fetch(au_sample */*s*/);
 194
 195 /* --- @au_queue@ --- *
 196  *
 197  * Arguments:   @au_sample *s@ = sample pointer
 198  *
 199  * Returns:     Zero on success, nonzero on failure.
 200  *
 201  * Use:         Queues a sample to be played.
 202  */
 203
 204 extern int au_queue(au_sample */*s*/);
 205
 206 /* --- @au_free@, @au_free_unlocked@ --- *
 207  *
 208  * Arguments:   @au_data *a@ = pointer to audio data block
 209  *
 210  * Returns:     ---
 211  *
 212  * Use:         Frees a sample data block when it's no longer required.
 213  */
 214
 215 extern void au_free(au_data */*a*/);
 216 extern void au_free_unlocked(au_data */*a*/);
 217
 218 /* --- @au_play@, @au_tryplay@ --- *
 219  *
 220  * Arguments:   @const char *tag@ = sample tag string
 221  *
 222  * Returns:     Zero on success, nonzero on failure.
 223  *
 224  * Use:         Convenience functions for queueing samples by tag.
 225  *              If @au_tryplay@ cannot find the requested sample, it returns
 226  *              a zero value; if @au_play@ cannot find the sample, it aborts
 227  *              the program.
 228  */
 229
 230 extern int au_play(const char */*tag*/);
 231 extern int au_tryplay(const char */*tag*/);
 232
 233 /*----- That's all, folks -------------------------------------------------*/
 234
 235 #ifdef __cplusplus
 236   }
 237 #endif
 238
 239 #endif