2014-07-16 05:05:01 -05:00
|
|
|
.\" $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
|
2015-08-13 10:37:45 -05:00
|
|
|
continuous quantity or a boolean.
|
2014-07-16 05:05:01 -05:00
|
|
|
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
|
2015-09-04 10:08:12 -05:00
|
|
|
Then, whenever a mixer control description changes, the call-back is
|
|
|
|
invoked with the updated information followed by a call with a NULL
|
|
|
|
argument.
|
2014-07-16 05:05:01 -05:00
|
|
|
.Pp
|
|
|
|
Controls are described by the
|
|
|
|
.Va siomix_ondesc
|
|
|
|
stucture as follows:
|
|
|
|
.Bd -literal
|
|
|
|
struct siomix_chan {
|
|
|
|
char str[SIOMIX_NAMEMAX]; /* stream name */
|
2015-09-04 10:08:12 -05:00
|
|
|
int unit; /* optional number */
|
2014-07-16 05:05:01 -05:00
|
|
|
};
|
|
|
|
|
|
|
|
struct siomix_desc {
|
2017-08-02 18:53:40 -05:00
|
|
|
unsigned int addr; /* control address */
|
|
|
|
#define SIOMIX_NUM 2 /* integer in the 0..127 range */
|
|
|
|
#define SIOMIX_SW 3 /* on/off switch (0 or 1) */
|
|
|
|
#define SIOMIX_VEC 4 /* number, element of vector */
|
|
|
|
#define SIOMIX_LIST 5 /* switch, element of a list */
|
2014-07-16 05:05:01 -05:00
|
|
|
unsigned int type; /* one of above */
|
2015-09-04 10:08:12 -05:00
|
|
|
char func[SIOMIX_NAMEMAX]; /* function name */
|
2017-08-02 18:53:40 -05:00
|
|
|
struct siomix_chan group; /* group this control belongs to */
|
2014-07-16 05:05:01 -05:00
|
|
|
struct siomix_chan chan0; /* affected channels */
|
2017-08-02 18:53:40 -05:00
|
|
|
struct siomix_chan chan1; /* dito for SIOMIX_{VEC,LIST} */
|
2014-07-16 05:05:01 -05:00
|
|
|
};
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Va addr
|
2015-08-13 10:37:45 -05:00
|
|
|
attribute is the mixer control address, usable with
|
2014-07-16 05:05:01 -05:00
|
|
|
.Fn siomix_setval
|
|
|
|
to set its value.
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Va type
|
|
|
|
attribute indicates what the structure describes.
|
|
|
|
Possible types are:
|
2015-09-04 10:08:12 -05:00
|
|
|
.Bl -tag -width "SIOMIX_LIST"
|
2014-07-16 05:05:01 -05:00
|
|
|
.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
|
2015-06-03 23:12:38 -05:00
|
|
|
.Va func
|
2014-07-16 05:05:01 -05:00
|
|
|
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
|
2015-03-05 03:12:34 -06:00
|
|
|
attributes indicate the names of the affected streams, and
|
|
|
|
an optional channel sub-set.
|
2014-07-16 05:05:01 -05:00
|
|
|
.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
|
2015-06-03 23:12:38 -05:00
|
|
|
.Va func
|
2016-01-28 12:17:11 -06:00
|
|
|
are strings usable as unique identifiers within the the given
|
|
|
|
.Va namespace .
|
2014-07-16 05:05:01 -05:00
|
|
|
.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
|