| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
oss_mixext ext;
extr.dev=mixer_device_number;
extr.ctrl=controller_number;
ioctl(fd, SNDCTL_MIX_EXTINFO, &ext);
The above code fragment lacks all error checks for clarity. Real world applications must always check for the errors and handle them as described below. Also most OSS ioctl calls will return information in the argument variable and it's usually necessary to check it too.
Use this ioctl call to obtain a mixer control descriptor for a device. The dev and ctrl fields of the oss_mixext structure needs to be initialized before the call. Use the SNDCTL_MIX_NRMIX and SNDCTL_MIX_NREXTioctl calls to find out the available device and control numbers.
| Field | Description |
dev | Mixer device number. Should be initialized before making the call. Value of -1 means the current mixer device number. |
ctrl | The mixer control number (0 to N-1). |
type | Type of the mixer control (see below). |
maxvalue | Maximum value. Exact meaning depends on the control type. |
minvalue | Minimum value or range offset. Exact meaning depends on the control type. |
flags | Mixer control flags (see below). |
id | Name of the mixer control as specified by the device driver. See the "Mixer control names" section (below). |
parent | Number of the group node that owns this mixer control or group. This parent node link can be used by GUI mixer programs to find out where this control or group should be located on the screen. |
timestamp | This field is used for managing changes in the mixer structure. In some situations the driver may remove some parts of the mixer interface and replace them with different ones. This happens for example when some master mode control is changed. The application should copy the value of this field to the timestamp field of the oss_mixer_value record before making the SNDCTL_MIX_READ or SNDCTL_MIX_WRITE calls. If the timestamp value is different than the one of the current control then these ioctl calls will return an error (errno==EIDRM). This is a signal to the mixer application that it should re-create it's GUI to match the current mixer structure. |
data | A record containing additional information for some mixer control or group types. Currently struct oss_mixext_root type is used for the root node (MIXT_ROOT). |
enum_present | Used with enumerated controls MIXT_ENUM to tell which enumerated settings/choises are available at this moment. This field is a bitmap where enum_present[N/8] & (1<<(N%8)) tells if choice N is currently permitted. |
control_no | This field is used by some drivers to tell the legacy mixer control number matches this control. This field has no use in the real world. |
extname | Hierarchical name of the mixer control. See the "Mixer control names" section (below). |
update_counter | This field will get incremented every time the value of this mixer control is changed by some application. However in reality applications should not use this field since some controls may change their value spontaneously (without incrementing this field). For groups (MIXT_GROUP and MIXT_DEVROOT contains the number of controls currently contained by the group and it's child groups. However this reference count feature is new to OSS 4.1 and older versions will always return 0 in this field for group nodes. |
rgbcolor | The driver may return a 24 bit RGB color to be used with a control (see below). |
The application can read and write the actual mixer controls by using SNDCTL_MIX_READ and SNDCTL_MIX_WRITE.
Usage of the control depends on the type field returned by this call. See the descriptions of the control types (below) for more details.
See the Scaling of mixer control values section for more info for interpreting the maxvalue and minvalue fields.
| Source | Explanation |
| MIXT_3D | Experimental 3D positioning control MIXT_3D (not implemented) |
| MIXT_DEVROOT | Mixer device root group MIXT_DEVROOT |
| MIXT_ENUM | Enumerated mixer control MIXT_ENUM |
| MIXT_GROUP | Generic mixer group node MIXT_GROUP |
| MIXT_HEXVALUE | Hexadecimal mixer value control MIXT_HEXVALUE |
| MIXT_MARKER | Legacy mixer boundary marker MIXT_MARKER |
| MIXT_MESSAGE | Alphanumeric string control MIXT_MESSAGE |
| MIXT_MONODB | Mixer control type MIXT_MONODB (obsolete) |
| MIXT_MONOPEAK | Mono peak meter control MIXT_MONOPEAK |
| MIXT_MONOSLIDER16 | Mono volume slider with 16 bit value field MIXT_MONOSLIDER16 |
| MIXT_MONOSLIDER | 8 bit mono volume slider MIXT_MONOSLIDER |
| MIXT_MONOVU | Undefined control MIXT_MONOVU |
| MIXT_MUTE | Mute control MIXT_MUTE |
| MIXT_ONOFF | ON/OFF type mixer control MIXT_ONOFF |
| MIXT_RADIOGROUP | Mixer control type MIXT_RADIOGROUP |
| MIXT_ROOT | Mixer root group (MIXT_ROOT) |
| MIXT_SLIDER | Mono volume slider with expanded range MIXT_SLIDER |
| MIXT_STEREODB | Mixer control type MIXT_STEREODB |
| MIXT_STEREOPEAK | Stereo peak meter control MIXT_STEREOPEAK |
| MIXT_STEREOSLIDER16 | Stereo volume slider with 16 bit precision MIXT_STEREOSLIDER16 |
| MIXT_STEREOSLIDER | Stereo volume slider with 8 bit precision MIXT_STEREOSLIDER |
| MIXT_STEREOVU | Mixer control type MIXT_STEREOVU |
| MIXT_VALUE | General purpose decimal value mixer control MIXT_VALUE |
There are few control flags (returned in the flags field that enhance the bahaviour of the control.
| Source | Explanation |
| MIXF_CENTIBEL | Mixer control uses centibel (0.1 dB) scale |
| MIXF_DECIBEL | Mixer control used decibel scale |
| MIXF_DESCR | Control has a description (tooltip and help) string available. |
| MIXF_DYNAMIC | Mixer control flag MIXF_DYNAMIC |
| MIXF_FLAT | Mixer group is flat |
| MIXF_HZ | Mixer control uses HZ scale. |
| MIXF_LEGACY | Mixer group contains legacy controls |
| MIXF_MAINVOL | Mixer widget controls main output volume. |
| MIXF_MONVOL | Mixer widget controls direct input to output monitoring volume. |
| MIXF_OKFAIL | Mixer control has OK/FAIL type value |
| MIXF_PCMVOL | Mixer widget controls audio (pcm) output volume |
| MIXF_POLL | Value may change spontaneously |
| MIXF_READABLE | Mixer control is readable |
| MIXF_RECVOL | Mixer control is used for recording volume |
| MIXF_STRING | Mixer control flag MIXF_STRING |
| MIXF_WIDE | Mixer control needs more horizontal space |
| MIXF_WRITEABLE | Mixer control is writeable |
There are two different fields in the oss_mixext structure that give the name of the control. The id field is the original name given by the driver when it created the control. This name can be used by fully featured GUI mixers. However this name should be downshifted and cut before the last underscore ("_") to get the proper name. For example mixer control name created as "MYDRV_MAINVOL" will become just "mainvol" after this transformation.
Non-GUI mixers and GUI mixers using the simple mixer interface shoud use the control name gicen in the extname field. This field gives the hierarchical name composed from the id field and the names of the parent nodes. For example "jack.pink.vol".
The rgbcolor field was introduced in OSS 4.1. Older OSS versions don't have this field. Applications using this field can only be compiled under OSS 4.1 and later (#ifdef OSS_RGB_RED). However applications compiled under v4.1 can be run under OSS 4.0 because the rgbcolor field will be automatically initialized to 0.
Practically all modern motherboards and consumer sound cards use color coded 3.5 mm jacks for audio input and outputs (pink=mic, etc). OSS drivers may return a 24 bit RGB value that matches the jack color (or whatever) in the rgbcolor field. Value of 0 means that the driver has not returned any color (it does't mean full black). Mixer applications may use this color as the color of the slider or other display element created for the mixer control. This should make it easier to the user to identify which audio jack the slider controls. However applications must ensure that use of colors doesn't cause any readability problems.
The color values use the standard encoding (0xXXRRGGBB in hexadecimal) where XX is reserved (must be set to 0), RR=red, GG=green and BB=blue.
OSS drivers can return any RGB color they want. However its recommemded to avoid (background) colors that may make black text on foreground invisible or difficult to read. It is highly recommended that only the colors predefined in soundcard.h are used (OSS_RGB_BLUE, OSS_RGB_GREEN, OSS_RGB_PINK, OSS_RGB_GRAY, OSS_RGB_BLACK and OSS_RGB_ORANGE, OSS_RGB_RED, OSS_RGB_YELLOW, OSS_RGB_PURPLE, OSS_RGB_WHITE). This makes it easier to the applications to select the right foreground color if they use the rgbcolor value as the background color. For example applications may need to use white text on OSS_RGB_BLACK background.
The return value from the OSS ioctl calls will be -1 if a fatal error occurred. Other values mean that the ioctl call was more or less successful. However in most cases the application must check the value returned in the argument to see what was the accepted value.
Please see the Possible error codes (errno) returned by OSS calls section for more info about the error codes returned by OSS.
| ossxmix.c | This is the ossxmix (GTK++ GUI) program shipped with OSS |
| ossmix.c | Sources for the ossmix command line mixer shipped with OSS |
| mixer_applet.c | A sample program for developing a simple mixer applet. |
| mixext.c | A simple sample program for using the new mixer API |