#ifndef _SOUND_#d#define _SOUND_H
/*=
Sound and music
2600
**/

// Introduction
/**
The Raydium sound API is pretty easy to use and there's only need to use a
few functions to make your program ouput sounds or music.

On top of this, there are a bunch of functions to modify the sound behavior.

Raydium uses OpenAL and OggVorbis for its sounds and musics, for a basic
use of our sound API you only need to know one thing: OpenAL uses buffers
for its sounds and you need to be able to address the sounds separately.
For this we use ALuint in our code. Each buffer is associated to a source,
we have an array of all available sources and then, you only need to have
a simple int that acts as an index in this array. See below for more
informations.

Music is readed thru libogg, streamed from disk. If you want to play an
OGG audio track, the only thing you've to do is to call the suitable function.
You can use ##raydium_sound_music_eof_callback## if needed. This event is
fired when sound track ends, allowing you to switch to another file.
Prototype for this callback is ##int callback(char *new_track)##, allowing
you to do something like ##strcpy(new_track,"foobar.ogg"); return 1;##.
Return 0 if you do not want to switch to another audio file (this will stops
music playback).
Another callback is available, ##raydium_sound_music_changed_callback##, fired
just after a music track switch, allowing you to get new informations from the
new stream, such as artist, album and title. See ##raydium_sound_load_music()##
for more informations about this.

This document is not an alternative to OpenAL papers, and only provides
informations about Raydium's interface to OpenAL.
See specifications here: http://www.openal.org/documentation.html
**/

__rayapi void raydium_sound_verify (char *caller);
/**
This functions checks if any error occured during last OpenAL operation.
You don't have to call this function by yourself, since every function of
this API will do it.
**/

__rayapi int raydium_sound_Array3IsValid(ALfloat *a);
/**
Since OpenAL is very sensitive to malformed values, this function is used
internally to check consistency of provided ALfloat arrays.
**/

__rayapi void raydium_sound_InitSource (int src);
/**
Internal use.
**/

__rayapi int raydium_sound_LoadWav (const char *fname);
/**
This function tries to load the ##fname## wav file into a buffer, if
successful, it returns the source id, else 0.
**/

__rayapi int raydium_sound_SourceVerify (int src);
/**
Internal id checks.
**/

__rayapi int raydium_sound_SetSourceLoop (int src, signed char loop);
/**
Modifies the ##loop## property of the ##src## source (loops if loop is non-zero,
default value for a source is "true").
Returns 0 if ok, -1 if error.
**/

__rayapi int raydium_sound_GetSourcePitch (int src, ALfloat * p);
/**
Returns current pitch for ##src## source.
**/

__rayapi int raydium_sound_SetSourcePitch (int src, ALfloat p);
/**
Sets pitch for ##src## source.
Current OpenAL spec is not clear about pitch's limits. Raydium will
clamp values to to ]0,2] interval.
**/

__rayapi int raydium_sound_GetSourceGain (int src, ALfloat * g);
/**
Returns current gain ("volume") for ##src## source.
**/

__rayapi int raydium_sound_SetSourceGain (int src, ALfloat g);
/**
Sets gain ("volume") for ##src## source.
Current OpenAL spec is not clear about pitch's limits. Raydium do not allows
negative values, but no upper limit is set.
Warning: some OpenAL implementations will provide strange gain curves. More
work is needed on this issue.
**/

__rayapi int raydium_sound_SetSourceRefDist(int src, ALfloat distance);
/**
Sets reference distance for source ##src##. The reference distance is
the distance where the sound will be half-volume.
**/

__rayapi int raydium_sound_SetSourcePos (int src, ALfloat Pos[]);
/**
Sets 3D position of ##src## source.
##Pos## is a 3 * ALfloat array.
**/

__rayapi int raydium_sound_SetSourcePosCamera(int src);
/**
Sets 3D position of ##src## source on the current camera position.
**/

__rayapi int raydium_sound_GetSourcePos (int src, ALfloat * Pos[]);
/**
Returns current 3D pospacing between 2 consecutive letters. With
standard fonts, 0.5 is a correct value (relatively condensed text).

- ##texture## is obviously the texture filename to use (font*.tga are
often provided with Raydium distribution, and by R3S).

- ##format## is the standard printf format string, followed by
corresponding arguments: ##"^9Player ^Fname is: %10s", player_name##
This format can use '^' char to change color text, followed by a color,
indicated by a hexadecimal letter (EGA palette). See ##raydium_osd_color_ega##
function, above.

Here you are a simple example:

%%(c)
strcpy(version,"^Ctest 0.1^F");
raydium_osd_printf(2,98,16,0.5,"font2.tga","- %3i FPS - tech demo %s for Raydium %s, CQFD Corp.",
                   raydium_render_fps,version,raydium_version);
%%
**/

