| OpenAL-1.3.1.1: A binding to the OpenAL cross-platform 3D audio API | Source code | Contents | Index

Sound.OpenAL.ALC.Device

Portability | portable
Stability | provisional
Maintainer | sven.panne@aedion.de

Description

This module corresponds to section 6.1 (Managing Devices) of the OpenAL Specification and Reference (version 1.1).

ALC introduces the notion of a device. A device can be, depending on the implementation, a hardware device, or a daemon/OS service/actual server. This mechanism also permits different drivers (and hardware) to coexist within the same system, as well as allowing several applications to share system resources for audio, including a single hardware output device. The details are left to the implementation, which has to map the available backends to unique device specifiers.

Synopsis

data Device
openDevice :: Maybe String -> IO (Maybe Device)
closeDevice :: Device -> IO Bool
defaultDeviceSpecifier :: GettableStateVar (Maybe String)
deviceSpecifier :: Device -> GettableStateVar String
allDeviceSpecifiers :: GettableStateVar [String]

Documentation

data Device | Source

The abstract device type.
Instances

Eq Device
Ord Device
Show Device

openDevice :: Maybe String -> IO (Maybe Device) | Source

`openDevice` allows the application (i.e. the client program) to connect to a device (i.e. the server). If the function returns `Nothing`, then no sound driver/device has been found. The argument to `openDevice` specifies a certain device or device configuration. If it is `Nothing`, the implementation will provide an implementation specific default, see `defaultDeviceSpecifier`. Otherwise it is `Just` an implementation-dependent string. You can use `allDeviceSpecifiers` to get a list of the known OpenAL devices.

Notes for Windows: There are 3 possible device strings, each having a deprecated equivalent for legacy applications only:

- `"Generic Hardware"` (legacy string: `"DirectSound3D"`)
- `"Generic Software"` (legacy string: `"DirectSound"`)
- `"Generic Software Fallback"` (legacy string: `"MMSYSTEM"`)

Notes for Linux\*nix:/ If an `.openalrc` file is present in the user's home directory, it is loaded first, otherwise `/etc/openalrc` is tried. The bindings (if any) of `devices`, `direction`, `sampling-rate`, and `speaker-num` (see below) after loading one of these files take precedence over any bindings done via the argument to `openDevice`.

The syntax of these files is lisp-based and a sequence of expressions, where an expression is one the following:

- A boolean value of the form `#f` or `#t`, which evaluate to false and true, respectively.
- An non-negative integer value, i.e. a sequence of decimal digits, evaluating to itself.
- A (signed) floating point value, as recoginzed by C's `atof()`, evaluating to itself.
- A pointer value of the form `#pnum`, where num can be an octal, decimal or hexadecimal value, as recoginzed by C`s `strtol()`, evaluating to itself. This kind of expression is currently unused.
- A string, i.e. a sequence of printable/whitespace characters between double quotes, evaluating to itself.
- A symbol, i.e. a sequence of almost all characters which don't form a simple expression like the ones mentioned below, e.g. `foo`, `bar1`, `3baz`, ... The symbol evaluates to the value currently bound to it.
- A function application of the form `(symbol expression...)`. The function bound to the symbol is applied to the evaluated arguments.
- A quotation of the form `(quote expression)` or `'expression`, evaluating to the unevaluated expression itself.
- A definition of the form `(define symbol expression)`, binding symbol to the value of expression. The whole expression evaluates to the value of expression, too.
- A conjunction of boolean expressions of the form `(and expression...)`. Each expression is evaluated in turn, and if one of them evaluates to false, the value of the whole expression is false. Otherwise the value is true.
- An extension loading mechanism of the form `(load-extension libraryName)`, where libraryName has to evaluate to a string. This tries to load the dynamic library with up to 3 special entry points: `alExtension_03282000` (pointing to a mandatory NULL-terminated sequence of pairs of pointers to names and extension functions), `alExtInit_03282000` (an optional initialization function), and `alExtFini_03282000` (an optional cleanup function). If the extension could be loaded successfully, the whole expression evaluates to true, otherwise to false.

Some symbols have a special meaning for OpenAL:

`devices`
  Has the form `(devspec...)`, where devspec is either a symbol/string specifying a device or `(device device-param...)`, specifying a device with additional parameters. These optional device parameters are stored in a variable `device-params`, but are currently unused. The first device which can successfully opened is used.
`direction`
  Type string or symbol: `"read"` specifies that the device should be an input device, everything else means output device (default).
`sampling-rate`
  Type integer or float: Specifies the internal mixing frequency, default is 44.1kHz.
`speaker-num`
  Type integer or float: Specifies the number of speakers, which can be 1, 2 (default), or 4.
`alsa-device`
  Type string, `alsa` backend only: Specifies both `alsa-out-device` and `alsa-in-device`, default `"plughw:0,0"`.
`alsa-out-device`
  Type string, `alsa` backend only: Specifies the ALSA output device, defaults to the value of `alsa-device`.
`alsa-in-device`
  Type string, `alsa` backend only: Specifies the ALSA input device, defaults to the value of `alsa-device`.
`native-in-device`
  Type string, `native` backend on IRIX only.
`native-out-device`
  Type string, `native` backend on IRIX only.
`native-rear-out-device`
  Type string, `native` backend on IRIX only.
`native-use-select`
  Type boolean, `native` backend on Linux only: If `#t`, wait up to 0.8sec for the device to become ready for writing. If `#f`, just try to write and hope it won't hang forever. The latter might be necessary for some drivers which don't implement `select()` , like some Aureal drivers.
`lin-dsp-path`
  Type string, `native` backend on Linux only: Path to DSP device for writing, tried before `/dev/sound/dsp` and `/dev/sound` if set.
`lin-dsp-read-path`
  Type string, `native` backend on Linux only: Path to DSP device for reading, tried before `/dev/sound/dsp` and `/dev/sound` if set. Defaults to the value of `lin-dsp-path`.
`native-backend-debug`
  Type boolean, `native` backend on Darwin only: If set to `#f`, be a bit verbose on stderr about what's going on in the backend.
`source-rolloff-factor`
  Type integer or float: Value of the initial rolloff factor for sources, default is `1.0`.
`listener-position`
  List of 3 integers or floats: Value of the initial listener position, default is `(0 0 0)`.
`listener-velocity`
  List of 3 integers or floats: Value of the initial listener velocity, default is `(0 0 0)`.
`listener-orientation`
  List of 6 integers or floats: Value of the initial listener orientation (at/up), default is `(0 0 -1 0 1 0)`.

The string given to `openDevice` has to be of the form `'((symbol expression) ...)`, which means basically a sequence of `define` expressions. Example:

     "'((sampling-rate 8000) (native-backend-debug #f))"

Note: The information above has been reverse-engineered from the OpenAL SI and could be inaccurate. Any corrections and/or additions are highly welcome.

closeDevice :: Device -> IO Bool | Source

`closeDevice` allows the application (i.e. the client program) to disconnect from a device (i.e. the server). It returns `True` for success and `False` for failure. Once closed, the `Device` is invalid. Note: Older OpenAL implementations will always report a success!

defaultDeviceSpecifier :: GettableStateVar (Maybe String) | Source

Contains `Just` the specifier string for the default device or `Nothing` if there is no sound support at all.

deviceSpecifier :: Device -> GettableStateVar String | Source

Contains the specifier string for the given device.

allDeviceSpecifiers :: GettableStateVar [String] | Source

Contains a list of specifiers for all available devices.
Produced by Haddock version 0.9