1 /** 2 * @file api_audiod_sfx.h 3 * Sound effects playback interface for an audio driver. @ingroup audio 4 * 5 * @authors Copyright © 2003-2017 Jaakko Keränen <jaakko.keranen@iki.fi> 6 * @authors Copyright © 2006-2013 Daniel Swanson <danij@dengine.net> 7 * 8 * @par License 9 * GPL: http://www.gnu.org/licenses/gpl.html 10 * 11 * <small>This program is free software; you can redistribute it and/or modify 12 * it under the terms of the GNU General Public License as published by the 13 * Free Software Foundation; either version 2 of the License, or (at your 14 * option) any later version. This program is distributed in the hope that it 15 * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty 16 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 17 * Public License for more details. You should have received a copy of the GNU 18 * General Public License along with this program; if not, write to the Free 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 20 * 02110-1301 USA</small> 21 */ 22 23 #ifndef __DOOMSDAY_AUDIO_DRIVER_SFX_H__ 24 #define __DOOMSDAY_AUDIO_DRIVER_SFX_H__ 25 26 /// @addtogroup audio 27 ///@{ 28 29 /** 30 * @defgroup sfxBufferFlags Sfx Buffer Flags 31 * @ingroup audio apiFlags 32 */ 33 ///@{ 34 #define SFXBF_PLAYING 0x1 ///< The buffer is playing. 35 #define SFXBF_3D 0x2 ///< Otherwise playing in 2D mode. 36 #define SFXBF_REPEAT 0x4 ///< Buffer will repeat until stopped. 37 #define SFXBF_DONT_STOP 0x8 ///< Never stop until normal finish. 38 #define SFXBF_STREAM 0x10 ///< Buffer plays in streaming mode (looping). 39 #define SFXBF_RELOAD 0x10000 ///< Sample must be reloaded before playing. 40 ///@} 41 42 /// Sfx interface properties. 43 enum { 44 SFXIP_DISABLE_CHANNEL_REFRESH = 1, ///< The channel refresh thread is not needed. 45 SFXIP_ANY_SAMPLE_RATE_ACCEPTED = 2 ///< Samples don't all need the same rate. 46 }; 47 48 /// Events. 49 enum { 50 SFXEV_BEGIN, ///< An update is about to begin. 51 SFXEV_END ///< The update is done. 52 }; 53 54 /// Buffer properties. 55 enum { 56 SFXBP_VOLUME, ///< 0..1 57 SFXBP_FREQUENCY, ///< 1 = normal 58 SFXBP_PAN, ///< -1..1 (2D only) 59 SFXBP_MIN_DISTANCE, ///< 3D only 60 SFXBP_MAX_DISTANCE, 61 SFXBP_POSITION, 62 SFXBP_VELOCITY, 63 SFXBP_RELATIVE_MODE 64 }; 65 66 /// Listener properties. 67 enum { 68 SFXLP_UPDATE, ///< Not a real value (commit deferred) 69 SFXLP_PRIMARY_FORMAT, ///< Arguments are bits and rate. 70 SFXLP_UNITS_PER_METER, 71 SFXLP_DOPPLER, 72 SFXLP_POSITION, 73 SFXLP_VELOCITY, 74 SFXLP_ORIENTATION, 75 SFXLP_REVERB ///< Use SRD_* for indices. 76 }; 77 78 /// Listener audio environment properties. 79 enum { 80 SFXLP_REVERB_VOLUME, 81 SFXLP_REVERB_SPACE, 82 SFXLP_REVERB_DECAY, 83 SFXLP_REVERB_DAMPING, 84 NUM_REVERB_DATA 85 }; 86 87 typedef struct sfxsample_s { 88 int id; ///< Id number of the sound sample. 89 void* data; ///< Actual sample data. 90 unsigned int size; ///< Size in bytes. 91 int numSamples; ///< Number of samples. 92 int bytesPer; ///< Bytes per sample (1 or 2). 93 int rate; ///< Samples per second. 94 int group; ///< Exclusion group (0, if none). 95 } sfxsample_t; 96 97 typedef struct sfxbuffer_s { 98 void* ptr; ///< Pointer to driver's own buffer object. 99 void* ptr3D; ///< Pointer to driver's 3D buffer data. 100 struct sfxsample_s* sample; ///< Source sample data. 101 int bytes; ///< Bytes per sample (1 or 2). 102 int rate; ///< Samples per second. 103 int flags; 104 unsigned int length; ///< Length of the buffer (bytes). 105 unsigned int cursor; ///< Write cursor position (%length). 106 unsigned int written; ///< Total bytes written. 107 unsigned int endTime; ///< System time, milliseconds (if !repeating). 108 unsigned int freq; ///< Played samples per second (real freq). 109 } sfxbuffer_t; 110 111 /** 112 * When a buffer is using SFXBF_STREAM, a sample's data pointer is interpreted 113 * as a sfxstreamfunc_t and will be called whenever the sample needs more data 114 * streamed in. 115 */ 116 typedef int (*sfxstreamfunc_t)(sfxbuffer_t* buf, void* data, unsigned int size); 117 118 /// Generic driver interface. All other interfaces are based on this. 119 typedef struct audiointerface_sfx_generic_s { 120 int (*Init) (void); 121 sfxbuffer_t* (*Create) (int flags, int bits, int rate); 122 void (*Destroy) (sfxbuffer_t* buf); 123 void (*Load) (sfxbuffer_t* buf, struct sfxsample_s* sample); 124 void (*Reset) (sfxbuffer_t* buf); 125 void (*Play) (sfxbuffer_t* buf); 126 void (*Stop) (sfxbuffer_t* buf); 127 void (*Refresh) (sfxbuffer_t* buf); 128 void (*Set) (sfxbuffer_t* buf, int prop, float value); 129 void (*Setv) (sfxbuffer_t* buf, int prop, float* values); 130 void (*Listener) (int prop, float value); 131 void (*Listenerv) (int prop, float* values); 132 int (*Getv) (int prop, void* values); 133 } audiointerface_sfx_generic_t; 134 135 typedef struct audiointerface_sfx_s { 136 audiointerface_sfx_generic_t gen; 137 } audiointerface_sfx_t; 138 139 ///@} 140 141 #endif 142