__rayapi void raydium_osd_printf_3D (GLfloat x, GLfloat y, GLfloat z, GLfloat size, GLfloat spacer, char *texture, char *format, ...);
/**
Same as above, but you can place your text in your application 3D space,
using ##x##, ##y## and ##z## values.
**/

__rayapi void raydium_osd_logo (char *texture);
/**
Will draw a logo for the current frame with texture filename.
For now, you've no control over rotation speed of the logo.
**/

__rayapi void raydium_osd_cursor_set (char *texture, GLfloat xsize, GLfloat ysize);
/**
This function will set mouse cursor with texture filename and
with (##xsize##,##ysize##) size (percent of screen size).
You should use a RGB**A** texture for better results.
example:
%%(c)
raydium_osd_cursor_set("BOXcursor.tga",4,4);
%%

You can set ##texture## to NULL or empty string to cancel OSD cursor texture.

This cursor is not impacted by raydium_mouse_show/hide functions, you should
use raydium_osd_cursor_show/hide for this.
**/

__rayapi void raydium_osd_cursor_offset(GLfloat xoffset, GLfloat yoffset);
/**
This function allows to offset the cursor. Used with non-regular cursor
textures. The units are percentage of the screen.
**/

__rayapi void raydium_osd_cursor_show(void);
/**
Shows the OSD cursor.
**/

__rayapi void raydium_osd_cursor_hide(void);
/**
Hides the OSD cursor.
**/

__rayapi void raydium_osd_cursor_draw (void);
/**
Internal use.
**/

__rayapi void raydium_osd_internal_vertex (GLfloat x, GLfloat y, GLfloat top);
/**
Internal use.
**/

__rayapi void raydium_osd_network_stat_draw (GLfloat px, GLfloat py, GLfloat size);
/**
Will draw network stats (if available) in a box.
%%(c) raydium_osd_network_stat_draw(5,30,20); %%
**/

__rayapi void raydium_osd_mask (GLfloat * color4);
/**
Will draw a uniform mask using ##color4## (RGBA color) for this frame.
**/

__rayapi void raydium_osd_mask_texture(int texture,GLfloat alpha);
/**
Will draw a textured mask, with ##alpha## opacity (1 is full opacity).
**/

__rayapi void raydium_osd_mask_texture_name(char *texture,GLfloat alpha);
/**
Same as above, but resolving texture by name.
**/

__rayapi void raydium_osd_mask_texture_clip(int texture,GLfloat alpha, GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2);
/**
Same as ##raydium_osd_mask_texture##, but (x1,y1),(x2,y2) will be used as
texture coords, in a [0,100] range.
**/

__rayapi void raydium_osd_mask_texture_clip_name(char *texture,GLfloat alpha, GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2);
/**
Same as above, but resolving texture by name.
**/

__rayapi void raydium_osd_fade_callback (void);
/**
Internal use.
**/

__rayapi void raydium_osd_fade_init (void);
/**
Internal use.
**/

__rayapi void raydium_osd_fade_from (GLfloat * from4, GLfloat * to4, GLfloat time_len, void *OnFadeEnd);
/**
This function will configure a fading mask from ##from4## color to ##to4##.
This fade will last ##time_len## seconds, and will call ##OnFadeEnd## callback
when finished.
This callback signature must be ##void callback(void)##.

A standard fade-to-black-and-restore example:
%%(c)
// back to normal rendering
void restorefade(void)
{
   GLfloat from[4]={0,0,0,2};
   GLfloat to[4]={0,0,0,0};
   raydium_osd_fade_from(from,to,1,NULL);
   // do things (like moving camera to another place, for example).
}

...

// If space key : fade to black
if(raydium_key_last==1032)
    {
    GLfloat from[4]={0,0,0,0};
    GLfloat to[4]={0,0,0,1};
    raydium_osd_fade_from(from,to,0.3,restorefade);
    }
%%
**/

#endif
 raydium_sound_source_fade_to(int src, ALfloat len, char *to);
/**
Same as above, but plays ##to## file at the end of the fade.
Warning: Works only for "music" source (##src## = 0).
**/

#endif