.TH "roar_vs_volume_get" "3" "May 2011" "RoarAudio" "RoarAudio Programmer's Manual"

.SH NAME
roar_vs_volume_get, roar_vs_volume_mono, roar_vs_volume_stereo \- Get or set volume for audio stream

.SH SYNOPSIS

#include <roaraudio.h>

int     roar_vs_volume_get    (roar_vs_t * vss, float * l, float * r, int * error);

int     roar_vs_volume_mono   (roar_vs_t * vss, float c, int * error);

int     roar_vs_volume_stereo (roar_vs_t * vss, float l, float r, int * error);

.SH "DESCRIPTION"
Those functions are used to get or set volume for the given stream.

\fBroar_vs_volume_get()\fR gets the volume for the given stream in stereo form as
a left and a right component (L/R). If you need the mono volume just divide the sum of both
by two. See examples below.

\fBroar_vs_volume_mono()\fR sets the mono volume for the stream. Balance information is not kept.

\fBroar_vs_volume_stereo()\fR sets the stereo volume for the stream as left and right component (L/R).

.SH "PARAMETERS"
.TP
\fBvss\fR
The VS object for which volume is get or set.

.TP
\fBl\fR, \fBr\fR, \fBc\fR
The volume for left, right or center (mono) channel. Value is a float in range zero to one.
Zero means this channel is fully muted. One means the channel is passed without altering the amplitude.

Small numerical errors are detected and corrected. Bigger errors will result in a out of range error.

Note that to mute the stream you MUST NOT use volume setting but \fBroar_vs_mute\fR(3).

.TP
\fBerror\fR
This is a pointer to a integer used to store the error value in case of error.
This can be NULL if not used but it is very recommended to use this error value to report
good error messages to the user.

.SH "RETURN VALUE"
On success these calls return 0.  On error, \-1 is returned.

.SH "EXAMPLES"
Getting mono volume:

 float l, r, c;
 int err;

 if ( roar_vs_volume_get(vss, &l, &r, &err) == \-1 ) {
  /* handle error */
 }
 c = (l + r)/2.;

.SH "SEE ALSO"
\fBroarvs\fR(7),
\fBlibroar\fR(7),
\fBRoarAudio\fR(7).

.\" ll