seal 0.1.0

data/include/seal/core.h

@@ -0,0 +1,95 @@
+/*
+ * core.h is part of the Scorched End Audio Library (SEAL) and is licensed
+ * under the terms of the GNU Lesser General Public License. See COPYING
+ * attached with the library.
+ *
+ * core.h defines interfaces for low-level Seal operations.
+ */
+
+#ifndef _SEAL_CORE_H_
+#define _SEAL_CORE_H_
+
+#include <stddef.h>
+#include "err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Initializes Seal by specifying the device name. This function is not
+ * re-entrant nor thread-safe and should be called only once per Seal session.
+ * Match a call to `seal_startup' with a call to `seal_cleanup' and never call
+ * `seal_starup' twice in a row.
+ *
+ * @param device_name   the name of a device; 0 to use the default one
+ */
+seal_err_t seal_startup(const char* /*device_name*/);
+
+/* Uninitializes Seal and invalidate all Seal objects. Thread-unsafe. */
+void seal_cleanup(void);
+
+/*
+ * @return  the maximum number of effect slots a source can feed concurrently.
+ */
+int seal_get_per_src_effect_limit(void);
+
+/*
+ * Gets the Seal version string.
+ *
+ * @return  the version string
+ */
+const char* seal_get_version(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+/*
+ *****************************************************************************
+ * Below are **implementation details**.
+ *****************************************************************************
+ */
+
+void _seal_sleep(unsigned int millisec);
+
+/* Common types. */
+typedef void _seal_openal_initializer_t(int, unsigned int*);
+typedef void _seal_openal_destroyer_t(int, const unsigned int*);
+typedef char _seal_openal_validator_t(unsigned int);
+typedef void _seal_openal_setterf(unsigned int, int, float);
+typedef void _seal_openal_getterf(unsigned int, int, float*);
+typedef void _seal_openal_setteri(unsigned int, int, int);
+typedef void _seal_openal_getteri(unsigned int, int, int*);
+
+/* Common helpers. */
+unsigned int _seal_openal_id(void*);
+seal_err_t _seal_gen_objs(int, unsigned int*, _seal_openal_initializer_t*);
+seal_err_t _seal_delete_objs(int, const unsigned int*,
+                             _seal_openal_destroyer_t*);
+seal_err_t _seal_init_obj(void*, _seal_openal_initializer_t*);
+seal_err_t _seal_destroy_obj(void*, _seal_openal_destroyer_t*,
+                             _seal_openal_validator_t*);
+seal_err_t _seal_setf(void*, int, float, _seal_openal_setterf*);
+seal_err_t _seal_getf(void*, int, float*, _seal_openal_getterf*);
+seal_err_t _seal_seti(void*, int, int, _seal_openal_setteri*);
+seal_err_t _seal_geti(void*, int, int*, _seal_openal_getteri*);
+seal_err_t _seal_getb(void*, int, char*, _seal_openal_getteri*);
+
+/* OpenAL effect extension functions. */
+extern _seal_openal_initializer_t* alGenEffects;
+extern _seal_openal_destroyer_t* alDeleteEffects;
+extern _seal_openal_validator_t* alIsEffect;
+extern _seal_openal_setterf* alEffectf;
+extern void (*alEffecti)(unsigned int, int, int);
+extern _seal_openal_getterf* alGetEffectf;
+extern void (*alGetEffecti)(unsigned int, int, int*);
+extern _seal_openal_initializer_t* alGenAuxiliaryEffectSlots;
+extern _seal_openal_destroyer_t* alDeleteAuxiliaryEffectSlots;
+extern _seal_openal_validator_t* alIsAuxiliaryEffectSlot;
+extern void (*alAuxiliaryEffectSloti)(unsigned int, int, int);
+extern void (*alAuxiliaryEffectSlotf)(unsigned int, int, float);
+extern void (*alGetAuxiliaryEffectSloti)(unsigned int, int, int*);
+extern void (*alGetAuxiliaryEffectSlotf)(unsigned int, int, float*);
+
+#endif /* _SEAL_CORE_H_ */

data/include/seal/efs.h

@@ -0,0 +1,112 @@
+/*
+ * efs.h is part of the Scorched End Audio Library (SEAL) and is
+ * licensed under the terms of the GNU Lesser General Public License. See
+ * COPYING attached with the library.
+ *
+ * efs.h defines the effect slot type, which is the container type for
+ * effects. A source can mix an effect in an effect slot to filter the output
+ * sound.
+ */
+
+#ifndef _SEAL_EFS_H_
+#define _SEAL_EFS_H_
+
+#include "src.h"
+#include "err.h"
+
+typedef struct seal_efs_t seal_efs_t;
+
+/*
+ * Initializes a new effect slot. If the effect slot is no longer needed, call
+ * `seal_destroy_efs' to release the resources used by the effect
+ * slot.
+ *
+ * @param efs   the effect slot to initialize
+ */
+seal_err_t seal_init_efs(seal_efs_t*);
+
+/*
+ * Destroys an effect slot.
+ *
+ * @param efs   the effect slot to destroy
+ */
+seal_err_t seal_destroy_efs(seal_efs_t*);
+
+/*
+ * Fills an effect slot with an effect object, then the effect Slot will
+ * become ready to be mixed with sources. Pass 0 to unfill the slot.
+ *
+ * @param efs       the effect slot to fill
+ * @param effect    the effect to fill the effect slot with
+ */
+seal_err_t seal_set_efs_effect(seal_efs_t*, void* /*effect*/);
+
+/*
+ * Mixes a sound effect loaded into an effect slot with a source's output.
+ * Later calls to this function with a different effect slot and the same
+ * index will override the old effect slot association.
+ *
+ * @see             seal_get_neffects_per_src
+ * @param efs       the slot that contains the effect to mix
+ * @param index     the zero-based index of the effect
+ * @param src       the source that feeds the effect slot
+ */
+seal_err_t seal_feed_efs(seal_efs_t*, int /*index*/, seal_src_t*);
+
+/*
+ * Sets the output level of an effect Slot in the interval [0.0f, 1.0f]. A
+ * value of 0.0 mutes the output.
+ *
+ * @param efs   the effect slot to set the gain of
+ * @param gain  the gain
+ */
+seal_err_t seal_set_efs_gain(seal_efs_t*, float /*gain*/);
+
+/*
+ * Sets whether the effect should have automatic adjustments based on the
+ * physical positions of the sources and the listener.
+ *
+ * @param efs       the effect slot to set the auto adjust flag of
+ * @param automatic 1 to set it auto adjust or otherwise 0
+ */
+seal_err_t seal_set_efs_auto(seal_efs_t*, char /*automatic*/);
+
+/*
+ * Gets the effect object in an effect slot. The default is 0 (null pointer).
+ *
+ * @param efs   the effect slot to get the effect object of
+ * @return      the effect object
+ */
+void* seal_get_efs_effect(seal_efs_t*);
+
+/*
+ * Gets the output level of an effect Slot in the interval. The default is
+ * 1.0f.
+ *
+ * @param efs   the effect slot to get the gain of
+ * @param pgain the receiver of the gain
+ */
+seal_err_t seal_get_efs_gain(seal_efs_t*, float* /*pgain*/);
+
+/*
+ * Determines if the effect is automatically adjusted. The default is true
+ * (nonzero).
+ *
+ * @param efs   the effect slot to determine
+ * @param pauto the receiver of the auto adjust flag
+ */
+seal_err_t seal_is_efs_auto(seal_efs_t*, char* /*pauto*/);
+
+/*
+ *****************************************************************************
+ * Below are **implementation details**.
+ *****************************************************************************
+ */
+
+struct seal_efs_t
+{
+    unsigned int id;
+    void*        effect;
+};
+
+#endif /* _SEAL_EFS_H_ */

