git.mutantstargoat.com Git - dosdemo/blob - libs/mikmod/drivers/dos/libgus.h

   1 /*      MikMod sound library
   2         (c) 1998, 1999 Miodrag Vallat and others - see file AUTHORS for
   3         complete list.
   4
   5         This library is free software; you can redistribute it and/or modify
   6         it under the terms of the GNU Library General Public License as
   7         published by the Free Software Foundation; either version 2 of
   8         the License, or (at your option) any later version.
   9
  10         This program is distributed in the hope that it will be useful,
  11         but WITHOUT ANY WARRANTY; without even the implied warranty of
  12         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13         GNU Library General Public License for more details.
  14
  15         You should have received a copy of the GNU Library General Public
  16         License along with this library; if not, write to the Free Software
  17         Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  18         02111-1307, USA.
  19 */
  20
  21 /*==============================================================================
  22
  23   $Id$
  24
  25   Linux libGUS-alike library for DOS, used by drv_ultra.c under DOS.
  26
  27 ==============================================================================*/
  28
  29 /*
  30         Current limitations:
  31         - Only a subset of libgus is supported
  32         - Only one GUS card is supported (due to the fact that ULTRASND environment
  33           variable is used)
  34         - No Interwawe support (if IW works the old way, it's ok).
  35 */
  36
  37 #ifndef __LIBGUS_H__
  38 #define __LIBGUS_H__
  39
  40 #include <stddef.h>
  41
  42 #define __LITTLE_ENDIAN
  43
  44 typedef struct _gus_info_t gus_info_t;
  45 typedef struct _gus_instrument_t gus_instrument_t;
  46 typedef struct _gus_wave_t gus_wave_t;
  47 typedef struct _gus_layer_t gus_layer_t;
  48
  49 #define GUS_CARD_VERSION_CLASSIC        0x0024  /* revision 2.4 */
  50 #define GUS_CARD_VERSION_CLASSIC1       0x0034  /* revision 3.4? */
  51 #define GUS_CARD_VERSION_CLASSIC_ICS    0x0037  /* revision 3.7 (ICS mixer) */
  52 #define GUS_CARD_VERSION_EXTREME        0x0050  /* GUS Extreme */
  53 #define GUS_CARD_VERSION_ACE            0x0090  /* GUS ACE */
  54 #define GUS_CARD_VERSION_MAX            0x00a0  /* GUS MAX - revision 10 */
  55 #define GUS_CARD_VERSION_MAX1           0x00a1  /* GUS MAX - revision 11 */
  56 #define GUS_CARD_VERSION_PNP            0x0100  /* GUS Plug & Play */
  57
  58 #define GUS_STRU_INFO_F_DB16            0x00000001      /* 16-bit daughter board present */
  59 #define GUS_STRU_INFO_F_PCM             0x00000004      /* GF1 PCM during SYNTH enabled */
  60 #define GUS_STRU_INFO_F_ENHANCED        0x00000008      /* InterWave - enhanced mode */
  61 #define GUS_STRU_INFO_F_DAEMON          0x00000010      /* instrument daemon is present */
  62
  63 struct _gus_info_t {
  64         unsigned char id[8];            /* id of this card (warning! maybe unterminated!!!) */
  65
  66         unsigned int flags;             /* some info flags - see to GUS_STRU_INFO_F_XXXX */
  67         unsigned int version;           /* see to GUS_CARD_VERSION_XXXX constants */
  68
  69         unsigned short port;
  70         unsigned short irq;
  71         unsigned short dma1;            /* DMA1 - GF1 download & codec record */
  72         unsigned short dma2;            /* DMA2 - GF1 record & codec playback */
  73
  74         unsigned int mixing_freq;       /* mixing frequency in Hz */
  75
  76         unsigned int memory_size;       /* in bytes */
  77         unsigned int memory_free;       /* in bytes */
  78         unsigned int memory_block_8;    /* largest free 8-bit block in memory */
  79         unsigned int memory_block_16;   /* largest free 16-bit block in memory */
  80 };
  81
  82 /* struct gus_instrument_t - mode */
  83
  84 #define GUS_INSTR_SIMPLE        0x00    /* simple format - for MOD players */
  85 #define GUS_INSTR_PATCH         0x01    /* old GF1 patch format */
  86 #define GUS_INSTR_COUNT         2
  87
  88 #define GUS_INSTR_F_NORMAL      0x0000  /* normal mode */
  89 #define GUS_INSTR_F_NOT_FOUND   0x0001  /* instrument can't be loaded */
  90 #define GUS_INSTR_F_ALIAS       0x0002  /* alias */
  91 #define GUS_INSTR_F_NOT_LOADED  0x00ff  /* instrument not loaded (not found) */
  92
  93 #define GUS_INSTR_E_NONE        0x0000  /* exclusion mode - none */
  94 #define GUS_INSTR_E_SINGLE      0x0001  /* exclude single - single note from this instrument */
  95 #define GUS_INSTR_E_MULTIPLE    0x0002  /* exclude multiple - stop only same note from this instrument */
  96
  97 #define GUS_INSTR_L_NONE        0x0000  /* not layered */
  98 #define GUS_INSTR_L_ON          0x0001  /* layered */
  99 #define GUS_INSTR_L_VELOCITY    0x0002  /* layered by velocity */
 100 #define GUS_INSTR_L_FREQUENCY   0x0003  /* layered by frequency */
 101
 102 struct _gus_instrument_t {
 103         union {
 104                 unsigned int instrument;/* instrument number */
 105         } number;
 106
 107         char *name;                     /* name of this instrument or NULL */
 108
 109         unsigned int mode:8,            /* see to GUS_INSTR_XXXX */
 110             flags:8,                    /* see to GUS_INSTR_F_XXXX */
 111             exclusion:4,                /* see to GUS_INSTR_E_XXXX */
 112             layer:4;                    /* see to GUS_INSTR_L_XXXX */
 113         unsigned short exclusion_group; /* 0 - none, 1-65535 */
 114
 115         struct {
 116                 unsigned char effect1:4,/* use global effect if available */
 117                     effect2:4;          /* use global effect if available */
 118                 unsigned char effect1_depth;/* 0-127 */
 119                 unsigned char effect2_depth;/* 0-127 */
 120         } patch;
 121
 122         union {
 123                 gus_layer_t *layer;     /* first layer */
 124                 unsigned int alias;     /* pointer to instrument */
 125         } info;
 126         gus_instrument_t *next;         /* next instrument */
 127 };
 128
 129 struct _gus_layer_t {
 130         unsigned char mode;             /* see to GUS_INSTR_XXXX constants */
 131
 132         gus_wave_t *wave;
 133         gus_layer_t *next;
 134 };
 135
 136 /* bits for format variable in gus_wave_t */
 137
 138 #define GUS_WAVE_16BIT          0x0001  /* 16-bit wave */
 139 #define GUS_WAVE_UNSIGNED       0x0002  /* unsigned wave */
 140 #define GUS_WAVE_INVERT         0x0002  /* same as unsigned wave */
 141 #define GUS_WAVE_BACKWARD       0x0004  /* forward mode */
 142 #define GUS_WAVE_LOOP           0x0008  /* loop mode */
 143 #define GUS_WAVE_BIDIR          0x0010  /* bidirectional mode */
 144 #define GUS_WAVE_ULAW           0x0020  /* uLaw compressed wave */
 145 #define GUS_WAVE_RAM            0x0040  /* wave is _preloaded_ in RAM (it is used for ROM simulation) */
 146 #define GUS_WAVE_ROM            0x0080  /* wave is in ROM */
 147 #define GUS_WAVE_DELTA          0x0100
 148
 149 #define GUS_WAVE_PATCH_ENVELOPE 0x01    /* envelopes on */
 150 #define GUS_WAVE_PATCH_SUSTAIN  0x02    /* sustain mode */
 151
 152 struct _gus_wave_t {
 153         unsigned char mode;             /* see to GUS_INSTR_XXXX constants */
 154         unsigned char format;           /* see to GUS_WAVE_XXXX constants */
 155         unsigned int size;              /* size of waveform in bytes */
 156         unsigned int start;             /* start offset in bytes * 16 (lowest 4 bits - fraction) */
 157         unsigned int loop_start;        /* bits loop start offset in bytes * 16 (lowest 4 bits - fraction) */
 158         unsigned int loop_end;          /* loop start offset in bytes * 16 (lowest 4 bits - fraction) */
 159         unsigned short loop_repeat;     /* loop repeat - 0 = forever */
 160         struct {
 161                 unsigned int memory;    /* begin of waveform in GUS's memory */
 162                 unsigned char *ptr;     /* pointer to waveform in system memory */
 163         } begin;
 164
 165         struct {
 166                 unsigned char flags;
 167                 unsigned int sample_rate;
 168                 unsigned int low_frequency;/* low frequency range for this waveform */
 169                 unsigned int high_frequency;/* high frequency range for this waveform */
 170                 unsigned int root_frequency;/* root frequency for this waveform */
 171                 signed short tune;
 172                 unsigned char balance;
 173                 unsigned char envelope_rate[6];
 174                 unsigned char envelope_offset[6];
 175                 unsigned char tremolo_sweep;
 176                 unsigned char tremolo_rate;
 177                 unsigned char tremolo_depth;
 178                 unsigned char vibrato_sweep;
 179                 unsigned char vibrato_rate;
 180                 unsigned char vibrato_depth;
 181                 unsigned short scale_frequency;
 182                 unsigned short scale_factor;/* 0-2048 or 0-2 */
 183         } patch;
 184
 185         gus_wave_t *next;
 186 };
 187
 188 /* defines for gus_memory_reset () */
 189 #define GUS_DOWNLOAD_MODE_NORMAL 0x0000
 190 #define GUS_DOWNLOAD_MODE_TEST   0x0001
 191
 192 /*
 193     A subset of libgus functions (used by MikMod Ultrasound driver)
 194 */
 195 int gus_cards(void);
 196   /*
 197    * return value:      number of GUS cards installed in system or
 198    *                    zero if driver isn't installed
 199    */
 200 int gus_close(int card);
 201   /*
 202    * close file (gus synthesizer) previously opened with gusOpen function
 203    * return value:      zero if success
 204    */
 205 int gus_do_flush(void);
 206   /*
 207    * return value:      zero if command queue was successfully flushed
 208    *                    in non block mode - number of written bytes
 209    */
 210 void gus_do_tempo(unsigned int tempo);
 211   /*
 212    * set new tempo
 213    */
 214 void gus_do_voice_frequency(unsigned char voice, unsigned int freq);
 215   /*
 216    * set voice frequency in Hz
 217    */
 218 void gus_do_voice_pan(unsigned char voice, unsigned short pan);
 219   /*
 220    * set voice pan (0-16384) (full left - full right)
 221    */
 222 void gus_do_voice_start(unsigned char voice, unsigned int program,
 223                         unsigned int freq, unsigned short volume,
 224                         unsigned short pan);
 225   /*
 226    * start voice
 227    *            voice    : voice #
 228    *            program  : program # or ~0 = current
 229    *            freq     : frequency in Hz
 230    *            volume   : volume level (0-16384) or ~0 = current
 231    *            pan      : pan level (0-16384) or ~0 = current
 232    */
 233 void gus_do_voice_start_position(unsigned char voice, unsigned int program,
 234                                  unsigned int freq, unsigned short volume,
 235                                  unsigned short pan, unsigned int position);
 236   /*
 237    * start voice
 238    *            voice    : voice #
 239    *            program  : program # or ~0 = current
 240    *            freq     : frequency in Hz
 241    *            volume   : volume level (0-16384) or ~0 = current
 242    *            pan      : pan level (0-16384) or ~0 = current
 243    *            position : offset to wave in bytes * 16 (lowest 4 bits - fraction)
 244    */
 245 void gus_do_voice_stop(unsigned char voice, unsigned char mode);
 246   /*
 247    * stop voice
 248    *            mode = 0 : stop voice now
 249    *            mode = 1 : disable wave loop and finish it
 250    */
 251 void gus_do_voice_volume(unsigned char voice, unsigned short vol);
 252   /*
 253    * set voice volume level 0-16384 (linear)
 254    */
 255 void gus_do_wait(unsigned int ticks);
 256   /*
 257    * wait x ticks - this command is block separator
 258    * all commands between blocks are interpreted in the begining of one tick
 259    */
 260 int gus_get_voice_status(int voice);
 261   /*
 262    * THIS IS NOT A FUNCTION OF ORIGINAL libGUS!
 263    * Return voice status: -1 on error, 0 if voice stopped, 1 if playing
 264    */
 265 int gus_get_handle(void);
 266   /*
 267    * return value:      file handle (descriptor) for /dev/gus
 268    */
 269 int gus_info(gus_info_t * info, int reread);
 270   /*
 271    * return value:      filled info variable with actual values
 272    *                    (look at gus.h header file for more informations)
 273    * version field:     0x0024  - GUS revision 2.4
 274    *                    0x0035  - GUS revision 3.7 with flipped mixer channels
 275    *                    0x0037  - GUS revision 3.7
 276    *                    0x0090  - GUS ACE
 277    *                    0x00a0  - GUS MAX revision 10
 278    *                    0x00a1  - GUS MAX revision 11
 279    *                    0x0100  - InterWave (full version)
 280    * flags field:       see to GUS_STRU_INFO_F_???? constants (gus.h header file)
 281    * port field:        port number (for example 0x220)
 282    * irq field:         irq number (for example 11)
 283    * dma1 field:        dma1 number (for example 5)
 284    * dma2 field:        dma2 number (for example 6)
 285    * note:              dma1 and dma2 could be same in case of only one dma channel used
 286    */
 287 int gus_memory_alloc(gus_instrument_t * instrument);
 288   /*
 289    * input value:       look at gus.h for more details about gus_instrument_t structure
 290    * return value:      zero if instrument was successfully allocated
 291    */
 292 int gus_memory_free(gus_instrument_t * instrument);
 293   /*
 294    * input value:       look at gus.h for more details about gus_instrument_t structure
 295    * return value:      zero if instrument was successfully removed
 296    */
 297 int gus_memory_size(void);
 298   /*
 299    * return value:  gus memory size in bytes
 300    */
 301 int gus_memory_free_size(void);
 302   /*
 303    * return value:      unused gus memory in bytes
 304    * warning:           reset function must be called before
 305    */
 306 int gus_memory_free_block(int w_16bit);
 307   /*
 308    * return value:  current largest free block for 8-bit or 16-bit wave
 309    */
 310 int gus_memory_pack(void);
 311   /*
 312    * return value:      zero if success
 313    */
 314 int gus_memory_reset(int mode);
 315   /*
 316    * input value:   see to GUS_DOWNLOAD_MODE_XXXX constants (gus.h)
 317    * return value:  zero if samples & instruments was successfully removed
 318    *            from GF1 memory manager
 319    */
 320
 321 int gus_open(int card, size_t queue_buffer_size, int non_block);
 322   /*
 323    * input values:      card number,
 324    *                    size of command queue buffer (512-1MB)
 325    *                    buffer is allocated dynamically,
 326    *                    non block mode
 327    * return value:      zero if success
 328    * note 1:            this function must be called as first
 329    *                    open file /dev/gus
 330    * note 2:            you can open more cards with one process
 331    */
 332 int gus_queue_flush(void);
 333   /*
 334    * return value:      zero if command queue was successfully flushed
 335    */
 336 int gus_queue_read_set_size(int items);
 337   /*
 338    * input value:       echo buffer size in items (if 0 - erase echo buffer)
 339    */
 340 int gus_queue_write_set_size(int items);
 341   /*
 342    * input value:       write queue size in items (each item have 8 bytes)
 343    */
 344 int gus_reset(int voices, unsigned int channel_voices);
 345   /*
 346    * input values:      active voices and channel voices (for dynamic allocation)
 347    * return value:      number of active voices if reset was successfull (GF1 chip active)
 348    */
 349 int gus_reset_engine_only(void);
 350   /*
 351    * return value:  same as gus_reset function
 352    * note:      this command doesn't change number of active
 353    *            voices and doesn't do hardware reset
 354    */
 355 int gus_select(int card);
 356   /*
 357    * select specified card
 358    * return value:      zero if success
 359    */
 360 int gus_timer_start(void);
 361   /*
 362    * return value:      zero if successfull
 363    */
 364 int gus_timer_stop(void);
 365   /*
 366    * return value:      zero if timer was stoped
 367    */
 368 int gus_timer_continue(void);
 369   /*
 370    * return value:  zero if timer will be continue
 371    */
 372 int gus_timer_tempo(int ticks);
 373   /*
 374    * return value:      zero if setup was success
 375    */
 376 int gus_timer_base(int base);
 377   /*
 378    * return value:  zero if setup was success (default timebase = 100)
 379    */
 380
 381 void gus_convert_delta(unsigned int type, unsigned char *dest,
 382                        unsigned char *src, size_t size);
 383   /*
 384    * note: dest and src pointers can be equal
 385    */
 386
 387 void gus_timer_callback(void (*timer_callback) ());
 388   /*
 389    * Set a callback to be called once per tempo tick
 390    */
 391
 392 int gus_dma_usage (int use);
 393   /*
 394    * Tell GUS library to use/to not use DMA for sample transfer.
 395    * In some environments/on some hardware platforms you will need
 396    * to disable DMA in order to function properly. You should call
 397    * this function before opening the card.
 398    */
 399
 400 #endif /* __LIBGUS_H__ */
 401
 402 /* ex:set ts=4: */