[jog] / au.h

/* -*-c-*-
 *
 * $Id: au.h,v 1.2 2002/02/02 22:43:50 mdw Exp $
 *
 * Audio handling
 *
 * (c) 2002 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Jog: Programming for a jogging machine.
 *
 * Jog is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * Jog is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with Jog; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: au.h,v $
 * Revision 1.2  2002/02/02 22:43:50  mdw
 * Provide a decent interface for finding out about the audio cache and
 * configuring its capacity.
 *
 * Revision 1.1  2002/02/02 19:16:28  mdw
 * New audio subsystem.
 *
 */

#ifndef AU_H
#define AU_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#include <mLib/bits.h>
#include <mLib/sym.h>

/*----- Data structures ---------------------------------------------------*/

/* --- An audio sample --- *
 *
 * We maintain a cache of sample data, keyed by textual tags.  An entry in
 * the cache may indicate one of three states:
 *
 *   * a tag for a sample which doesn't exist (negative answer);
 *
 *   * a sample whose data is currently resident; or
 *
 *   * sample with nonresident data.
 *
 * A negative answer is indicated by the @AUF_NOMATCH@ flag.  If an entry has
 * resident data, the @a@ pointer is non-null.
 */

typedef struct au_sample {
  sym_base s;                           /* Base structure for name lookup */
  unsigned f;                           /* Flags for this entry */
  struct au_data *a;                    /* Sample data, if present */
} au_sample;

#define AUF_NOMATCH 1u                  /* Cached non-match for this tag */

/* --- Audio data --- *
 *
 * The actual sample data, in an internal representation chosen by the
 * system-specific layer.
 *
 * The sample data can be in one of two states: in-use or spare.  Sample data
 * is considered to be in-use if the @ref@ field is nonzero.  Spare sample
 * data is left in-memory for efficiency's sake, but will be discarded
 * (least-recently-used first) when the total size of sample data (as
 * measured by the @sz@ fields) exceeds @AU_CACHEMAX@.
 */

typedef struct au_data {
  struct au_data *next, *prev;          /* Other samples in this list */
  unsigned ref;                         /* Reference count for sample data */
  struct au_sample *s;                  /* Parent sample node */
  octet *p;                             /* Pointer to sample file data */
  size_t sz;                            /* Size of sample file data */
} au_data;

/* --- Audio cache information --- */

typedef struct au_cacheinfo {
  size_t sz_max;                        /* Maximum allowed cache size */
  size_t sz_total;                      /* Total size used by samples */
  size_t sz_spare;                      /* Size used by `spare' samples */
  size_t sz_queue;                      /* Size used by queued samples */
  unsigned n_total;                     /* Total number of cached samples */
  unsigned n_spare;                     /* Number of `spare' samples */
  unsigned n_queue;                     /* Number of queued samples */
  unsigned long hits;                   /* Number of cache hits */
  unsigned long misses;                 /* Number of cache misses */
} au_cacheinfo;

#define AU_CACHEMAX 0x01000000          /* Default cache maximum size */

/*----- Functions provided ------------------------------------------------*/

/* --- @au_init@ --- *
 *
 * Arguments:   @const char *dir@ = samples directory, or null
 *              @size_t max@ = maximum cache size
 *
 * Returns:     ---
 *
 * Use:         Initializes the audio subsystem.
 */

extern void au_init(const char */*dir*/, size_t /*max*/);

/* --- @au_shutdown@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     ---
 *
 * Use:         Shuts down the audio subsystem.
 */

extern void au_shutdown(void);

/* --- @au_getcacheinfo@ --- *
 *
 * Arguments:   @au_cacheinfo *c@ = where to put the information
 *
 * Returns:     ---
 *
 * Use:         Extracts audio cache information.
 */

extern void au_getcacheinfo(au_cacheinfo */*c*/);

/* --- @au_setcachelimit@ --- *
 *
 * Arguments:   @size_t max@ = new cache limit
 *
 * Returns:     ---
 *
 * Use:         Reconfigures the maximum cache size.  This probably isn't
 *              very useful, but it was easy...
 */

extern void au_setcachelimit(size_t /*max*/);

/* --- @au_find@ --- *
 *
 * Arguments:   @const char *tag@ = sample tag string
 *
 * Returns:     A pointer to the sample corresponding to the tag, or null if
 *              the sample wasn't found.
 *
 * Use:         Looks up a sample by its name.
 */

extern au_sample *au_find(const char */*tag*/);

/* --- @au_fetch@ --- *
 *
 * Arguments:   @au_sample *s@ = sample pointer
 *
 * Returns:     A pointer to the audio data for the sample.
 *
 * Use:         Fetches a sample, and decodes it, if necessary.  The decoded
 *              sample data is left with an outstanding reference to it, so
 *              it won't be freed.  This is used internally by @au_queue@,
 *              before passing the fetched sample data to the system-specific
 *              layer for playback.  It can also be used to lock sample data
 *              in memory (e.g., for the `abort' error message), or (by
 *              freeing it immediately afterwards) to prefetch a sample which
 *              will be used soon, to reduce the latency before the sample is
 *              heard.
 */

extern au_data *au_fetch(au_sample */*s*/);

/* --- @au_queue@ --- *
 *
 * Arguments:   @au_sample *s@ = sample pointer
 *
 * Returns:     Zero on success, nonzero on failure.
 *
 * Use:         Queues a sample to be played.
 */

extern int au_queue(au_sample */*s*/);

/* --- @au_free@, @au_free_unlocked@ --- *
 *
 * Arguments:   @au_data *a@ = pointer to audio data block
 *
 * Returns:     ---
 *
 * Use:         Frees a sample data block when it's no longer required.
 */

extern void au_free(au_data */*a*/);
extern void au_free_unlocked(au_data */*a*/);

/* --- @au_play@, @au_tryplay@ --- *
 *
 * Arguments:   @const char *tag@ = sample tag string
 *
 * Returns:     Zero on success, nonzero on failure.
 *
 * Use:         Convenience functions for queueing samples by tag.
 *              If @au_tryplay@ cannot find the requested sample, it returns
 *              a zero value; if @au_play@ cannot find the sample, it aborts
 *              the program.
 */

extern int au_play(const char */*tag*/);
extern int au_tryplay(const char */*tag*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif