sndio/libsndio/siomix_open.3

.\" $OpenBSD$
.\"
.\" Copyright (c) 2011 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 29 2012 $
.Dt SIO_OPEN 3
.Os
.Sh NAME
.Nm siomix_open ,
.Nm siomix_close ,
.Nm siomix_ondesc ,
.Nm siomix_onctl ,
.Nm siomix_setctl ,
.Nm siomix_nfds ,
.Nm siomix_pollfd ,
.Nm siomix_eof
.Nd interface to audio mixer
.Sh SYNOPSIS
.Fd #include <sndio.h>
.Ft "struct siomix_hdl *"
.Fn "siomix_open" "const char *name" "unsigned int mode" "int nbio_flag"
.Ft "void"
.Fn "siomix_close" "struct siomix_hdl *hdl"
.Ft "int"
.Fn "siomix_ondesc" "struct siomix_hdl *hdl" "void (*cb)(void *arg, struct siomix_desc *desc, int val)" "void *arg"
.Ft "void"
.Fn "siomix_onctl" "struct siomix_hdl *hdl" "void (*cb)(void *arg, unsigned int addr, unsigned int val)" "void *arg"
.Ft "int"
.Fn "siomix_setctl" "struct siomix_hdl *hdl" "unsigned int addr" "unsigned int val"
.Ft "int"
.Fn "siomix_nfds" "struct siomix_hdl *hdl"
.Ft "int"
.Fn "siomix_pollfd" "struct siomix_hdl *hdl" "struct pollfd *pfd" "int events"
.Ft "int"
.Fn "siomix_revents" "struct siomix_hdl *hdl" "struct pollfd *pfd"
.Ft "int"
.Fn "siomix_eof" "struct siomix_hdl *hdl"
.Sh DESCRIPTION
The audio mixer of a sound device is the set of available controls,
e.g. the volume control.
Each control has an integer
.Em address
and an integer
.Em value .
Depending on the control type, its integer value represents either a
continuous quantity or a boolean.
Any control may be changed by submitting
a new value to its address.
When values change, asynchronous notifications are sent.
.Pp
Controls descriptions are available, allowing them to be grouped and
represented in a human usable form.
.Sh Opening and closing the mixer
First the application must call the
.Fn siomix_open
function to obtain a handle
that will be passed as the
.Ar hdl
argument to other functions.
.Pp
The
.Ar name
parameter gives the device string discussed in
.Xr sndio 7 .
In most cases it should be set to SIOMIX_DEVANY to allow
the user to select it using the
.Ev AUDIODEVICE
environment variable.
The
.Ar mode
parameter is a bitmap of the SIOMIX_READ and SIOMIX_WRITE constants
indicating whether control values can be read and
modified respectively.
.Pp
If the
.Ar nbio_flag
argument is 1, then the
.Fn siomix_setctl
function (see below) may fail instead of blocking and
the
.Fn siomix_ondesc
function doesn't block.
.Pp
The
.Fn siomix_close
function closes the mixer and frees any allocated resources
associated with the handle.
.Sh Mixer description
The
.Fn siomix_ondesc
function can be used to obtain the description of all available mixer controls
and their initial values.
It registers a call-back that is immediately invoked for all
controls.
It's called once with a NULL argument to indicate that the full
description was sent and that the caller has a consistent
representation of the mixer.
.Pp
Then, whenever a mixer control description changes, the call-back is
invoked with the updated information followed by a call with a NULL
argument.
.Pp
Controls are described by the
.Va siomix_ondesc
stucture as follows:
.Bd -literal
struct siomix_chan {
	char str[SIOMIX_NAMEMAX];	/* stream name */
	int unit;			/* optional number */
};

struct siomix_desc {
	unsigned int addr;		/* control's address */
#define SIOMIX_NUM		2	/* number in the 0..127 range */
#define SIOMIX_SW		3	/* on/off switch */
#define SIOMIX_VEC		4	/* element of array of numbers */
#define SIOMIX_LIST		5	/* element of array of switches */
	unsigned int type;		/* one of above */
	char func[SIOMIX_NAMEMAX];	/* function name */
	struct siomix_chan chan0;	/* affected channels */
	struct siomix_chan chan1;	/* dito for vec, and list */
};
.Ed
.Pp
The
.Va addr
attribute is the mixer control address, usable with
.Fn siomix_setval
to set its value.
.Pp
The
.Va type
attribute indicates what the structure describes.
Possible types are:
.Bl -tag -width "SIOMIX_LIST"
.It SIOMIX_NUM
A continuous control in the 0..SIOMIX_INTMAX range.
For instance the volume of the speaker.
.It SIOMIX_SW
A on/off switch control.
For instance the switch to mute the speaker.
.It SIOMIX_VEC
Element of an array of continuous controls.
For instance the knob to control the amount of signal flowing
from the line input to the speaker.
.It SIOMIX_LIST
An element of an array of on/off switches.
For instance the line-in position of the
speaker source selector.
.El
.Pp
The
.Va func
attribute is the name of the parameter being controlled.
There may be no parameters of different types with the same name.
.Pp
The
.Va chan0
and
.Va chan1
attributes indicate the names of the affected streams, and
an optional channel sub-set.
.Va chan1
is meaningful for
.Va SIOMIX_VEC
and
.Va SIOMIX_LIST
only.
.Pp
Stream names in the
.Va chan0
and
.Va chan1
attributes and
.Va func
are static strings usable as unique identifiers.
.Sh Changing and reading control values
Controls are changed with the
.Fn siomix_setctl
function, by giving the index of the control and the new value.
The
.Fn siomix_onctl
function can be used to register a call-back which will be invoked whenever
a control changes.
Continuous values are in the 0..127 range.
.Sh "Interface to" Xr poll 2
The
.Fn siomix_pollfd
function fills the array
.Ar pfd
of
.Va pollfd
structures, used by
.Xr poll 2 ,
with
.Ar events ;
the latter is a bit-mask of
.Va POLLIN
and
.Va POLLOUT
constants.
.Fn siomix_pollfd
returns the number of
.Va pollfd
structures filled.
The
.Fn siomix_revents
function returns the bit-mask set by
.Xr poll 2
in the
.Va pfd
array of
.Va pollfd
structures.
If
.Va POLLOUT
is set,
.Fn siomix_setctl
can be called without blocking.
POLLHUP may be set if an error occurs, even if
it is not selected with
.Fn siomix_pollfd .
POLLIN is not used yet.
.Pp
The
.Fn siomix_nfds
function returns the number of
.Va pollfd
structures the caller must preallocate in order to be sure
that
.Fn siomix_pollfd
will never overrun.
.Sh SEE ALSO
.Xr sndioctl 1 ,
.Xr poll 2 ,
.Xr sndio 7