.\"
.\" Copyright (c) 2014-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AU_DEVOUT 3
.Os Agar 1.7
.Sh NAME
.Nm AU_DevOut
.Nd agar audio output interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/au.h>
.Ed
.Sh DESCRIPTION
The
.Nm
interface provides basic audio output functionality, using different
drivers to interface with different audio systems.
.Sh INTERFACE
.nr nS 1
.Ft "AU_DevOut *"
.Fn AU_OpenOut "const char *path" "int rate" "int channels"
.Pp
.Ft "void"
.Fn AU_CloseOut "AU_DevOut *dev"
.Pp
.Ft "int"
.Fn AU_AddChannel "AU_DevOut *dev"
.Pp
.Ft "int"
.Fn AU_DelChannel "AU_DevOut *dev" "int channel"
.Pp
.Ft "void"
.Fn AU_WriteFloat "AU_DevOut *dev" "float *data" "Uint nFrames"
.Pp
.nr nS 0
The
.Fn AU_OpenOut
function opens the specified output device.
The
.Fa path
argument should contain the name of the output driver, with optional
arguments in round brackets.
For example,
.Sq pa
opens the PortAudio output driver, if available.
The
.Sq file(foo.wav)
argument specifies the "file" driver with an output filename argument.
The
.Fa rate
argument is the requested sampling rate in Hz, and
.Fa channels
is the requested number of channels (if the device is unable to handle
those settings, the call will fail).
On success, a device handle is returned.
.Pp
.Fn AU_CloseOut
closes the specified output device.
.Pp
Every output device has an associated set of virtual channels, which is
independent from the number of channels supported by the underlying device
(software mixing is done if necessary).
The
.Fn AU_AddChannel
function adds a new virtual channel to the given output device.
.Fn AU_DelChannel
deletes the specified channel.
.Pp
The
.Fn AU_WriteFloat
routine writes
.Fa nFrames
frames to the output device.
A single frame should contain one
.Ft float
per channel.
.Sh SEE ALSO
.Xr AU 3 ,
.Xr AU_Wave 3
.Sh HISTORY
The
.Xr AU 3
library and the
.Nm
interface first appeared in Agar 1.5.0.