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

   1 /* -*-c-*-
   2  *
   3  * $Id: au.h,v 1.1 2002/02/02 19:16:28 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.1  2002/02/02 19:16:28  mdw
  33  * New audio subsystem.
  34  *
  35  */
  36
  37 #ifndef AU_H
  38 #define AU_H
  39
  40 #ifdef __cplusplus
  41   extern "C" {
  42 #endif
  43
  44 /*----- Header files ------------------------------------------------------*/
  45
  46 #include <stddef.h>
  47
  48 #include <mLib/bits.h>
  49 #include <mLib/sym.h>
  50
  51 /*----- Data structures ---------------------------------------------------*/
  52
  53 /* --- An audio sample --- *
  54  *
  55  * We maintain a cache of sample data, keyed by textual tags.  An entry in
  56  * the cache may indicate one of three states:
  57  *
  58  *   * a tag for a sample which doesn't exist (negative answer);
  59  *
  60  *   * a sample whose data is currently resident; or
  61  *
  62  *   * sample with nonresident data.
  63  *
  64  * A negative answer is indicated by the @AUF_NOMATCH@ flag.  If an entry has
  65  * resident data, the @a@ pointer is non-null.
  66  */
  67
  68 typedef struct au_sample {
  69   sym_base s;                           /* Base structure for name lookup */
  70   unsigned f;                           /* Flags for this entry */
  71   struct au_data *a;                    /* Sample data, if present */
  72 } au_sample;
  73
  74 #define AUF_NOMATCH 1u                  /* Cached non-match for this tag */
  75
  76 /* --- Audio data --- *
  77  *
  78  * The actual sample data, in an internal representation chosen by the
  79  * system-specific layer.
  80  *
  81  * The sample data can be in one of two states: in-use or spare.  Sample data
  82  * is considered to be in-use if the @ref@ field is nonzero.  Spare sample
  83  * data is left in-memory for efficiency's sake, but will be discarded
  84  * (least-recently-used first) when the total size of sample data (as
  85  * measured by the @sz@ fields) exceeds @AU_CACHEMAX@.
  86  */
  87
  88 typedef struct au_data {
  89   struct au_data *next, *prev;          /* Other samples in this list */
  90   unsigned ref;                         /* Reference count for sample data */
  91   struct au_sample *s;                  /* Parent sample node */
  92   octet *p;                             /* Pointer to sample file data */
  93   size_t sz;                            /* Size of sample file data */
  94 } au_data;
  95
  96 #define AU_CACHEMAX 0x01000000          /* Maximum resident sample data */
  97
  98 /*----- Functions provided ------------------------------------------------*/
  99
 100 /* --- @au_init@ --- *
 101  *
 102  * Arguments:   @const char *dir@ = samples directory, or null
 103  *              @size_t max@ = maximum cache size
 104  *
 105  * Returns:     ---
 106  *
 107  * Use:         Initializes the audio subsystem.
 108  */
 109
 110 extern void au_init(const char */*dir*/, size_t /*max*/);
 111
 112 /* --- @au_shutdown@ --- *
 113  *
 114  * Arguments:   ---
 115  *
 116  * Returns:     ---
 117  *
 118  * Use:         Shuts down the audio subsystem.
 119  */
 120
 121 extern void au_shutdown(void);
 122
 123 /* --- @au_find@ --- *
 124  *
 125  * Arguments:   @const char *tag@ = sample tag string
 126  *
 127  * Returns:     A pointer to the sample corresponding to the tag, or null if
 128  *              the sample wasn't found.
 129  *
 130  * Use:         Looks up a sample by its name.
 131  */
 132
 133 extern au_sample *au_find(const char */*tag*/);
 134
 135 /* --- @au_fetch@ --- *
 136  *
 137  * Arguments:   @au_sample *s@ = sample pointer
 138  *
 139  * Returns:     A pointer to the audio data for the sample.
 140  *
 141  * Use:         Fetches a sample, and decodes it, if necessary.  The decoded
 142  *              sample data is left with an outstanding reference to it, so
 143  *              it won't be freed.  This is used internally by @au_queue@,
 144  *              before passing the fetched sample data to the system-specific
 145  *              layer for playback.  It can also be used to lock sample data
 146  *              in memory (e.g., for the `abort' error message), or (by
 147  *              freeing it immediately afterwards) to prefetch a sample which
 148  *              will be used soon, to reduce the latency before the sample is
 149  *              heard.
 150  */
 151
 152 extern au_data *au_fetch(au_sample */*s*/);
 153
 154 /* --- @au_queue@ --- *
 155  *
 156  * Arguments:   @au_sample *s@ = sample pointer
 157  *
 158  * Returns:     Zero on success, nonzero on failure.
 159  *
 160  * Use:         Queues a sample to be played.
 161  */
 162
 163 extern int au_queue(au_sample */*s*/);
 164
 165 /* --- @au_free@, @au_free_unlocked@ --- *
 166  *
 167  * Arguments:   @au_data *a@ = pointer to audio data block
 168  *
 169  * Returns:     ---
 170  *
 171  * Use:         Frees a sample data block when it's no longer required.
 172  */
 173
 174 extern void au_free(au_data */*a*/);
 175 extern void au_free_unlocked(au_data */*a*/);
 176
 177 /* --- @au_play@, @au_tryplay@ --- *
 178  *
 179  * Arguments:   @const char *tag@ = sample tag string
 180  *
 181  * Returns:     Zero on success, nonzero on failure.
 182  *
 183  * Use:         Convenience functions for queueing samples by tag.
 184  *              If @au_tryplay@ cannot find the requested sample, it returns
 185  *              a zero value; if @au_play@ cannot find the sample, it aborts
 186  *              the program.
 187  */
 188
 189 extern int au_play(const char */*tag*/);
 190 extern int au_tryplay(const char */*tag*/);
 191
 192 /*----- That's all, folks -------------------------------------------------*/
 193
 194 #ifdef __cplusplus
 195   }
 196 #endif
 197
 198 #endif