data/include/seal/err.h

@@ -0,0 +1,93 @@
+/*
+ * err.h is part of the Scorched End Audio Library (SEAL) and is licensed
+ * under the terms of the GNU Lesser General Public License. See COPYING
+ * attached with the library.
+ *
+ * err.h defines Seal errors and provides subroutines for clearing and
+ * retriving errors. Seal functions will set a thread-local error flag when
+ * error strikes, so if the last Seal function call returns 0, the exact error
+ * and detailed error message can be retrieved using functions in this module.
+ */
+
+#ifndef _SEAL_ERR_H_
+#define _SEAL_ERR_H_
+
+enum seal_err_t
+{
+    SEAL_OK,
+
+    SEAL_BAD_OBJ,
+    SEAL_BAD_ENUM,
+    SEAL_BAD_VAL,
+    SEAL_BAD_OP,
+
+    SEAL_CANNOT_OPEN_DEVICE,
+    SEAL_NO_EFX,
+    SEAL_NO_EXT_FUNC,
+    SEAL_BAD_DEVICE,
+    SEAL_CANNOT_CREATE_CONTEXT,
+
+    SEAL_STREAM_UNOPENED,
+    SEAL_MIXING_STREAM_FMT,
+
+    SEAL_MIXING_SRC_TYPE,
+
+    SEAL_CANNOT_OPEN_FILE,
+    SEAL_BAD_AUDIO,
+
+    SEAL_CANNOT_ALLOC_MEM,
+
+    SEAL_BAD_PRESET,
+
+    SEAL_BAD_WAV_SUBTYPE,
+    SEAL_BAD_WAV_CHUNK,
+    SEAL_BAD_WAV_CHUNK_SIZE,
+    SEAL_ABSENT_WAV_CHUNK,
+    SEAL_BAD_WAV_BPS,
+    SEAL_BAD_WAV_NCHANNELS,
+    FILE_BAD_WAV_FREQ,
+    SEAL_CANNOT_REWIND_WAV,
+
+    SEAL_CANNOT_OPEN_OV,
+    SEAL_CANNOT_GET_OV_INFO,
+    SEAL_CANNOT_READ_OV,
+    SEAL_CANNOT_REWIND_OV,
+    SEAL_CANNOT_CLOSE_OV,
+
+    SEAL_CANNOT_INIT_MPG,
+    SEAL_CANNOT_GET_MPG_INFO,
+    SEAL_CANNOT_READ_MPG,
+    SEAL_CANNOT_REWIND_MPG,
+    SEAL_CANNOT_CLOSE_MPG,
+};
+
+typedef enum seal_err_t seal_err_t;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Gets a Seal error message.
+ *
+ * @param err   the error to get the message associated with
+ * @return      the error message if there is any or otherwise 0
+ */
+const char* seal_get_err_msg(seal_err_t);
+
+#ifdef __cplusplus
+}
+#endif
+
+/*
+ *****************************************************************************
+ * Below are **implementation details**.
+ *****************************************************************************
+ */
+
+/*
+ * @return  the OpenAL error as a Seal error
+ */
+seal_err_t _seal_get_openal_err(void);
+
+#endif /* _SEAL_ERR_H_ */

data/include/seal/fmt.h

@@ -0,0 +1,58 @@
+/*
+ * fmt.h is part of the Scorched End Audio Library (SEAL) and is licensed
+ * under the terms of the GNU Lesser General Public License. See COPYING
+ * attached with the library.
+ *
+ * fmt.h defines all the supported audio file format and provides utilities
+ * to deal with them.
+ */
+
+#ifndef _SEAL_FMT_H_
+#define _SEAL_FMT_H_
+
+#include "err.h"
+
+enum seal_fmt_t
+{
+    SEAL_UNKNOWN_FMT,
+    SEAL_WAV_FMT,
+    SEAL_OV_FMT,
+    SEAL_MPG_FMT
+};
+
+/* Audio file formats. */
+typedef enum seal_fmt_t seal_fmt_t;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Tries to recognize an audio file's format by peeking its header. Use of
+ * this function is by no mean an accurate way to determine the exact encoding
+ * of the audio file; it only considers the format directly supported by Seal
+ * as if there are only these types of format in the world. Assumes `audio' is
+ * at the beginning.
+ *
+ * @param filename  the filename of the audio
+ * @param pfmt      the receiver of the format if recognized or otherwise
+ *                  `SEAL_UNKNOWN_FMT'
+ */
+seal_err_t seal_recognize_fmt(const char* /*filename*/, seal_fmt_t* /*pfmt*/);
+
+/*
+ * Ensures an audio format is known.
+ *
+ * @param filename  the filename of the audio to check format of
+ * @param pfmt      if `*pfmt' is not `SEAL_UNKNOWN_FMT' then do nothing;
+ *                  otherwise the file format is checked and `pfmt' receives
+ *                  the known format
+ */
+seal_err_t seal_ensure_fmt_known(const char* /*filename*/,
+                                 seal_fmt_t* /*pfmt*/);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _SEAL_FMT_H_ */

