[src/trunk]: src/lib/libossaudio ossaudio(3): Turn BUGS section into a list o...

[nia <nia%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/fd905ece85de
branches:  trunk
changeset: 945077:fd905ece85de
user:      nia <nia%NetBSD.org@localhost>
date:      Tue Oct 20 06:43:34 2020 +0000

description:
ossaudio(3): Turn BUGS section into a list of potential compat issues

diffstat:

 lib/libossaudio/ossaudio.3 |  42 ++++++++++++++++++++++++++++--------------
 1 files changed, 28 insertions(+), 14 deletions(-)

diffs (79 lines):

diff -r a8fcafca78b5 -r fd905ece85de lib/libossaudio/ossaudio.3
--- a/lib/libossaudio/ossaudio.3        Tue Oct 20 06:33:52 2020 +0000
+++ b/lib/libossaudio/ossaudio.3        Tue Oct 20 06:43:34 2020 +0000
@@ -1,10 +1,10 @@
-.\"    $NetBSD: ossaudio.3,v 1.24 2020/10/17 09:04:59 wiz Exp $
+.\"    $NetBSD: ossaudio.3,v 1.25 2020/10/20 06:43:34 nia Exp $
 .\"
 .\" Copyright (c) 1997, 2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Lennart Augustsson,
+.\" by Lennart Augustsson and Nia Alarie.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -50,7 +50,7 @@
 building code written for other operating systems.
 .Ss Mixer Control Map
 The following table summarizes the mappings from native interface
-device names to OSS mixer controls.
+device names to OSSv3 mixer controls.
 .Bl -column ".Sy Native Device Name" "SOUND_MIXER_SPEAKER"
 .It Sy "Native Device Name" Ta Sy "OSS Mixer Control"
 .It *.mic Ta SOUND_MIXER_MIC
@@ -98,16 +98,24 @@
 .Fx
 and Solaris, and a large body of code exists supporting it.
 .Sh BUGS
-The emulation is incomplete, covering most of OSSv3 and some of OSSv4.
-Some obscure features are not included, but the essential ioctls used
-by the majority of software are covered.
-.Pp
-The emulation uses a #define for
-.Fn ioctl
-so some obscure programs
-can fail to compile.
-.Pp
-Linux,
+.Bl -bullet
+.It
+The emulation is incomplete.
+Some less popular features are not emulated (e.g. sync groups), but the
+essential ioctls used by the majority of software are covered.
+.It
+.Nx
+.Dv AUDIO_MIXER_SET
+control types cannot be accurately represented in the OSSv4 mixer API,
+so are treated as enums.
+.It
+Per-stream volume (i.e.
+.Dv SNDCTL_DSP_SETPLAYVOL )
+is not currently implemented as in OSSv4, and will instead modify the
+global volume.
+Applications need to provide samples with the appropriate gain.
+.It
+Linux, 
 .Fx ,
 and Solaris provide
 .Pa /dev/dsp
@@ -120,7 +128,7 @@
 devices this compatibility layer must be accessed through on
 .Nx .
 However, changing this is typically trivial when porting programs.
-.Pp
+.It
 The emulation only covers
 .Fn ioctl ,
 there are other differences as well.
@@ -131,3 +139,9 @@
 .Nx 1.3
 returns
 .Dv EAGAIN .
+.It
+The emulation uses a #define for
+.Fn ioctl
+so some obscure programs
+can fail to compile.
+.El