data/include/seal/listener.h

@@ -0,0 +1,103 @@
+/*
+ * listener.h is part of the Scorched End Audio Library (SEAL) and is licensed
+ * under the terms of the GNU Lesser General Public License. See COPYING
+ * attached with the library.
+ *
+ * listener.h wraps up the listener singleton object, which is the abstract
+ * representation of the sole listener who hears the sound.
+ */
+
+#ifndef _SEAL_LISTENER_H_
+#define _SEAL_LISTENER_H_
+
+#include "err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Sets the master scalar amplitude multiplier of the listener which applies
+ * to all the sources. 1.0f means that the sound is unattenuated; 0.5f means
+ * an attenuation of 6 dB; 0.0f means silence.
+ *
+ * @param gain  the scalar amplitude multiplier in the interval [0.0f, +inf.)
+ */
+seal_err_t seal_set_listener_gain(float /*gain*/);
+
+/*
+ * Sets the position of the listener in a right-handed Cartesian coordinate
+ * system. Use of NaN and infinity is undefined.
+ *
+ * @param x     the x position to set
+ * @param y     the y position to set
+ * @param z     the z position to set
+ */
+seal_err_t seal_set_listener_pos(float /*x*/, float /*y*/, float /*z*/);
+
+/*
+ * Sets the velocity of the listener in a right-handed Cartesian coordinate
+ * system. The velocity of the listener does not affect its position but is a
+ * factor used during the Doppler effect emulation.
+ *
+ * @param x     the x velocity to set
+ * @param y     the y velocity to set
+ * @param z     the z velocity to set
+ */
+seal_err_t seal_set_listener_vel(float /*x*/, float /*y*/, float /*z*/);
+
+/*
+ * Sets the orientation of the listener.
+ *
+ * @param orien a pair of 3-tuple consisting of an 'at' vector and an 'up'
+ *              vector, where the 'at' vector represents the 'forward'
+ *              direction of the listener and the 'up' vector represents the
+ *              'up' direction for the listener. These two vectors must be
+ *              linearly independent, must not be NaN and must not be
+ *              normalized. Otherwise, the operation is undefined
+ */
+seal_err_t seal_set_listener_orien(float* /*orien*/);
+
+/*
+ * Gets the gain of the listener. The default is 1.0f.
+ *
+ * @see         seal_set_listener_gain
+ * @param pgain the receiver of the gain
+ */
+seal_err_t seal_get_listener_gain(float* /*pgain*/);
+
+/*
+ * Gets the position of the listener. The default is ( 0.0f, 0.0f, 0.0f ).
+ *
+ * @see         seal_set_listener_pos
+ * @param px    the receiver of the x position
+ * @param py    the receiver of the y position
+ * @param pz    the receiver of the z position
+ */
+seal_err_t seal_get_listener_pos(float* /*px*/, float* /*py*/, float* /*pz*/);
+
+/*
+ * Gets the velocity of the listener. The default is ( 0.0f, 0.0f, 0.0f ).
+ *
+ * @see         seal_set_listener_vel
+ * @param px    the receiver of the x velocity
+ * @param py    the receiver of the y velocity
+ * @param pz    the receiver of the z velocity
+ */
+seal_err_t seal_get_listener_vel(float* /*px*/, float* /*py*/, float* /*pz*/);
+
+/*
+ * Gets the orientation of the listener. The default is
+ * ( 0.0f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f ).
+ *
+ * @see seal_set_listener_orien
+ * @param orien the array of a pair of 3-tuple that receives the 'at' vector
+ *              and the 'up' vector
+ */
+seal_err_t seal_get_listener_orien(float* /*orien*/);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _SEAL_LISTENER_H_ */